Zn Gate

[zn]

zn-gate

[CI] [npm version] [License: MIT]

The local security layer for coding agents. zn-gate guards your secrets, your data and your systems while you use Claude Code, Codex CLI, Cursor, OpenCode, Antigravity or ZCode desktop app.

zn-gate is an open-source security layer that runs on your machine, between your agent and the tools and content it touches. It checks what the agent reads and calls for prompt injection, redacts secrets from tool output before the model sees it, and audits prompts, skills and configs. No account, no network by default, and no runtime dependencies except age-encryption (and its @noble/@scure dependencies) for the secret vault, bundled in the package at the versions pinned in package-lock.json.

For: developers using Claude Code, Codex CLI, Cursor, OpenCode, Antigravity, ZCode desktop app or any MCP client. Python SDK: zn-gate on PyPI.

Install

Everything runs on your machine; no account or API key is needed. Node.js 22 LTS is recommended (from nodejs.org). Node.js 18 or later works for the hooks and the CLI; the Claude Code plugin needs 20.19 or later. For security, use the latest patch of a supported Node.js line (22.23.4, 24.22.1, 26.12.1 or later): Node.js 18 and 20 are end-of-life and get no security fixes, even though zn-gate still runs on them. With a Node.js older than 18, the zn-gate and zn commands stop and say how to install it.

Getting started: four steps, one command each. Run them in your own terminal.

1. npx -y zn-gate reach shows what your coding agents can reach on this machine: secrets in your .env files (by name only), credential files and MCP servers. It is read only and sends nothing. Details in docs/reach.md.
2. npx -y zn-gate init sets up protection for the coding agents it finds, one step at a time, and asks before each change.
3. npx -y zn-gate check tests that protection with a fake secret in a temporary folder. init runs it at the end too.
4. npx -y zn-gate env shadow .env moves the real values of your .env into the local vault and leaves markers in the file. The first time, run npx -y zn-gate unlock to create the vault.

One command for the coding agents on your machine:

npx -y zn-gate init

init does this:

