Skip to content

Security_Guide.md

Latest commit

 

History

History
87 lines (53 loc) · 4.21 KB

Security_Guide.md

File metadata and controls

87 lines (53 loc) · 4.21 KB

Security Guide

This document matches **alpha_agent/security/** and **alpha_agent/cli/chat.py** as of the current codebase. For CLI flags see CLI_Reference.md.

Architecture

Component Role
FilesystemGuard Resolves paths inside the workspace; blocks traversal outside sandbox.
CommandPolicy Classifies shell strings: **CommandVerdict.SAFE**, **CONFIRM**, **BLOCK\*\*.
TerminalGuard Applies policy + SecurityMode; runs subprocess with workspace cwd; logs via AuditLogger.
AuditLogger Appends JSON lines to **workspace/logs/audit.log**.

There is no separate “WARN” verdict in code: unknown commands fail-closed to **CONFIRM**.

Command tiers (CommandPolicy)

Evaluation order:

  1. BLOCK - first match wins; no mode can override.
  2. CONFIRM - network installs, curl/wget, git clone / checkout / merge / rebase / reset, file copies/moves, etc. (see command_policy.py patterns).
  3. SAFE - interpreters, read-only git status/log/diff/branch/show/stash list, ls, cat, etc.
  4. Anything unmatched → CONFIRM.

Examples of BLOCK (non-exhaustive): rm, sudo, chmod, git push, git remote, kill, many package install subcommands, dd, etc.

Security modes (SecurityMode)

Mode SAFE CONFIRM BLOCK
safe Run Preview + y/N Reject
dev Run Preview + y/N except narrow git auto-approve (below) Reject
unrestricted Run Auto-run + audit (auto_approved_unrestricted) Reject

Switch at launch: **alpha-agent chat --mode**. Mid-session: **/mode**replaces**SecurityManager**immutably and logs**security_mode_change\*\* on the audit logger (with session id preserved).

DEV mode auto-approve (implemented)

Applies only when **classify(command) == CONFIRM**.

Allowed auto-approval (must match a allowlist regex and no exclusion regex):

  • Commands that look like leading **git clone**.
  • Commands that look like leading **git checkout** to switch branches/ref without dangerous flags.

Exclusions (not auto-approved) include: git push, git merge, git rebase, git reset, git commit, git remote, --hard, --force, -f as a token, git checkout -b/-B, --orphan, --merge, checkout with -- path syntax, etc. (see **DEV_AUTO_APPROVE_EXCLUSIONS** in **command_policy.py\*\*).

Audit: event **terminal_cmd** with decision **auto_approved_dev_git_readonly**, plus command, verdict, mode, agent. The console prints a dim line: **DEV: auto-approved → …\*\*.

Not auto-approved: curl, pip install, cp, git merge, … - still CONFIRM with prompt (unless unrestricted).

Workspace boundaries

  • Working directory for **run_terminal_cmd** is the workspace root passed into **TerminalGuard**(typically**config.workspace\*\*).
  • File tools use FilesystemGuard on the same workspace root.

Audit log

  • Path: ~/.alpha-agent/workspace/logs/audit.log
  • Format: one JSON object per line (ts, event, optional session, plus event-specific fields).
  • Terminal: event = terminal_cmd; filesystem events use dedicated event types from **AuditLogger**.

/audit (in chat)

Reads **audit.log**, prefers lines whose **session** matches the current chat session; falls back to all lines if none match. Displays time, event, target, result/allowed, session short id.

Further reading