🛡️ Code-Airlock

Low-Latency AI Privacy, Secret/PII Redaction & Streaming Rehydration Gateway (OpenAI Proxy + FastMCP Server)

code-airlock is a zero-trust privacy layer for LLMs and agentic coding harnesses. It intercepts sensitive credentials, financial identifiers, and personal data before they leave your machine, replaces them with deterministic session tokens (<API_KEY_1>, <PERSON_1>), and seamlessly rehydrates them back into real-time Server-Sent Events (SSE) token streams or local file writes.

• Dual Deployment Modes: Run as a drop-in OpenAI-compatible /v1/chat/completions reverse proxy or as a Model Context Protocol (MCP) server (stdio) for OpenCode, Cursor, and Claude Code.
• 2-Stage Hybrid Cascade: Combines sub-millisecond deterministic regex + mathematical checksums (Luhn, Verhoeff $D_5$, ISO 7064 MOD-97) with contextual neural NER (onnx-community/gliner_small-v2.1 on ONNX Runtime) and a curated developer allowlist.
• Deterministic Secret Coverage: Stage 1 also captures inline connection-string passwords and PASSWORD / SECRET / ACCESS_TOKEN / API_KEY assignments, excluding placeholders, booleans, function calls, and existing vault tokens.
• Git & CI Guardrails: code-airlock scan --staged catches secrets in staged files at sub-millisecond Stage 1 speed, masks every value in output, and installs a .git/hooks/pre-commit gate via init --pre-commit.
• Safe Agent Execution: airlock_exec injects real .env values into a guarded subprocess (shell=False) and scrubs both stdout and stderr before returning them to the model.
• Project-Aware Rules: .airlock.toml adds team allowlist terms and custom Stage-1 regexes such as EMPLOYEE_ID = 'EMP-[0-9]{6}'.
• Zero-Delay Streaming Rehydration: Stateful sliding-window SSE parser reassembles split tokens across arbitrary 2-byte network chunks without delaying code comparison or bitwise operators (<, <<, template <typename T>).
• Minimalist Systems Footprint: ~850 lines of core runtime code (engine.py, onnx_ner.py, sanitizer.py, proxy.py, mcp_server.py, scanner.py, config.py, executor.py) plus a deterministic 2,000-row benchmark harness. One universal install — no PyTorch, no CUDA toolkit.

🏗️ System Architecture

flowchart TB
    classDef client fill:#1e293b,stroke:#64748b,stroke-width:2px,color:#f8fafc
    classDef stage1 fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#ecfdf5
    classDef stage2 fill:#1e3a8a,stroke:#3b82f6,stroke-width:2px,color:#eff6ff
    classDef merger fill:#312e81,stroke:#8b5cf6,stroke-width:2px,color:#f5f3ff
    classDef vault fill:#7c2d12,stroke:#f97316,stroke-width:2px,color:#fff7ed
    classDef stream fill:#4c1d95,stroke:#a855f7,stroke-width:2px,color:#faf5ff

    Client(["🖥️ Client SDK / Agent Harness<br/>(OpenAI SDK, OpenCode, Cursor, Claude Code)"]):::client

    subgraph Airlock["🛡️ CODE-AIRLOCK (proxy.py / mcp_server.py)"]
        direction TB
        subgraph Cascade["engine.py — 2-Stage Hybrid Cascade"]
            S1["⚡ Stage 1: Deterministic Fast-Pass (~0.44ms)<br/>• Regex: API_KEY, AUTH_TOKEN, EMAIL, PHONE, IPv4<br/>• Checksums: Luhn (Card), Verhoeff (ID), MOD-97 (IBAN)"]:::stage1
            S2["🧠 Stage 2: Guarded Neural NER (GLiNER-small · ONNX)<br/>• Entities: PERSON, ORGANIZATION, LOCATION<br/>• Guards: 93-term TECH_ALLOWLIST + Code/Pronoun Filter"]:::stage2
            Merger{"⚖️ Span Conflict Resolver<br/>Stage 1 Overrides Stage 2<br/>Longest Span Wins"}:::merger
            S1 & S2 --> Merger
        end

        Vault[("🗄️ Ephemeral Session Vault<br/>sanitizer.py (VaultSession)<br/>Right-to-Left Tagging")]:::vault
        Rehydrator["🪟 StreamRehydrator<br/>Stateful Sliding-Window SSE & File Parser"]:::stream

        Merger --> Vault
        Vault -.->|"O(1) Token Lookup"| Rehydrator
    end

    LLM(["☁️ Upstream LLM Provider<br/>*Sees Only &lt;ENTITY_n&gt; Tokens*"]):::client

    Client -->|"1. Raw Prompt / File Read"| Cascade
    Vault -->|"2. Sanitized Payload"| LLM
    LLM -->|"3. Fragmented SSE Stream / Tool Patch"| Rehydrator
    Rehydrator -->|"4. Restored Plaintext"| Client

