🛡️ code-airlock

Zero-trust PII & secret airlock for AI coding agents (Claude Code, OpenCode, Cursor, Windsurf, Cline).

code-airlock sits between your local codebase and LLM agents as both a FastMCP Server and an OpenAI-compatible SSE Proxy. It replaces live API keys, database passwords, and PII with reversible, session-consistent placeholders (<API_KEY_1>, <AUTH_TOKEN_1>, <PERSON_1>) before text enters LLM context—and restores them byte-exact on disk or inside child test processes without the AI ever seeing the raw values.

• Lightweight & Universal (~60 MB): Powered by a two-stage deterministic Regex + Pure ONNX Runtime (gliner_small-v2.1) cascade. No torch bloat, no GPU required, and 100% offline after initial model warmup.
• Sub-Millisecond Stage 1 (0.20 ms p50): Instant secret detection and Git pre-commit scanning.
• Safe Subprocess Execution (airlock_exec): Run pytest or scripts against live .env credentials while automatically scrubbing secrets from stdout and stderr before logs return to the agent.

⚡ Quickstart (Add to Your Agent Harness in 10 Seconds)

🤖 Tell Your AI Agent to Install It Automatically

Paste this into OpenCode, Claude Code, Cursor, or Windsurf:

Install https://github.com/sarthexe/code-airlock and register it as an MCP server.

Agent Execution Instructions (for LLMs reading this repo):

Run this single command to install code-airlock, warm up the ONNX model, register the MCP server in OpenCode/Cursor/Claude configs without overwriting existing keys, and initialize project guardrails:

pip install -U code-airlock && python -m code_airlock install

install merges into existing JSON configs (it never deletes other MCP servers), writes .cursorrules, CLAUDE.md, .airlock.toml, and installs the Git pre-commit hook when run inside a repository. Restart the agent afterward to load the seven airlock_* tools.

You can run code-airlock directly via uvx (zero install, no virtual environment needed) or install it globally via pip.

Option A: Zero-Install via uvx (Recommended)

1. Claude Code

claude mcp add code-airlock -- uvx code-airlock

2. OpenCode (~/.config/opencode/opencode.json)

{
  "mcp": {
    "code-airlock": {
      "type": "local",
      "command": ["uvx", "code-airlock"]
    }
  }
}

3. Cursor / Claude Desktop / Windsurf (.cursor/mcp.json)

{
  "mcpServers": {
    "code-airlock": {
      "command": "uvx",
      "args": ["code-airlock"]
    }
  }
}

Warm up the ONNX model & initialize your repository with uvx:

# 1. Pre-cache ONNX weights & run a 1-second round-trip self-test
uvx --from code-airlock python -m code_airlock doctor

# 2. Add agent rules (.cursorrules / CLAUDE.md), .airlock.toml, and Git pre-commit hook
uvx --from code-airlock python -m code_airlock init --pre-commit --config

Option B: Standard pip install

pip install code-airlock

# Verify installation & warm up local ONNX model cache
python -m code_airlock doctor

# Initialize project guardrails & Git pre-commit secret shield
python -m code_airlock init --pre-commit --config

claude mcp add code-airlock -- python -m code_airlock.mcp_server