• It finds Claude Code, Codex CLI, Cursor, OpenCode, Antigravity and ZCode desktop app on your machine.
• For each one that is not protected yet, it shows the setup: the zn-gate plugin for Claude Code (or zn's hooks when your Node.js is older than 20.19), and zn's hooks for the others.
• It runs each step only after you confirm it.
• It ends with zn-gate check.

Run it yourself, in your own terminal. When an AI agent or a script runs it, it only prints the steps.

Windows PowerShell: npm and npx can fail with "running scripts is disabled on this system", because the default execution policy blocks npm.ps1. Use npm.cmd, npx.cmd and zn.cmd instead (for example npm.cmd install -g zn-gate), run the commands from Command Prompt, or allow local scripts for your account with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

If something fails:

• npx: command not found, or a message about the Node.js version: install the LTS version of Node.js, open a new terminal and run the command again.
• "running scripts is disabled on this system" on Windows: see the PowerShell note above.
• init only prints steps and changes nothing: an AI agent or a script ran it. Run it yourself in your own terminal.
• check shows NOT protected: that line says why and what to run. What the output means.
• You want to remove zn-gate: npx -y zn-gate uninstall shows what it will remove (the Claude Code plugin, zn's hooks, wrapped MCP servers) and asks first. init --revert only puts back MCP configs saved before wrapping.

Then keep your .env values in the vault. With the plugin or the hooks, the agent cannot read .env files with real values; move them into zn-gate's encrypted vault, and the file keeps markers such as __ZN_STRIPE_KEY__:

npx -y zn-gate unlock            # creates the vault the first timenpx -y zn-gate env shadow .env

After this, your own app also reads the markers in .env: start it with zn-gate's run command once you allow it (docs/secrets.md). env shadow tells you how to undo it.

Five-minute walkthrough: docs/secrets.md. Limits: docs/threat-model.md. Words you do not know: glossary. Every command and exit code: command line reference.

claude plugin marketplace add usezn/znclaude plugin install zn-gate@usezn

npm install -g zn-gatezn hooks install codex           # or: cursor, opencode

python3 -m venv .venv.venv/bin/pip install zn-gate      # Windows: .venv\Scripts\pip install zn-gate

claude mcp add zn-gate -- npx -y zn-gate mcp     # Claude Codecodex mcp add zn-gate -- npx -y zn-gate mcp      # Codex CLI

Wrap the MCP servers you already use

init finds MCP servers in your agent config files, writes a backup, and wraps each local (stdio) server with zn-gate shield:

npx -y zn-gate init --dry-run   # preview, changes nothingnpx -y zn-gate init --wrap-mcp  # wrap (a .bak.<timestamp> copy is written first)npx -y zn-gate init --shadow    # log detections without blockingnpx -y zn-gate init --revert    # put back the MCP configs saved before wrapping (not hooks or the plugin)

Remote (URL) servers are left as they are. init never rewrites a file it cannot round-trip safely: OpenCode JSONC files with comments and Codex entries with multi-line args are reported as "wrap manually".

To wrap a single server by hand:

npx -y zn-gate shield -- uvx mcp-server-fetch

See what zn-gate did

npx -y zn-gate report

A short summary of the last 7 days on this computer: blocked actions, secrets hidden, new protected MCP servers and tool changes waiting for your approval. It reads only local files, needs no account and sends nothing. --since 30d changes the period, --json prints it for scripts. What it shows.

Turn on the optional cloud check

npx -y zn-gate connect

Optional, and you do it yourself in your own terminal (an agent cannot). It opens usezn.com so you can create an analysis-only API key (it cannot read your usage or manage keys), then asks you to paste it at a hidden prompt. A full-access key is refused. The key is kept in your system keychain (or the zn vault when there is no keychain), never written to a file, and zn's hooks refuse the direct ways for your agent to read it. After that, the text you or your agent send through analyze_prompt, with detected secrets removed first, is also checked by the Galvanize 3 classifier at usezn.com. Until you run it, nothing is sent. zn-gate disconnect removes the key from this computer and asks whether to revoke it on usezn.com too (default no). How it works.

Check that it works

npx -y zn-gate check

For each agent set up for your user, zn-gate asks its hook to let the agent read a .env file with a fake key and an ordinary file, in a temporary folder. It shows what your agent would be told, and a line that says NOT protected says how to fix it. Nothing is sent over the network and no setting changes. What the output means.

npx -y zn-gate test

This runs the local self-test (51 curated vectors: 26 attacks, 25 benign) and shows per-decision latency on your machine. It is a smoke test, not a detection rate. Nothing is sent over the network.

For developers: see the redaction by hand. Send a tool output with a fake AWS key (AWS's documentation example) and a database password through zn-gate, exactly as your agent would, and look for sanitized_content in the output; that field is what the model would see. In the full output, verdict: allow only means that no prompt injection was found; the secrets are hidden in sanitized_content (here [REDACTED_AWS_KEY] and [REDACTED_DB_PASSWORD]), and secrets_redacted counts them:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_tool_result","arguments":{"tool_name":"read_file","content":"AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\nDATABASE_URL=postgres://app:hunter2@db:5432/main"}}}' \  | npx -y zn-gate@latest mcp

Example: protect the tools of a Vercel AI SDK agent.

What each piece does

Scrubber: secrets stay out of the model's context

• Today, through zn-gate: redacts AWS keys, OpenAI and Anthropic keys, GitHub tokens, JWTs, private keys and database URL passwords in everything that passes through zn-gate (check_tool_result, check_tool_call, and output of servers wrapped by shield / init).
• Today, agent hooks and vault: hooks for Claude Code, Codex CLI and OpenCode scrub the output of the agents' built-in tools and block pasted secrets (in Cursor only MCP tool output is scrubbed); a local encrypted vault with stable markers (__ZN_AWS_KEY_1__); zn run gives a value (as an environment variable) only to commands you approved; personal data (cards, IBAN, national IDs, e-mail, phone) is detected too. What each agent allows differs: see compat.md.

Galvanize: prompt-injection detection

• Today, local: a deterministic rules engine with normalization against homoglyphs, zero-width characters, BiDi overrides (CVE-2021-42574), comment splicing and Base64. It checks prompts, tool arguments, tool output and MCP tool descriptions.
• Today, optional cloud: the Galvanize 3 classifier (open weights on Hugging Face; announcement; the previous model, Galvanize 2, also has open weights under Apache-2.0) can also check prompts sent to analyze_prompt, only with ZN_CLOUD=1 and ZN_API_KEY. The secrets zn-gate detects are removed before sending; personal data and a secret it does not recognize are sent as written.
• Roadmap: running Galvanize locally inside zn-gate.

Scan: audit what your agent is about to trust

• Today: npx -y zn-gate scan <path> audits prompt templates, AGENTS.md / SKILL.md files and configs for injection traps and leaked secrets. It exits with code 1 on findings, for CI. A link given as the folder to scan is followed. When no file is scanned, the report says "No files were scanned in " and the exit code is 3. A file or folder that could not be read (for example a file of 2 MiB or larger) is listed and also makes the exit code 3, unless you pass --allow-partial. It also checks the MCP server configs (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, .codex/config.toml, claude_desktop_config.json and others) for keys and passwords written in plain text in env, headers, arguments or URLs; it never prints the value, and --include-home checks your own MCP configs too. MCP servers can be checked on the web at usezn.com/scan.
• Roadmap: auditing MCP servers and skills from the CLI before you add them.

MCP tools

What leaves your machine

Nothing, by default.

If the cloud call fails (no connection, a timeout, an error from the service, or a saved key that cannot be read), the prompt is checked by the local rules alone and the result says fallback: true. The check does not fail closed: a prompt the local rules allow goes through. ZN_API_KEY alone enables nothing. zn-gate connect is the other way to opt in: you run it, in your own terminal, and it keeps the key in your system keychain or the zn vault, never in a file (zn-gate disconnect undoes it and can revoke the key on usezn.com when you say yes; details). ZN_LOCAL_ONLY=true (or --local-only) overrides ZN_CLOUD=1 and a connected key. npx -y zn-gate status shows the active detection engine and whether the optional cloud check is on. Sharing of usage statistics is off by default and has its own status: npx -y zn-gate stats share status. Data-flow diagrams: repository README.

1.4.0 and earlier: with ZN_API_KEY set, tool output and tool-call arguments not blocked locally were sent to api.usezn.com without redaction. 1.4.1 removes that path. See the CHANGELOG.

Performance (local rules engine, no network)

Measured 2026-10-11 on a 2-vCPU Intel Xeon Platinum 8259CL (AWS), Node 24, zn-gate 1.4.1, uncached inputs. p50 is the median of 3 runs; p99 is the worst of 3 runs.

check_tool_result includes secret redaction. Latency grows roughly linearly with input size. The MCP stdio round-trip for a 4 KB check_tool_result was 0.5 ms p50 on the same host.

Reproduce with node bench/bench_by_size.js from the repository. Please send us your numbers.

Accuracy: what the local rules catch, and what they don't

The local engine is a deterministic signature and normalization layer. It is fast and explainable, but it is not a semantic classifier.

• Self-test: 51 curated vectors pass. That is a smoke test, not a detection or false-positive rate.
• Known limitation: on whole source files, as seen by check_tool_result, the rules can flag ordinary code comments. 1.5.0 reduces these on code and documentation, at the cost of letting some loosely worded override attempts through the local rules. Prefer check_tool_result for web and third-party content rather than your own repository files.
• Detection rates: on a multilingual set of 3,309 examples, Galvanize 3 has 89.6% recall at a 0.6% false positive rate, and it flags 2.9% of 658 long legitimate documents; these numbers are for the cloud classifier only. They do not measure the local rules engine and are not protection that zn-gate gives you offline; the local engine has no detection rate, only the self-test above. The set was not used for training; it was used to choose between candidate models. Method and the comparison with nine open detectors are in the announcement. The Galvanize 3 weights and model card are on Hugging Face. The previous model, Galvanize 2, has its own results on its model card. It is one layer of defense, not a guarantee.

What zn-gate is not

• Not a sandbox. zn-gate checks what its hooks, MCP wrappers and library calls can see, and blocks or rewrites it. A program the agent starts can still do things the hooks cannot read. For that, use your agent's own sandbox or permission prompts (see the threat model).
• Coverage depends on the agent. Each agent's hooks see and can change different things: for example, Cursor cannot rewrite shell or file output, and Codex replaces a result instead of editing it. Agent compatibility lists it per agent, and npx -y zn-gate check shows what your own agents are covered for.

Configuration

• ZN_CLOUD: 1 lets analyze_prompt / zn-gate analyze also query the cloud classifier. Requires ZN_API_KEY. Off by default.
• ZN_API_KEY: API key from usezn.com/dashboard. No effect without ZN_CLOUD=1. (zn-gate connect keeps a key for you instead and turns the cloud check on.)
• ZN_LOCAL_ONLY: true forces local-only, even with ZN_CLOUD=1.
• ZN_STRICT: 1 also blocks the rules that only warn by default (see below).
• ZN_LONG_INPUT: how a long text (over 1,000 characters) is sent to the cloud classifier. windows (default) asks it to check overlapping 512-token windows, up to 20, so an injection in the middle or at the end of a long document is not missed; off checks only the first 512 tokens. Also --long-input windows|off. Windows are slower and slightly more likely to flag a long benign text, and cloud checks are billed by text size with or without windows, so off does not lower the count (1 call up to 2,000 characters, 1 more per further 1,000; billed_calls in the result); see the changelog.
• ZN_STAGE: v30 (default, current production API) or prod (legacy endpoint). ZN_API_URL overrides both.
• NO_COLOR (any non-empty value) or TERM=dumb: command output has no colors, symbols or box-drawing lines; the status words (ALLOWED, BLOCKED, PASSED, ...) stay. Colors are also off when the output is not a terminal.
• hooks.replaceToolOutputOnSecret in ~/.zn/config.json ({"hooks": {"replaceToolOutputOnSecret": true}}): Codex only, off by default. When a tool output holds a real secret value (not only a marker), zn also returns continue: false with a stop reason. Codex then replaces the tool result with that text, so the model may get it instead of zn's tokenized copy of the output. Environment variables do not turn it on.
• hooks.blockDestructiveCommands in ~/.zn/config.json: the agent hooks refuse a recursive delete of the home folder or the root and writes to a disk device by default. true also turns on four more rules (a download piped to a shell, chmod -R 777 /, a fork bomb, a download written into a shell startup file), false turns the check off, and a list of rule names picks exactly those. ZN_BLOCK_DESTRUCTIVE=1 turns on all six rules from the environment; the environment cannot turn rules off, so 0 is ignored and only the file can disable the check. A blocked command is not run; the agent is told to ask you first. It reads command text only and is not a sandbox; see Destructive commands.
• hooks.egressCheck in ~/.zn/config.json: before a network request runs (curl, wget, Invoke-WebRequest, inline python -c or node -e, WebFetch, MCP calls with a URL or headers), the agent hooks look for personal data (email addresses, phone numbers and the other kinds the scrubber finds) and literal secrets in its headers, credentials, query string and body, and ask you first. "deny" refuses the request instead, "off" or false turns the check off. hooks.egressAllowHosts lists hosts that are not checked ("api.example.com", "*.example.org"); localhost, 127.0.0.1 and ::1 never are. A value read from an environment variable ($TOKEN) is not reported, because only literal values are; it is still not a way to hand an agent a secret, since the shell puts it in the program's arguments (use zn run --secrets NAME -- <command> or the secrets_http_request tool). ZN_EGRESS_CHECK=deny makes the check stricter from the environment; it cannot turn the check off. See Network requests that carry personal data.

To enable the cloud check for one MCP server, add to its entry: "env": { "ZN_CLOUD": "1", "ZN_API_KEY": "zn_live_..." }.

Custom rules (.znrules or zn.config.json)

# .znrulespath:.env.productionpath:/etc/secretsCONFIDENTIAL_INTERNAL_PROJECT_[A-Z0-9]+

Each non-comment line is a pattern (matched without regard to case) unless it starts with path:, secret: or is the word strict. In zn.config.json the same patterns go in bannedPatterns and the paths in forbiddenPaths.

Patterns run in time proportional to the text, so a project file cannot make the hooks hang. That is why only this syntax is accepted: literal characters, ., classes such as [a-z] or [^x], \d \w \s, \b, ^, $, groups ( ) and (?: ), alternation |, and the quantifiers ?, *, + and {n}, {n,}, {n,m} (counts up to 100). A pattern can be at most 500 steps long once its counts are expanded (for example a{100} is 100 steps), and all the patterns of a file together at most 600 steps, so that checking a long text stays fast; a file can hold at most 100 patterns and a pattern at most 500 characters. Matching ignores case for ASCII letters (a-z); letters of other scripts are matched as written. Backreferences, lookahead, lookbehind, named groups, \p{...} and a quantifier on a group that already contains one (such as (a+)+) are rejected.

If a rules file cannot be read, is not valid JSON, or holds a pattern that is not accepted, zn-gate does not apply half of it. It blocks with a message that names the file, the line or entry and the reason, until you fix the file: edit that line, or delete it. zn-gate check lists the errors, and zn-gate audit reports them as one finding about the rules file.

Local audit log

zn-gate shield appends every decision to ~/.zn/evidence.jsonl as a hash-chained (SHA-256) record with a secret-redacted preview. It detects accidental or partial edits. It is not tamper-proof against someone with write access to the file, who can recompute the whole chain.

The agent hooks write to the same log. When a hook blocks a tool call, a prompt or a final answer, or hides a secret in a tool result, zn-gate evidence shows one more event with the agent, the kind of event, the tool name, a rule name (such as hook-pre_tool-policy or hook-redacted-output) and the kinds of secret found. It never stores a secret value, a command, a file path or the text of your prompt. Calls that are allowed are not written, so the log stays short. If the log cannot be written (a full disk, a damaged log, a busy lock), zn prints one line about it and the block still holds. Counts of all checks, including allowed ones, are in npx -y zn-gate stats.

npx -y zn-gate evidence --verifynpx -y zn-gate evidence --ui        # local dashboard on http://localhost:3100npx -y zn-gate evidence --tail 20

What the code API checks (and what it does not)

require('zn-gate/lib/rules') gives you evaluate(text) and sanitizeToolResult(name, text). They are a text check: evaluate looks for prompt-injection wording and for names of secret files (~/.ssh/id_rsa, .env) in the string you pass, and sanitizeToolResult checks and cleans what a tool returned. They do not parse a shell command and they do not know what a tool would do.

So evaluate is not a command or tool-call firewall: deleting files or piping a download to a shell is allowed. The checks that protect your machine while an agent works (the secret-file and vault rules for shell commands, file reads and writes) belong to the agent hooks (zn-gate init, zn hooks install <agent>), and they protect secrets and zn's own files, not every dangerous command. Hooks are not a function you call from your own agent code. If you build an agent, decide for yourself which tools may delete files or run commands, and use zn-gate on the text that reaches the model.

What is blocked and what only warns

zn-gate blocks what is almost certainly an attack or a leak: reading credential files (.env, ~/.aws/credentials, SSH keys), asking for API keys or passwords, sending data out through hidden image links, hidden instructions in Base64 or invisible characters, "ignore all previous instructions" and other injection wording. It does not judge whether a shell command is destructive: rm -rf ~/ or curl ... | sh are not blocked on their own.

Some other patterns also appear in ordinary text, such as system: keys in YAML, "bypass the cache" or an article that explains what a jailbreak is. For those, zn-gate lets the text through and adds a short warning (advisory in the result) so you or your agent can take a look.

The same goes for text in a tool result (a fetched page, an MCP result, a file) that tells your agent to say who its user is, or to put the user's name, email, account or API key in a header, a URL parameter, a cookie, a form field or the next request. That wording is rarely legitimate there, but docs and policies mention the same words, so by default it is an advisory (pi:identity_request; pi:identity_request_multi covers Spanish, Portuguese, French, German, Russian and Chinese) and strict mode blocks it. Documentation that tells you to send your own API key in the Authorization header does not match, and neither does API documentation that asks for your email in a User-Agent or From header, a mailto parameter, a request body or a form.

To block those too, turn on strict mode: set ZN_STRICT=1, or add "strict": true to zn.config.json in your project (or a line strict in .znrules).

Examples

Runnable examples, including LangChain.js and LangGraph.js (block a dangerous tool call, scrub the output) and the OpenAI Agents SDK for JavaScript (block a dangerous tool call, scrub the output, all offline) and a Mastra agent, are in examples/.

FAQ

Do I need an account or API key? No. Everything local works without one.

Will it block legitimate content? Sometimes. Use --shadow with init or shield to log detections without blocking while you evaluate it.

How do I remove it? Run npx -y zn-gate uninstall in your own terminal. It lists what it found (the Claude Code plugin, zn's hooks for each agent, wrapped MCP servers), asks before removing, and ends with zn-gate check. Your vault is only deleted if you confirm that separately. npx -y zn-gate uninstall --dry-run shows the list and changes nothing. To remove one part at a time, or for the steps by agent, see the removal guide. init --revert is narrower: it only puts back the MCP configs that were saved before init --wrap-mcp wrapped them. For a standalone server, remove the zn-gate entry from your agent config.

Security

Report vulnerabilities to [email protected]. Policy and safe harbor: SECURITY.md.

License

MIT © usezn

The package bundles age-encryption (BSD-3-Clause) and its @noble / @scure dependencies (MIT); see THIRD_PARTY_NOTICES.md.