TripWire

TripWire is a sandbox-first prototype of a command safety layer for MCP-compatible coding agents. It protects only commands sent through its safe_exec MCP tool; it is not host-wide enforcement and cannot protect an agent that bypasses the tool.

Safety model

• Commands execute only in the configured, marker-protected demo sandbox.
• Safe read/test commands run immediately. Known destructive commands and shell/parser evasions are blocked.
• Unresolved environment, command, and home-directory expansion syntax (including $HOME, %USERPROFILE%, !HOME!, $env:HOME, $(...), ~, and ~/...) is a policy violation even for an otherwise harmless command such as ls $HOME. This is deliberate: TripWire detects syntax but does not resolve shell-dependent paths.
• Test/seed/cleanup operations that target a production-marked URL or connection string are blocked when destructive, or held for human review when lower-confidence. Built-in production markers are always active; TRIPWIRE_PRODUCTION_MARKERS can add comma-separated private markers. This is heuristic detection only: an unlabelled production resource that matches no known marker cannot be identified by this layer.
• Ambiguous commands enter a bounded GPT-5.6 Terra tool-calling loop in live mode, or a visibly labelled deterministic fixture in demo mode. The live agent may only request get_context and snapshot_state; it has no execution, rollback, cache, audit, or rule-writing authority. A model allow/flag result always waits for human approval.
• A workspace tarball and SQLite backup are created before a pending mutation or cached mutation runs. Rollback is explicit.
• Human review is two-step: authorization creates a short-lived, signed confirmation capability; only an explicit confirmation consumes it and starts execution. A dashboard disconnect before confirmation leaves the command unexecuted. Once confirmation is accepted, execution is authoritative even if the browser loses its response.
• The local JSONL audit log is hash chained and validated by the dashboard. It is tamper-evident, not immutable.
• After an escalated incident is logged, the agent drafts a short dashboard report. Repeated normalized patterns may produce a cache proposal, but a human must explicitly accept it. Proposals never edit safety rules and accepting one starts no command.

Run the judge demo

export TRIPWIRE_API_KEY="replace-with-a-long-random-local-secret"
docker compose up --build

Open http://localhost:8000, enter the same API key to unlock the dashboard, then approve the seeded touch agent-note.txt replay and roll it back. The dashboard seeds replay incidents in its own process, so pending commands remain approvable. The Compose profile runs as a non-root user with a read-only root filesystem, dropped Linux capabilities, resource limits, and required Landlock enforcement. Docker Desktop with WSL2 and a Landlock-capable Linux kernel are required; the service refuses protected execution when its Landlock probe fails. It also records two non-executing risk-taxonomy examples: rm -rf ~ and a synthetic test cleanup aimed at a production-marked database URL. Credentials in connection strings are redacted from the dashboard, audit record, and model prompt.

For a real reasoning call, set TRIPWIRE_MODE=live and OPENAI_API_KEY; no missing-key fallback is allowed in live mode.

Run the shipped test suite in the same image with:

docker compose run --rm --entrypoint pytest tripwire

Run the scripted acceptance scenario used for a fast judge check with:

docker compose run --rm --entrypoint python tripwire scenario_runner.py

It proves the safe, destructive, human-review, approval, rollback, cached-verdict, model-failure, and audit-chain paths in a fresh temporary sandbox. The interactive dashboard replay remains the best route for the visual demo.

MCP configuration

Add this to the Codex configuration appropriate to your machine, then start the dashboard separately with tripwire-dashboard:

[mcp_servers.tripwire]
command = "tripwire-mcp"

[mcp_servers.tripwire.env]
TRIPWIRE_MODE = "demo"
TRIPWIRE_SANDBOX_ROOT = "./demo/workspace"
TRIPWIRE_STATE_ROOT = "./demo/state"
TRIPWIRE_API_KEY = "replace-with-a-long-random-local-secret"
TRIPWIRE_APPROVAL_KEY = "same-long-random-local-secret-or-a-separate-shared-secret"

The MCP server exposes safe_exec(command, cwd, intent) and rollback(snapshot_id). safe_exec is the integration boundary: do not expose a raw shell tool alongside it for a safety demonstration. The dashboard and MCP process must share TRIPWIRE_SANDBOX_ROOT, TRIPWIRE_STATE_ROOT, and TRIPWIRE_APPROVAL_KEY. Every pending mutation is persisted as an HMAC-bound, one-time record tied to its exact canonical command, cwd, sandbox root, snapshot, expiry, and nonce; dashboard approval consumes it once.

Development

python -m pip install -e ".[dev]"
pytest
tripwire-demo

The project intentionally rejects redirection, pipelines, command substitution, encoded payloads, network/cloud tooling, executable paths, unsupported flags, path operands outside the sandbox, and symlink operands. pytest and git are review-required because they can execute repository-controlled behavior. Those restrictions make the demo boundary inspectable; production enforcement needs stronger isolated workers in addition to this application layer.

Execution integrations

The integrations/ directory contains the next product layer:

• terminal/: Bash and PowerShell tw wrappers that preflight or submit commands to a running local gateway. They enforce only commands deliberately routed through tw; MCP cannot intercept arbitrary shell input on its own.
• cursor-extension/: an experimental Cursor/VS Code protected-terminal prototype. The packaged .vsix is included for development evaluation, but is not the primary judge or video path for this submission.
• antigravity/: a workspace plugin that installs the local MCP server and a rule directing agent command calls to safe_exec.
• replit/: deployment instructions for the authenticated Streamable HTTP policy gateway. It exposes preflight_command and is advisory until Replit offers a non-bypassable execution hook.

Local fallback (unprotected demo)

If Docker Desktop cannot start the protected stack, the approval, audit, snapshot, and rollback demo can run directly from a local terminal. This mode does not provide Docker or Landlock execution isolation and must not be presented as protected execution.

From the repository root in VS Code or PowerShell:

.\scripts\run-local-demo.ps1

The script prints a one-time API key and starts a localhost-only dashboard at http://127.0.0.1:8000. Enter that key in the dashboard. Press Ctrl+C in the same terminal to stop it.

VS Code demo path

The submission demo uses VS Code as the local development environment and the browser dashboard as the approval surface; it does not rely on the experimental VSIX. Open the repository folder in VS Code, run Tasks: Run Task → TripWire: Start local demo, and choose a local dashboard key when prompted. The task disables Docker Compose Bake (a Docker Desktop compatibility workaround), starts the protected stack, and seeds the dashboard. Open http://127.0.0.1:8000, enter the same key, then run the approval-and-rollback walkthrough in docs/VIDEO_DEMO.md.

Security validation

Run the deterministic validation report with python scripts/security_report.py. The Docker/Landlock, live GPT-5.6, Cursor/Codex, and Railway validation procedures are in docs/SECURITY_VALIDATION.md. Live validation is opt-in, uses a disposable sandbox, requires current input/output rate values, and defaults to a US$5 estimated-cost ceiling.

For a fast evaluation walkthrough, see the judge guide.

For a judge-run live GPT-5.6 validation, copy .env.example to .env, enter a dedicated revocable API key and the current input/output rates, then explicitly set TRIPWIRE_TEST_LIVE=1. Run python scripts/live_validation.py. The runner loads that local file without overriding shell/CI variables, never confirms a mutation, and writes a redacted latency, usage, tool-call, and estimated-cost report. .env is gitignored and is used by this validation runner only; it does not silently switch the Docker dashboard out of demo mode.