convez.ai
AgenteSegurançaAvançado
Iskz17

Airlock — Guarda de Segurança para Agents

Iskz17/airlock

Defesa em camadas contra prompt injection e agent hijacking

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework em camadas para defesa contra injeção de prompts e comprometimento de agents. Monitora seis fronteiras críticas (ingresso, ação, egresso, persistência, cadeia de suprimentos e alinhamento) com detecção offline de Unicode invisível, injeção oculta via ML local e roubo de dados. Integra-se com Claude Code e openclaw.

Instalação

$npx convez-ai Iskz17/airlock

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.2.3
Issues abertas
0
Contribuidores
2

Casos de uso

  • Proteger agents contra injeção de prompts invisíveis e ocultas
  • Detectar e bloquear exfiltração de segredos/PII antes de saírem
  • Validar alinhamento de ação antes de ferramentas sensíveis executarem
  • Evitar envenenamento de memória/RAG por escrita maliciosa

Veredito

Solução robusta e bem pensada para hardening de agents em produção. Arquitetura em camadas com defesa offline como padrão (sem deps pesadas) e detecção ML opcional. Ideal para aplicações críticas que precisam de confiança real contra ataques sofisticados.

README

A tradução para o português deste README ainda está na fila.

airlock

CI  license: MIT  python: 3.9+

A layered prompt-injection / agent-security guard with a shared core and thin per-harness adapters (Claude Code + openclaw), organized around the agent's trust boundaries — ingress, action, egress, persistence, and supply chain — with a graceful offline ladder. The lesson behind the design (cf. EchoLeak / CVE-2025-32711): a single input classifier gets bypassed, so the defense is layered across boundaries.

What it catches

Ingress (content entering context):

  • Invisible-Unicode / ASCII smuggling (Stage 0): Unicode Tag block (U+E0000–E007F), zero-width, bidi overrides, supplementary variation selectors. Hidden payloads are decoded and surfaced, not silently dropped. Offline, deterministic, high precision.
  • Overt injection (Stage 1): high-precision regex for assistant-directed instructions ("ignore previous instructions", exfiltration asks, role hijacks, …). Offline.
  • Subtle/obfuscated injection (Stage 2): an ungated, openly-licensed ML classifier (protectai/deberta-v3-base-prompt-injection-v2, Apache-2.0) — no account or login. Local model, no per-request network. Meta Prompt Guard 2 is available as an opt-in backend (AIRLOCK_STAGE2_BACKEND=promptguard).
  • Multimodal (Stage 2b): OCR an ingested image/screenshot → feed extracted text (incl. low-contrast/hidden) back through Stages 0–2. Optional deps (pytesseract/Pillow); mainly for browser/computer-use agents.

Action (before the agent acts):

  • Task-drift / AlignmentCheck (Stage 3): before a sensitive/outbound tool runs, audit whether the agent is still serving the user's original request vs. a hijacked goal (LlamaFirewall scan_replay). Needs an LLM judge (Together / Ollama); silent no-op otherwise.

Egress (content leaving — the EchoLeak defense):

  • Exfiltration guard (Stage 4): blocks secrets/PII and Markdown-URL exfil sinks from leaving via outbound tools (WebFetch/Bash) or the final reply. PreToolUse gate defaults to ask; mostly offline, optional Presidio PII.

Persistence (writes to long-term memory):

  • Memory-write guard (Stage 5): re-runs ingress on content being written to a memory/RAG sink (CLAUDE.md, memory/, …) so a poisoned write can't persist and re-attack future sessions (AgentPoison / Morris-II).

Supply chain (installed MCP servers):

  • MCP vetting (Stage 6): offline tool-poisoning detection on tool/parameter descriptions (hidden <IMPORTANT> directives, invisible-Unicode, "read ~/.ssh / don't tell the user") + remote-code install-vector checks on server launch commands; optional mcp-scan enrichment (AIRLOCK_MCP_SCAN=1).

Install (Claude Code)

# Load for the current session (runs from this repo in place):
claude --plugin-dir /Users/iskandarzulkarnain/airlock/adapters/claude-code

Which stages are on, and how to enable the rest

Install airlock and you're immediately protected at every boundary, fully offline — the stdlib stages need nothing. The heavier detectors are opt-in. Here's the whole picture at a glance:

