# 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

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

```bash
docker compose run --rm --entrypoint pytest tripwire
```

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

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

```toml
[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

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

```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](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](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](docs/JUDGE_GUIDE.md).

For a judge-run live GPT-5.6 validation, copy [`.env.example`](.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.