# keryn mcp guard

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> keryn mcp guard: pin and check tool definitions, screen manifests, list configured servers, audit, wrap or guard a server

Source: https://keryn.dev/docs/reference/cli/mcp-guard/

Pin and check tool definitions, screen manifests, list configured servers, audit, wrap or guard a server.

```text
keryn mcp guard --policy <file> [guard options] -- <server command...>
```

## Options

```text
Usage: keryn mcp inventory <tools-list.json> [--requests <server-url>] [options]
       keryn mcp pin <tools-list.json> [--server <name>] [--lock <file>]
       keryn mcp check <tools-list.json> [--server <name>] [--lock <file>] [options]
       keryn mcp manifest <server.json|manifest.json> [--kind registry|dxt] [options]
       keryn mcp inventory --example
       keryn mcp servers <dir>
       keryn mcp audit [<home dir>]
       keryn mcp wrap <config.json> --policy <file> [--log <file>] [-o <out.json>]
       keryn mcp guard --policy <file> [guard options] -- <server command...>
  'inventory' reads a saved tools/list response ({tools: [...]}, a JSON-RPC envelope, or an array of tool definitions) and
  judges each tool with savvy-cli's tool engines compiled to WebAssembly: vendor shape, permissions, risk tags, a risk
  score, a capability descriptor (auth, effects), and a poisoning screen over the name, description and every parameter
  description (hidden or tag Unicode, "ignore previous", exfiltration URLs, cross-tool shadowing, instructions to read secrets
  or key files). The web app and the extension give the same verdict. Findings gate, write and annotate like a scan; the
  server is never contacted. No AI-BOM here (--aibom is refused). '--example' judges the tool list of the Keryn demo MCP server
  (api.keryn.app/demo/mcp: one poisoned, one over-broad and one clean tool) so there is something to look at on a first run.
  'inventory --requests <server-url>' also prints, as JSON on stdout, the JSON-RPC requests ZAP's MCP importer (mcp-import job)
  would send for that tool list: initialize, the lists, then one tools/call per tool with typed placeholder arguments, each with
  its named argument positions (input vectors) and the screen's verdict for its tool. The port is measured against ZAP's own
  McpImporter (evals/receipts/zap-mcp.json). Nothing is sent: use the templates with a tool you authorize against a server.
  'pin' writes keryn-mcp.lock.json: per server and tool, the SHA-256 of the canonical name, description and inputSchema
  (a file {mcpServers: {name: {tools}}} pins several servers; --server names a single tools list). 'check' compares a tools
  list with the lock: added, removed or changed tools; a changed description is an error (rug pull), other drift a warning.
  'manifest' screens an MCP registry server.json or a Claude Desktop extension manifest.json: shape, unpinned packages, plain-http
  or unauthenticated remotes, broad permissions, secret-looking settings with default values.
  'servers' lists the MCP servers the repository's client configs name (.mcp.json, mcp.json, .cursor/mcp.json,
  .vscode/mcp.json, claude_desktop_config.json, ...); 'keryn scan' lists the same servers as AI-BOM components (service,
  category mcp) and reports their config risks (unpinned npx/uvx, plain-http or unauthenticated remotes, trusted /
  auto-approved servers, inline secrets) unless the agent-config rule packs already did.
  'audit' reads the MCP configs of the AI clients installed for this user (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf,
  Gemini CLI, Continue) from their usual places, lists the servers each would start and reports the same config risks; it never
  writes those files, starts a server or contacts one. Pass a directory to audit another home (a mounted profile).
  'wrap' prints the client config with every stdio server behind 'keryn mcp guard' (policy, decision log, the server's name as the
  agent); remote servers are listed and left alone; servers already behind this keryn under the same policy are unchanged,
  any other 'mcp guard' entry is wrapped again under yours. It never writes over the input file.
  'guard' runs keryn-mcp-guard (find it on PATH, next to keryn, or KERYN_MCP_GUARD=<path>): a stdio proxy between the MCP
  client and the server that checks every tools/call against the policy file (deny, hold for approval, allow with
  obligations); everything else passes through untouched. IT FAILS OPEN: if the policy engine cannot decide, the call goes
  through and is recorded as FailedOpen; the guard's fail-closed option refuses instead. It does not inspect responses.
  Guard options (log, agent, session, fail-closed, approvals, notify, policy digest pin): 'keryn-mcp-guard --help' or https://keryn.dev/docs/guides/mcp-guard/.

Inputs
  --rules <a.yml,bundled:aibom>   rule files or bundled packs: aibom, vuln, audit, inventory, all, risk (default: bundled:all for scan, bundled:aibom for bom/diff)
  --policy <file>                 policy-as-code YAML
  --config <file> | --no-config   .keryn.yml (default: ./.keryn.yml if present)
  --base <git ref | bom.json | result.json>   baseline for diff
  --include/--exclude <glob,...>  path globs relative to the scan root (ts/fixtures/** is that one folder; **/fixtures/** any depth)
  --repo-root <dir>               (scan, bundle) the repository the scanned folder belongs to: report paths, rule paths:, code roles,
                                  --include/--exclude and .keryn.yml (default <dir>/.keryn.yml) see repository-relative paths, as a scan of
                                  the whole repository would; fingerprints stay relative to the folder, so earlier baselines still match
  --max-file-size <bytes> --max-files <n> --max-total-size <bytes> --timeout <seconds>
                                  (lockfiles past --max-file-size are still read for dependencies, up to 64 MiB)
  --symlinks skip|follow-confined|error   (default: skip)
  --subject <name> --revision <id> --timestamp <iso|now>
  --observed-browser <snapshot.json>   a page snapshot (extension download): its AI technologies join the BOM, basis observed-in-browser
  --observed-network <observed-ports.json>   network observations: classified AI services join the BOM (observed-on-network), their findings gate
  --summary-by owasp_llm|owasp_agentic|cwe|nist_ai_rmf|atlas   group findings by a framework taxonomy in the console and markdown summary (reference only; not a compliance assessment)
  --offline (source scan/import: accepted and a no-op; these commands do not use the network)

Outputs ("-" writes to stdout; several per run)
  --aibom <f>      CycloneDX 1.6      --sarif <f>        SARIF 2.1.0
  --sbom <f>       dependency SBOM: every locked package, licence, graph (--sbom-format cyclonedx|spdx: CycloneDX 1.6, SPDX 2.3)
  --junit <f>      JUnit XML          --gitlab-sast <f>  GitLab SAST report
  --codequality <f> Code Quality      --json <f>         Keryn result JSON
  --markdown <f>   PR/MR summary      --annotations github|azure|gitlab|teamcity
  -q, --quiet      --verbose      list findings with proof rung and flow

Gate
  --fail-on error|warning|info|none (default error)
  --fail-on-unsupported   exit 3 on unsupported/partial/timed-out rules (now the default; kept for scripts)
  --allow-incomplete      do not exit 3 when rules were unsupported/partial/timed out (default: exit 3)
  --dependencies <file>   (scan) a resolved dependency list your build produced, read like a lockfile; repeatable. dependency-tree.json or
                          dependency-tree.txt (mvn dependency:tree), or a CycloneDX / SPDX JSON SBOM named bom.json, sbom.json, *.cdx.json or
                          *.spdx.json. It supersedes the pom.xml or Gradle build of its project. Keryn does not run Maven or Gradle
  --advisory-max-age <days>  (scan) the installed offline advisory snapshot (keryn sca db update) may be this old; an older one still checks the
                          dependencies but the run is incomplete (exit 3). Without --online an installed snapshot is used with no flag
  --require-advisories    exit 3 when lockfiles were not checked against advisories (offline); the verdict always says so
  --gate-confidence P1|P2 lowest rule confidence that counts toward --fail-on (default P1; P2 widens)
  --secrets-config <file> (scan, ci) gitleaks TOML with your own secret rules ([extend] useDefault = true keeps the 222 defaults); default: .gitleaks.toml
                          at the scanned root when present. A .gitleaksignore at the root is read. keryn rules lint <file.toml> checks one without scanning
  --secrets-history       (scan, ci) also scan the added lines of every commit reachable from HEAD for secrets; --secrets-since <ref|date>, --secrets-max-commits N
  --no-deep               (scan, bundle) skip the Deep pass: pattern rules only (default: Deep runs after them, fed with their facts)
  --deep-timeout <seconds>  (scan, bundle) Deep's time limit (default 300; KERYN_DEEP_TIMEOUT_MS sets it in milliseconds). A Deep run
                          stopped by it leaves the pattern findings and makes the scan incomplete (exit 3 in keryn ci)
  --engine deep|forge     (scan) the interprocedural engine of the Deep pass: deep (default) or forge, the fact-bundle solver with
                          KSQL rules (Python and TypeScript today); side by side while Forge proves itself
  --vex <local-file>      repeatable OpenVEX, CSAF 2.0 VEX or CycloneDX VEX; attributed producer assertions, exact advisory and purl match
  --vex-product <purl|url> root context for VEX subcomponents; claims for other containers never apply globally
  --online                (scan, bundle, artifact analyze) check locked dependencies (artifact: crates and npm packages read from the file)
                          against OSV.dev advisories, and (scan) look up on deps.dev the licences lockfiles do not record:
                          sends package names and versions only, never
                          code or paths (default: offline; the report says which lockfiles were not checked). Reads deno.lock, and Deno code without one as declared, not locked; JSR, deno.land/x and URL modules are never sent
  --no-cache              (scan, bundle) neither read nor write the rescan cache (KERYN_NO_CACHE=1 does the same); 'keryn cache clear' empties it
  --no-ignore             scan files that .gitignore / .git/info/exclude exclude too (default: they are skipped and counted in the coverage line); Keryn's own earlier outputs are never scanned
  --new-only             gate new findings against a paired Git --base; incomplete comparison fails
  --fail-on-added         (diff) exit 1 when components were added
  --exit-warn             exit 10 for pass-with-warnings

Exit codes: 0 pass | 1 violations | 2 usage/config | 3 coverage | 4 internal/timeout | 10 warnings
```

## Examples

```sh
# Run a server behind the guard. Guard options: keryn-mcp-guard --help.
keryn mcp guard --policy policy.json -- npx -y @acme/server
```

## Exit codes

| Code | Meaning |
|---|---|
| 0 | the proxied server exited cleanly |
| 2 | usage error |
| 4 | guard could not start |

## Environment

| Variable | Meaning | Default |
|---|---|---|
| `KERYN_MCP_GUARD` | Path to the keryn-mcp-guard binary used by keryn mcp guard. | searched on PATH and next to keryn |