StageBoundaryOn by default?How to enable
0 invisible-Unicodeingress✅ on— (stdlib, offline)
1 heuristicsingress✅ on— (stdlib, offline)
2 ML injection classifieringress⬜ opt-in/airlock-setup (or promptguard) — pulls PyTorch + an ungated, openly-licensed model. No account/login/subscription.
2b image OCRingress⬜ opt-in/airlock-setup ocr + system tesseract (brew install tesseract)
3 AlignmentCheck (task drift)action⬜ opt-inlocal Ollama — open, no key/subscription: AIRLOCK_ALIGN_BACKEND=ollama + ollama pull qwen2.5:7b (or Together via TOGETHER_API_KEY). Use a 7B+ judge — 3B models false-positive (see below).
4 egress exfil (secrets + MD sinks)egress✅ on— (stdlib, offline)
4 richer PII (Presidio)egress⬜ opt-in/airlock-setup pii + AIRLOCK_EGRESS_PII=1
5 memory-write guardpersistence✅ on— (stdlib, offline)
6 MCP vetting (offline)supply chain✅ on— (stdlib, offline)
6 mcp-scan enrichmentsupply chain⬜ opt-in/airlock-setup mcp + AIRLOCK_MCP_SCAN=1

One command for all the installable stages — airlock installs them into an isolated managed venv (~/.cache/airlock/venv; never your system Python — uninstall by deleting that folder):

/airlock-setup                 # in a Claude Code session — installs EVERYTHING (2, 2b, 4-PII, 6)
/airlock-setup promptguard     # …or narrow to a single extra
airlock-setup --extras all     # CLI equivalent (a pip install of this repo provides it)

Or set-and-forget — install in the background on first session (off by default, non-blocking, never silent):

export AIRLOCK_AUTO_INSTALL=1                       # default extras: all
export AIRLOCK_AUTO_INSTALL_EXTRAS=promptguard,ocr  # optional: narrow the set

Prefer your own environment instead of the managed venv? pip install "airlock-guard-core[all]" (or [promptguard] / [pii] / [ocr] / [mcp]).

No stage requires a paid account or subscription. Stage 2 uses an ungated, Apache-2.0 prompt-injection classifier (protectai/deberta-v3-base-prompt-injection-v2 by default; override with AIRLOCK_STAGE2_MODEL). Stage 3 (task-drift) runs against a local Ollama — open models, no API key: install Ollama, ollama pull qwen2.5:7b, then AIRLOCK_ALIGN_BACKEND=ollama. (A paid Together key is an optional alternative.) Use a 7B-class judge: in live testing qwen2.5:7b scored 7/7 on a drift/benign battery while llama3.2 (3B) false-positived on 3 benign actions (including the user's own requested fetch) — too weak to judge alignment, though it needs ~5GB RAM vs ~2GB. The only non-pip needs are open-source binaries: Stage 2b wants the system tesseract.

Prefer Meta's Prompt Guard 2 instead? Set AIRLOCK_STAGE2_BACKEND=promptguard and /airlock-setup llamafirewall — note that model is gated (needs an HF_TOKEN + accepting Meta's license).

Use

  • Automatic: every WebFetch/WebSearch result is scanned; flagged fetches get a quarantine + re-anchor system reminder (high-confidence hits also signal a block).
  • Manual: /scan <text-or-url> runs the same guard on demand.
  • CLI: printf '%s' "text" | PYTHONPATH=. python3 -m guard_core.cli

Configuration (env vars)

