Security

Defense-in-depth for autonomous agents handling real money.

8-Point Security Audit

forge security-check . --harden

Kill Switch

One command stops everything:

forge halt .
# Kill switch ACTIVE
# All x402 calls blocked
# All live operations blocked
# All MCP tool calls blocked
 
forge resume .
# Kill switch CLEARED

The halt file is checked before every capability execution — not just x402.

Prompt Injection Detection

12 compiled patterns scanning for:

• Role impersonation
• Jailbreak attempts
• Delimiter injection
• Hidden content
• Base64 payloads
• Zero-width unicode

All capability results (MCP, A2A, HTTP) pass through InputSanitizer.scan() before entering the planner prompt.

Encrypted Backups

• Cipher: AES-256-GCM
• KDF: scrypt (n=2^16, r=8, p=1)
• Permissions: 0600
• Mnemonic never stored in plaintext

Budget Circuit Breakers

• Per-call, per-session, and per-day spending caps
• Atomic file locking (fcntl.flock) prevents race conditions
• Track spending velocity, auto-pause on anomalies

Environment Tiers

Side-effecting capabilities default to deny until policy explicitly allows.

MCP Security

• Subprocess env var filtering — secrets never leak to MCP servers
• Policy gate applies to all MCP tool calls
• Kill switch blocks MCP alongside everything else

Prompt Injection Patterns

The InputSanitizer scans all external input (MCP results, A2A messages, HTTP responses) before they enter the planner prompt. Detected patterns:

When a pattern is detected, the result is sanitized (suspicious content removed) and a warning is logged. The agent never sees the injected content.

Wallet Security Model

┌─────────────────────────────────────────────┐
│  Owner (you)                                │
│  - Holds passphrase                         │
│  - Can export/backup mnemonic               │
│  - Full wallet control                      │
│                                             │
│  ┌─────────────────────────────────────┐    │
│  │  Agent (scoped access)              │    │
│  │  - Has API key (ows_key_...)        │    │
│  │  - Can sign transactions            │    │
│  │  - CANNOT see owner passphrase      │    │
│  │  - CANNOT export mnemonic           │    │
│  │  - Chain-restricted (e.g., Base)    │    │
│  │  - Per-tx and per-day spending caps │    │
│  └─────────────────────────────────────┘    │
│                                             │
│  .env (0600)     — OWS_API_KEY only         │
│  .ows/ (0700)    — encrypted vault          │
│  wallet.json     — public addresses only    │
└─────────────────────────────────────────────┘

Halt File Deep Dive

The halt file is a simple filesystem-level kill switch. When present, the runtime checks it before every single capability execution — not just x402 payments.

# How the runtime checks:
def _check_halt(agent_dir):
    halt_path = Path(agent_dir) / "halt"
    if halt_path.exists():
        reason = halt_path.read_text().strip() or "no reason given"
        raise HaltError(f"Agent halted: {reason}")

# Create halt file with reason
forge halt ./my-agent --reason "suspicious activity detected"
 
# The file is just a text file:
cat ./my-agent/halt
# suspicious activity detected
 
# Remove it to resume
forge resume ./my-agent

Atomic Budget Locking

Budget checks and updates are wrapped in an exclusive file lock to prevent race conditions (e.g., two ticks executing simultaneously):

import fcntl
 
lock_path = agent_dir / "x402_state.lock"
with open(lock_path, "w") as lock_file:
    fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
    # Read budget state
    state = load_x402_state()
    # Check caps
    if state.session_spent + amount > config.max_session_usd:
        raise BudgetExceeded("Session cap reached")
    # Execute payment
    result = execute_payment(...)
    # Update state atomically
    state.session_spent += amount
    save_x402_state(state)
    # Lock released on exit

Security Audit Checklist

When preparing for production:

1. forge security-check . --harden passes all 8 checks
2. .env has 0600 permissions
3. .ows/ vault has 0700 permissions
4. .gitignore excludes .env, .ows/, replays/
5. No API keys or mnemonics in committed files
6. x402 budget caps are set (not unlimited)
7. Policy bundle restricts live capabilities to approved environments
8. Kill switch tested: forge halt . && forge resume .
9. Encrypted backup exists: forge wallet-backup .
10. A2A rate limiting is active (default: 60/min)