{
  "mcp": {
    "code-airlock": {
      "type": "local",
      "command": ["python", "-m", "code_airlock.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "code-airlock": {
      "command": "python",
      "args": ["-m", "code_airlock.mcp_server"]
    }
  }
}

🛠️ How It Works in Your Daily Workflow

Once added to your harness and initialized via init --pre-commit, your coding agent automatically uses code-airlock for sensitive operations:

1. Reading & Refactoring Configs Safely (airlock_read_file & airlock_write_file):
   • You ask: "Read .env and generate a production docker-compose.yml."
   • The agent calls airlock_read_file(".env") and sees only:

     STRIPE_SECRET_KEY=<API_KEY_1>
     DATABASE_URL=postgres://admin:<AUTH_TOKEN_1>@10.0.4.12:5432/prod
     

   • The agent writes the new file using <API_KEY_1> and <AUTH_TOKEN_1> via airlock_write_file(). code-airlock rehydrates the real secrets onto disk behind the scenes.
2. Running Tests Without Leaking stdout (airlock_exec):
   • You ask: "Run pytest using .env to verify the Stripe webhook."
   • The agent calls airlock_exec(command=["pytest", "-v"], env_file=".env").
   • code-airlock injects the real credentials into the child process memory, executes the test, and scrubs any secret values printed in stdout or stderr back into <API_KEY_1> before returning the output to the LLM.
3. Blocking Accidental Git Commits (scan --staged):
   • Whenever you or the agent runs git commit, the pre-commit hook runs python -m code_airlock scan --staged in 0.20 ms, blocking any staged file that contains a live credential.

🧰 Complete MCP Toolkit (7 Tools)

Built-In Security Guardrails

• Workspace & System Folder Jailing: Blocks path traversal and sensitive directories (.ssh, .aws, .gnupg, .kube, /etc, System32). Set AIRLOCK_WORKSPACE=/path/to/repo to strictly jail file operations to a single directory.
• Hallucination-Safe Write Gate: If an LLM invents a non-existent token (e.g., <API_KEY_999>), airlock_write_file refuses to write a broken file and returns an unresolved_tokens error so the agent can self-correct.
• Forgiving Rehydration: Automatically resolves LLM casing or spacing variations (<api_key_1> or < API_KEY_1 >).
• Crash-Safe Memory Hygiene: VaultSession.__repr__ and __str__ never expose raw secrets in stack traces or crash logs.
• Binary & Size Caps: Rejects non-UTF-8 binary files (\x00) and files over 1 MB.

💻 CLI Reference

python -m code_airlock                 # Start FastMCP stdio server (default)
python -m code_airlock install         # Register MCP configs, init guardrails, warm up model
python -m code_airlock doctor          # Warm up ONNX model, run self-test & print IDE configs
python -m code_airlock init            # Add agent rules to .cursorrules and CLAUDE.md
python -m code_airlock init --pre-commit --config  # Also install Git hook + starter .airlock.toml
python -m code_airlock scan src/       # Fast Stage-1 secret scan across paths (0.20ms/file)
python -m code_airlock scan --staged   # Scan staged Git changes (exits 1 on findings, masks preview)
python -m code_airlock scan --deep .   # Deep scan with Stage 1 + Stage 2 ONNX NER
python -m code_airlock proxy           # Launch OpenAI-compatible SSE proxy on :8000

⚙️ Project Configuration (.airlock.toml)

Drop an .airlock.toml file in your project root (or generate one via python -m code_airlock init --config) to define custom Stage 1 regex rules and Stage 2 allowlists for your team:

[allowlist]
terms = ["MyInternalApp", "staging.corp.local"]

[custom_patterns]
EMPLOYEE_ID = 'EMP-[0-9]{6}'
INTERNAL_TICKET = 'JIRA-[0-9]{4,6}'

• [custom_patterns]: Evaluated in Stage 1 (~0.20 ms) and mapped to reversible tokens (<EMPLOYEE_ID_1>, <INTERNAL_TICKET_1>).
• [allowlist]: Prevents domain-specific terms or internal hostnames from being flagged by Stage 2 NER.

🌐 OpenAI-Compatible SSE Proxy Mode

Need network-level protection for any OpenAI SDK client or custom agent pipeline? Run the streaming HTTP proxy:

code-airlock-proxy
# Or: python -m code_airlock proxy

Point your client's OPENAI_BASE_URL to http://localhost:8000/v1 and set UPSTREAM_BASE_URL (defaults to https://api.openai.com).

• Outbound: Scrubs all messages in POST /v1/chat/completions before forwarding upstream.
• Inbound Streaming (StreamRehydrator): Buffers only inside open <...> brackets across arbitrary network chunks (even 1-byte SSE splits) and restores secrets on the fly with zero latency on regular text.

📊 Benchmarks (sarthexe/pii-airlock-bench)

Evaluated on the open 4-split benchmark dataset (sarthexe/pii-airlock-bench) covering 2,000 rows, 5,817 entity spans, 250 hard negatives (UUIDs, Git SHAs, dummy placeholders, localhost IPs, CLI flags), and 1/2/7-byte adversarial SSE stream splits:

• Stage 1 Latency (Regex + URI/Key-Value Heuristics): 0.203 ms p50
• Stage 2 Latency (Pure ONNX CPU gliner_small-v2.1): 55.20 ms p50 (CUDAExecutionProvider automatically used when onnxruntime-gpu is present)

Reproduce locally:

python benchmarks/benchmark.py --suite all

📄 License

MIT © Sarthak Kumar Maurya