📊 Gold-Set Benchmark (benchmarks/gold_set.jsonl)

Evaluated on 285 developer prompts (sampled from CodeAlpaca_20K and OpenCodeInstruct with injected .env blocks, ticket escalations, billing metadata, and C++ template syntax) totaling 744 ground-truth PII spans across 11 categories:

• Hard-Negative Suite: 61/61 Passed (100% rejection of non-Luhn 16-digit order IDs, Verhoeff-invalid 12-digit numbers, MOD-97-invalid IBANs, and v192.168.1.300 version strings).
• Tech Allowlist Check: 30/30 Passed (FastAPI, Docker, Kubernetes, Redis, Postgres, AWS, Heroku, etc. produce zero false positives).

🧪 Unified 2,000-Row Benchmark Matrix

benchmarks/build_benchmarks.py deterministically generates four stratified splits into the git-ignored benchmarks/ directory (seed=42). benchmarks/benchmark.py evaluates them and writes benchmarks/BENCHMARK_RESULTS.md.

Reference result (strict exact-span matching, code-airlock v1.4.0 on CPU ONNX Runtime):

• Latency (CPU ONNX Runtime): 0.203 ms p50 / 0.433 ms p95 Stage 1; 55.201 ms p50 / 132.592 ms p95 Stage 2; 55.302 ms p50 / 132.668 ms p95 total cascade. GPU execution automatically uses CUDAExecutionProvider when available.
• Per-entity support: API_KEY 756, AUTH_TOKEN 467, CREDIT_CARD 440, EMAIL 754, PHONE 465, IP_ADDRESS 442, GOVT_ID 465, IBAN_CRYPTO 465, PERSON 729, ORGANIZATION 417, LOCATION 417. Every entity is at 100% P/R/F1.
• Invariants: MCP JSON parse 100/100, JSON round-trip 100/100, adversarial SSE 2,000/2,000, hard negatives 250/250, clean rows 350/350 with zero false positives.

These are synthetic, template-composed fixtures, so the perfect headline is a regression/invariant result, not a claim of real-world accuracy. The older real-world suites (benchmarks/gold_set.jsonl: 96.7/99.1/97.9; Gitleaks artifacts: 100/88.5/93.9) remain the honest field tests.

🤗 Published Dataset

One command publishes all four splits and the auto-generated card:

python benchmarks/export_hf.py --repo-id sarthexe/pii-airlock-bench

Dataset: sarthax/pii-airlock-bench (the token owner namespace is resolved automatically).

from datasets import load_dataset
ds = load_dataset("sarthax/pii-airlock-bench")

🚀 Quickstart & MCP Setup

Option 1: Zero-Install via uvx (Recommended)

No cloning, manual virtual environments, or path debugging. Anyone with Astral's uv can run code-airlock directly from PyPI:

🤖 Claude Code (CLI)

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

💻 OpenCode (opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "code-airlock": {
      "type": "local",
      "command": ["uvx", "code-airlock"],
      "enabled": true
    }
  }
}

🖱️ Cursor (.cursor/mcp.json)

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

🖥️ Claude Desktop (claude_desktop_config.json) & Windsurf (~/.codeium/windsurf/mcp_config.json)

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