VarDefaultEffect
AIRLOCK_DISABLEoff1 disables the guard
AIRLOCK_STAGE0/1/2ondisable an individual stage
AIRLOCK_BLOCK_THRESHOLD3severity (1–3) to block vs. only flag
AIRLOCK_STRIP_ZWJoffalso strip ZWJ/ZWNJ (off preserves emoji + Persian/Indic)
AIRLOCK_STAGE2_BACKENDopenopen (ungated classifier) / promptguard (Meta Prompt Guard 2, gated) / off
AIRLOCK_STAGE2_MODELprotectai/deberta-v3-base-prompt-injection-v2HF repo for the open backend
AIRLOCK_STAGE2_BLOCK_SCORE0.98open-backend injection score to block vs. flag — see tests/eval_stage2.py for the precision/recall trade-off (the open classifier is noisy on security-adjacent prose, so Stage 1 stays the high-precision layer)
AIRLOCK_PROMPTGUARD_MODEL86MPrompt Guard 2 size (86M/22M) — only the promptguard backend
AIRLOCK_EGRESS_ALLOWLISTemptycomma-separated hosts exempt from the data-param heuristic
AIRLOCK_EGRESS_BLOCKoff1 → deny outbound on detection (default: ask)
AIRLOCK_EGRESS_PIIoff1 → also run Presidio PII (needs presidio-analyzer)
AIRLOCK_ALIGN_BACKENDautoollama (local, open, no key) / together (API key) / off; auto prefers a configured local Ollama over the paid Together API, else stays off
AIRLOCK_OLLAMA_MODELqwen2.5:7bOllama model for the Stage 3 judge — use 7B+ (3B models false-positive); enables the ollama backend under auto
AIRLOCK_OLLAMA_URLhttp://localhost:11434Ollama server URL for Stage 3
AIRLOCK_ALIGN_BLOCKoff1 → deny (not ask) on detected task drift
AIRLOCK_SENSITIVE_TOOLSBash,WebFetch,WebSearchtools gated by Stage 3
AIRLOCK_SCAN_BASH_OUTPUToningress-scan stdout of curl/wget/etc. Bash fetches (closes the shell-fetch bypass); 0 to disable
AIRLOCK_STAGE3/5/6/2Bondisable an individual stage
AIRLOCK_MCP_SCANoff1 → also run Invariant mcp-scan (network) for Stage 6
AIRLOCK_MEMORY_PATHSemptyextra fnmatch globs treated as memory sinks (Stage 5)
AIRLOCK_MEMORY_BLOCKoff1 → deny (not ask) a poisoned memory write
AIRLOCK_AUTO_INSTALLoff1 → background-install heavier extras into the managed venv on first session
AIRLOCK_AUTO_INSTALL_EXTRASallwhich extras to auto-install (all, or narrow: promptguard,ocr,…)
AIRLOCK_HOME~/.cache/airlockwhere the managed dependency venv lives
AIRLOCK_SIDECAR_PORT8787loopback port for the openclaw sidecar (python3 -m guard_core.server)

Layout

guard_core/        shared, harness-agnostic Python:
                     normalize/heuristics/scanners/verdict  Stages 0–3 (ingress + action)
                     egress.py                              Stage 4 (egress)
                     memory_guard.py                        Stage 5 (persistence)
                     mcp_vetting.py                         Stage 6 (supply chain)
                     multimodal.py                          Stage 2b (image OCR)
                     trace.py / config.py / cli.py          glue
                     server.py                              loopback HTTP sidecar (for openclaw)
adapters/
  claude-code/     .claude-plugin + hooks (ingress scan, egress gate, alignment, memory gate,
                     MCP vet, SessionStart) + airlock skill + /scan
  openclaw/        TS plugin (tool_result_persist true-strip, before_tool_call gate,
                     message_sending rewrite) → calls the core via the sidecar
tests/             offline suites + run_all.py + fixtures/   (101 checks)
docs/SMOKE_TEST.md live in-session verification guide
pyproject.toml     pip-installable core (+ promptguard / pii extras)

Limitations (honest)

  • Claude Code hooks can't rewrite tool output, so airlock re-anchors/blocks, it does not byte-strip. The openclaw adapter can truly strip (via tool_result_persist) and rewrite the reply.
  • Ingress covers WebFetch/WebSearch; content fetched via Bash curl/wget bypasses the ingress hook (egress still gates the outbound Bash).
  • Stage 3 (task drift) and Stage 6's mcp-scan enrichment need an LLM/network; they no-op cleanly when absent. Stage 2b needs OCR deps.
  • Fails open: any internal error → the host session is never blocked.
  • A mitigation, not a complete fix. Egress secret detection is precision-tuned but not exhaustive; the gate defaults to ask (not deny) so a false positive costs a confirmation, not a hard block.

Test

python3 tests/run_all.py       # 101 offline checks (ingress, egress, alignment, MCP, memory,
                               #   multimodal, sidecar), no external deps

For a live in-session check (the plugin actually firing on a fetch / egress), follow docs/SMOKE_TEST.md.

Ver o original no GitHub

Bom para

Relacionados