(You can also run directly from source via uvx --from git+https://github.com/sarthexe/code-airlock code-airlock).

For a local editable checkout, use the package entrypoint instead of an absolute path:

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

python -m code_airlock starts the same MCP server.

Option 2: Local Development / Manual Git Clone

git clone https://github.com/sarthexe/code-airlock.git
cd code-airlock
pip install -e ".[dev,benchmark]"

# Optional: GPU inference (ONNX Runtime otherwise uses the CPU provider)
pip install onnxruntime-gpu

# Test tools locally over stdio
python -m code_airlock

# Or run the explicit MCP entrypoint
code-airlock-mcp

Zero-Friction CLI

python -m code_airlock doctor              # model warmup + round-trip + MCP config
python -m code_airlock init                # add rules to .cursorrules / CLAUDE.md
python -m code_airlock init --pre-commit   # also install .git/hooks/pre-commit
python -m code_airlock init --config       # create a starter .airlock.toml
python -m code_airlock scan --staged       # fast Stage 1 scan of staged files
python -m code_airlock scan --deep src/    # add ONNX GLiNER detection for a path
python -m code_airlock proxy               # start the HTTP proxy
python -m code_airlock                     # start the MCP server (default)

Installed entrypoints: code-airlock-mcp, code-airlock-proxy, and the backward-compatible code-airlock alias.

scan skips binaries, files over 1 MB, tests/, and benchmark fixtures. It prints file:line -> [CATEGORY] masked-preview and exits 1 when secrets are found, so it works unchanged in CI and Git hooks. --deep enables Stage 2 NER; the default Stage 1 path is sub-millisecond. init is idempotent, and init --pre-commit installs a hook that runs python -m code_airlock scan --staged.

🧰 MCP Tools

All file tools resolve paths with Path.expanduser().resolve() and jail access to AIRLOCK_WORKSPACE when that variable is set. Rehydration is tolerant of <api_key_1> / < API_KEY_1 >, while the SSE StreamRehydrator remains zero-delay and exact.

airlock_exec is designed for safe test runs:

airlock_exec(
    [sys.executable, "-c", "import os; print(os.environ['STRIPE_SECRET_KEY'])"],
    ".env",
)
# stdout: "<API_KEY_1>"  ← the real key never reaches the model

⚙️ Project Config (.airlock.toml)

Create a starter with python -m code_airlock init --config, or write one manually. CascadeEngine loads .airlock.toml from the current directory, or from AIRLOCK_CONFIG when set:

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

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

• Allowlist terms are merged into the Stage 2 allowlist so they are not misclassified as PERSON, ORGANIZATION, or LOCATION.
• Custom patterns run in Stage 1 alongside built-in rules and produce <EMPLOYEE_ID_n> / <INTERNAL_TICKET_n> vault tokens.
• Invalid regexes and malformed labels are ignored rather than crashing the engine.

Option 3: OpenAI-Compatible Reverse Proxy (/v1/chat/completions)

Run as a transparent privacy gateway intercepting HTTP requests:

# Run with built-in zero-leak mock upstream (offline validation)
code-airlock-proxy

# Or point to a live upstream provider (OpenAI, Ollama, OpenRouter, vLLM)
export AIRLOCK_UPSTREAM_URL="https://api.openai.com"
code-airlock-proxy

The proxy binds to 127.0.0.1:8000 by default. Override with AIRLOCK_HOST / AIRLOCK_PORT.

🧠 Guiding Your Agent (.cursorrules / System Prompt)

To ensure your coding agent actually leverages the airlock tools instead of raw file reads, include this rule in your .cursorrules, CLAUDE.md, or system instructions:

# Code-Airlock Agent Guardrails
1. When reading `.env`, configuration, or log files, NEVER use standard read tools. ALWAYS call `airlock_read_file(path)` so secrets and PII are redacted into `<ENTITY_n>` tokens before hitting context.
2. When creating or editing configs, write the `<ENTITY_n>` tokens directly and call `airlock_write_file(path, content)`. The airlock will rehydrate the real secrets locally on disk without ever sending them through the LLM.
3. Call `airlock_vault_status()` to inspect active pseudonymized tokens safely (never returns plaintext values).

📁 Repository Structure

🔐 Security

Detection is best-effort and local-only. It reduces exposure but is not a guarantee that every secret is removed. See SECURITY.md for the threat model, known gaps, and private disclosure instructions.

The MCP file tools additionally block sensitive directories (~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, /etc, System32), files over 1 MB, binary files, and paths outside AIRLOCK_WORKSPACE when that variable is set. Writes containing unresolved or hallucinated <ENTITY_N> tokens are refused.

code-airlock scan --staged adds a Git pre-commit gate for the five highest-risk secret categories (API_KEY, AUTH_TOKEN, CREDIT_CARD, GOVT_ID, IBAN_CRYPTO). It prints masked previews only and exits non-zero on findings.

📜 License

MIT © 2026 Sarthak Maurya. See LICENSE.