MCP scanner
Behavioural scan of every Model Context Protocol server an agent might call. DefenseClaw wraps cisco-ai-mcp-scanner to surface hidden tool intents and shadow capabilities, takes its analyzers and judge from config.yaml, and maps each verdict through the admission policy.
Scan an MCP server before an agent calls it.
Every scanner setting lives in config.yaml under scanners.mcp_scanner. DefenseClaw builds each scan from those keys and nothing else. What a severity does is set under admission: (see Admission). The skill scanner has its own page: Skill scanner.
Guided example · Synthetic local stdio server
Catch hidden side effects in an MCP tool before admission
A read-only-looking tool advertises filesystem and outbound-network effects, so policy disables runtime and blocks installation.
{ "server": "catalog-lookup", "transport": "local_stdio", "severity": "high", "finding": "claimed_intent_side_effect_mismatch", "runtime": "disabled", "admission": "blocked"}{ "server": "catalog-lookup", "transport": "local_stdio", "severity": "high", "finding": "claimed_intent_side_effect_mismatch", "runtime": "disabled", "admission": "blocked"}
HIGH capability mismatch
Write admission audit event
What DefenseClaw did — and did not do
What it did
- Inspect a local stdio server in a short-lived scan subprocess
- Compare claimed intent with descriptor side effects
- Apply policy to the whole server
What it did not do
- Add a remote URL to any connector
- Claim a clean scan proves harmless implementation
- Require optional LLM intent analysis
What you just saw
Guided example with synthetic data. The balanced default adds a server with a HIGH finding with a warning; this example uses a stricter admission.mcp.actions.high mapping that disables the runtime and blocks the install. In the demo, a local stdio server started with npx advertises a read-only-looking tool whose description and schema imply file and network side effects. DefenseClaw holds admission, starts the server in a short-lived scan process to read its tool list, applies that HIGH action and blocks the install. A remote URL scan does not add the server to a connector.
What it scans
The wrapper at cli/defenseclaw/scanner/mcp.py accepts two target shapes — both as a positional TARGET argument (there is no --server or --remote flag — the scanner figures out which from the target's shape):
- Local stdio server name — described by a JSON file with a top-level
mcpServersblock (the format used by Claude Desktop, Cursor, OpenClaw, Codex, and Copilot). DefenseClaw starts each server as a short-lived subprocess, lists its tools, and records every advertised description, parameter schema, and example. - Remote HTTP server URL — passed as the positional target. The scanner calls
scan_remote_server_toolsdirectly without spawning a subprocess.
For every tool the scanner produces:
- A static signature (name, schema, description hash) checked against YARA rules.
- An LLM-assisted intent analysis — the description vs. the implied side effects.
- A consolidated finding with severity and reasoning.
Where DefenseClaw finds your servers
The CLI auto-discovers MCP server lists from the connectors you've set up, so you usually don't pass paths:
defenseclaw mcp scan --all
defenseclaw mcp scan --connector cursorThe default sources include:
~/.openclaw/openclaw.json→mcp.servers~/Library/Application Support/Claude/claude_desktop_config.json→mcpServers~/.cursor/mcp.json→mcpServers~/.config/devin/mcp_config.jsonand<workspace>/.devin/mcp_config.json→mcpServers~/.gemini/config/mcp_config.jsonand<workspace>/.agents/mcp_config.json→mcpServers(Antigravity)~/.kiro/settings/mcp.jsonand<workspace>/.kiro/settings/mcp.json→mcpServers(Kiro)- The MCP config of every other connector you set up with
defenseclaw setup <connector>.
Each server is scanned independently and findings are tagged with the connector that discovered them. Use --connector <name> on list, scan, set, unset, block, allow, and unblock commands when you want one connector's MCP source instead of the full configured roster. Without --connector, mcp set writes the server into every configured connector's MCP source, and mcp unset removes it from every configured connector that has it. For Claude Code, mcp set writes ~/.claude.json (the file Claude Code reads) and removes a same-named entry that DefenseClaw 0.8.x left in ~/.claude/settings.json; mcp unset removes the name from both.
One-shot scans
Before you start
These defenseclaw mcp steps are for a per-user installation. On managed Linux and macOS, the standard user's defenseclaw launcher refuses mcp (Managed command availability), so users add the server through the connector's MCP configuration, for example claude mcp add. An administrator scans a remote server with the managed gateway: sudo /opt/defenseclaw/bin/defenseclaw-gateway scan mcp URL on Linux or sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway scan mcp URL on macOS (see Known limits). On managed Windows, use the administrator's & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' scan mcp URL command from an elevated PowerShell prompt for a remote URL.
- A judge:
defenseclaw setup llmanddefenseclaw keys set DEFENSECLAW_LLM_KEY. Without one the scan runs YARA signatures only. It printsLLM analyzer skippedwhen a model is set but its key is missing, and nothing when no model is set. - A configured connector (
defenseclaw setup <connector>). DefenseClaw reads each connector's MCP config.
Steps
-
List the servers DefenseClaw can see.
defenseclaw mcp list -
Scan one by name, scan all, or scan a URL.
defenseclaw mcp scan filesystem defenseclaw mcp scan --all defenseclaw mcp scan https://mcp.example.com/sseA URL scan is a pre-flight check. It does not add the server to any connector. Add
--scan-prompts --scan-resources --scan-instructionsto look beyond the tool list. -
Add a server through the scanner.
mcp setscans first and follows the configured MCP admission action. Balanced admission adds a server with HIGH findings with a warning and an audit entry;admission.mcp.actions.high: quarantinerefuses it under a stricter policy.defenseclaw mcp set context7 --command npx --args '["-y", "@upstash/context7-mcp"]'A first
npx -ydownload can take longer than the scan waits, and a remote hostname may temporarily fail to resolve. When the scan does not finish,mcp setadds the server with a warning and records the failed scan in the audit log; scan it later withdefenseclaw mcp scan context7. To refuse such servers instead, rundefenseclaw config set scanners.mcp_scanner.unverified_server block.mcp setalso takes--urland--transportfor an SSE or HTTP server,--env KEY=VAL(repeatable) for the server's environment,--allow-privateto let the pre-add scan reach a private URL, and--skip-scan. For OpenCode only,--force-untrusted-commandwrites a command outside the trusted install prefixes whenunverified_serverisblock.
Use it in CI
--all --json prints one JSON array with a result object per server. A failed scan is an error object in the same array, with an error field and no findings, and the command then exits 1. Save the output, then check it before you count, so a failed or empty scan fails the job:
defenseclaw mcp scan --all --json > mcp-scan.json
jq -e 'length > 0 and all(.[]; has("error") | not)' mcp-scan.json > /dev/null
jq '[.[] | (.findings // [])[]] | length' mcp-scan.jsonRun the three lines as separate steps, or in a shell that stops on the first error. The first fails when a scan failed, the second when nothing was scanned or a row is an error, and the third prints the finding count.
To scan one server, name its connector. Without --connector, a name configured on several connectors prints one JSON object per connector, one after the other:
defenseclaw mcp scan filesystem --connector claudecode --json > mcp-scan.json
jq '.findings | length' mcp-scan.jsonA server on the block list prints nothing and exits 2.
Check it worked
defenseclaw mcp listThe Verdict column reads clean, warning, rejected or scan failed. A server whose last scan failed shows scan failed and a next step under the table. A scanned server without a block or allow entry shows what admission does with its severity: warning where the policy only warns (the balanced default warns on HIGH), rejected where the policy refuses it. A block the gateway left after a failed admission scan is named as such, with its cause and the way to allow the call: defenseclaw mcp allow <name>, or the asset_policy.mcp.allowed policy on a managed device (Managed command availability lists the commands a managed computer offers). A new scan does not release it, and neither does mcp unblock where the strict tier or a managed policy fails closed on a server it cannot scan.
A remote URL whose hostname has no DNS answer is a scan that did not finish, not a refusal of the server. The unverified_server setting below decides what happens then.
Configure the scanner
Set every key with defenseclaw config set (one key, validated, applied at once), the defenseclaw setup mcp-scanner wizard, or an edit to config.yaml. A change that does not validate is refused and the file is left alone.
defenseclaw config set scanners.mcp_scanner.judge_source inherit
defenseclaw config set scanners.mcp_scanner.scan_prompts true
defenseclaw config set scanners.mcp_scanner.scan_resources true
defenseclaw config set scanners.mcp_scanner.scan_instructions trueSet scanners.mcp_scanner.scan_prompts (config generation 30, sha256 ebe5d7074f38).
Effective policy digest: sha256:...Leave analyzers unset: a scan then runs YARA, and the LLM judge as well once defenseclaw setup llm has a model and key. Set analyzers only to pick analyzers yourself (see Analyzers). A list you set is run exactly as written, so ["yara", "llm"] with no judge configured makes every scan fail, and mcp set adds nothing:
error: scan failed: Cannot proceed with scan - missing required configuration:
• LLM analyzer requested but MCP_SCANNER_LLM_API_KEY not configured (or AWS credentials for Bedrock models)
'context7' was not added. Run 'defenseclaw mcp set' again once the server can be scanned, or add it unscanned with --skip-scan.The variable it names is the scanner's own; DefenseClaw clears it and passes the judge from the llm: block. Set up a judge with defenseclaw setup llm and defenseclaw keys set DEFENSECLAW_LLM_KEY, or go back to automatic selection with defenseclaw config set scanners.mcp_scanner.analyzers --json '[]'.
The same settings, written out:
scanners:
mcp_scanner:
judge_source: inherit
scan_prompts: true
scan_resources: true
scan_instructions: true| Key | Default | What it does |
|---|---|---|
analyzers | unset, read back as auto | The analyzers to run. Unset (config get prints auto) and [] both mean YARA, plus the LLM judge when it is ready. |
judge_source | inherit | inherit uses the top-level llm: block. override uses scanners.mcp_scanner.llm. |
llm | empty | The scanner's own judge settings. It must be empty with inherit and needs a model with override. |
scan_prompts, scan_resources, scan_instructions | false | Also scan the server's prompts, resources and instructions on every scan. |
unverified_server | warn | What mcp set and the gateway's install admission do when the scan did not finish (a timeout, an unresolved hostname, a launcher that exited, an unreachable URL) or an OpenCode command is outside the trusted install prefixes. warn adds or keeps the server with a warning and an audit record, including on managed standalone hosts; block refuses it, and the gateway blocks and disables it (strict). Secure Client uses separate closed admission. |
The Cisco AI Defense endpoint and key are not scanner keys. They stay in cisco_ai_defense (endpoint, api_key_env, timeout_ms), shared with the guardrail.
Analyzers
analyzers takes a list of the names below, or []. The schema accepts these five and refuses any other name, and an empty list is not "no analyzers": it is auto.
| Analyzer | What it does | Needs |
|---|---|---|
yara | Signature rules over each tool's name, schema and description: the scanner's own rules and DefenseClaw's bundled MCP rules. | Nothing. |
llm | The judge compares each tool's description with its parameter schema and the side effects they imply. | A model and key (the shared llm: block). |
api | Cisco AI Defense cloud classification of tool content. | cisco_ai_defense.api_key_env set to a key you have stored. |
behavioral | Checks that a tool's description matches how it behaves (dataflow analysis). Off in the recommended setup. | Nothing extra. |
readiness | Production-readiness heuristics. Off in the recommended setup. | Nothing. |
To add your own YARA rules, list the files in scanners.mcp_scanner.yara.extra_rules, each with the sha256: digest of the file. A scan loads them next to the bundled rules (set include_bundled: false to use only yours), and only from bytes that match the digest:
scanners:
mcp_scanner:
yara:
extra_rules:
- path: C:\ProgramData\DefenseClaw-Yara\marker.yar
digest: sha256:<sha256 of the file>A pin that does not match its file is refused where the config is applied: the managed lifecycle (ensure, install, upgrade, Setup) names the key and changes nothing, and the gateway rejects a reload with policy_reload_rejected, keeping the policy it last built. A rule file edited in place under its pin is rejected the same way; until you pin the new digest or restore the file, MCP scans that load it fail closed.
Automatic selection never fails a scan for a missing optional key: a configured cloud model without its key falls back to YARA and prints warning: LLM analyzer skipped: DEFENSECLAW_LLM_KEY is not configured; continuing with local analyzers. An explicit list is honored exactly as written: one that names llm fails every scan until a judge is configured.
A clean verdict means every selected analyzer read every tool. If the YARA analyzer, the bundled DefenseClaw YARA rules or the Cisco AI Defense API analyzer fails on a tool, or the bundled rules are missing from the installation, the scan fails with the scan of MCP server '<name>' is incomplete, so it has no verdict (or names the missing rules) and admission blocks the server as not scanned. Only the LLM analyzer degrades with a warning, as described above.
To add the Cisco AI Defense analyzer to YARA and a configured judge:
defenseclaw keys set CISCO_AI_DEFENSE_API_KEY
defenseclaw config set scanners.mcp_scanner.analyzers --json '["yara", "llm", "api"]'Go back to automatic selection with an empty list:
defenseclaw config set scanners.mcp_scanner.analyzers --json '[]'The setup wizard
defenseclaw setup mcp-scanner # interactive
defenseclaw setup mcp-scanner \
--non-interactive \
--analyzers auto \
--scan-prompts --scan-resources --scan-instructions--analyzers auto runs YARA, and the judge as well once defenseclaw setup llm has a model and key. Name llm yourself (--analyzers yara,llm) only when a judge is set up: with no judge every scan then fails with LLM analyzer requested but MCP_SCANNER_LLM_API_KEY not configured, and mcp set adds nothing.
| Flag | What it sets |
|---|---|
--analyzers <list> | Comma-separated analyzers: yara, llm, api, behavioral, readiness. auto stands for YARA plus a ready judge, and auto,llm is saved as yara and llm. |
--llm-provider <name> | Judge provider: any provider defenseclaw setup llm knows, or openai-compatible. |
--llm-model <id> | Judge model. |
--api-endpoint <url>, --api-key-env <NAME>, --api-timeout-ms <n> | Cisco AI Defense settings, saved in cisco_ai_defense. --api-key-env takes the variable's name, never the key. |
--scan-prompts, --scan-resources, --scan-instructions (each with a --no- form) | Also scan the server's prompts, resources and instructions on every scan. |
--verify / --no-verify | Run the doctor scanner checks after saving (default on). |
With --non-interactive, a flag changes only what it names. The LLM flags write the top-level llm: block, which the guardrail judge and the skill and plugin scanners share. For a local server, pass --llm-base-url <url> (for vllm and openai-compatible), which saves llm.base_url, or use defenseclaw setup llm --base-url <url>. Neither needs a gateway restart.
The judge
With judge_source: inherit (the default) the judge is DefenseClaw's llm: block: provider, model, key and base URL. Set it once with defenseclaw setup llm; see Unified LLM key for how the key resolves. The recommended model is anthropic/claude-sonnet-5-5.
To give the MCP scanner its own judge, fill its llm block and switch the source. The two keys are validated together, so unset judge_source first when it is set to inherit:
defenseclaw config unset scanners.mcp_scanner.judge_source
defenseclaw config set scanners.mcp_scanner.llm.provider anthropic
defenseclaw config set scanners.mcp_scanner.llm.model claude-sonnet-5-5
defenseclaw config set scanners.mcp_scanner.llm.api_key_env ACME_MCP_JUDGE_KEY
defenseclaw config set scanners.mcp_scanner.judge_source overrideFields you leave empty in the scanner's llm block fall back to the top-level block. To go back to the shared judge, unset judge_source and then llm, in that order. The validator refuses inherit with a filled llm block, and override without llm.model; when it does, config set names the rule, for example config.yaml was not changed: scanners.mcp_scanner.llm.model: judge_source: override needs a model. Correct the value, then run again., and leaves the file as it was.
No LLM configured
Start with a judge. Run defenseclaw setup llm and pick a provider, or serve a local model and point DefenseClaw at it:
defenseclaw setup llm
defenseclaw keys set DEFENSECLAW_LLM_KEYFor a local judge, serve an OpenAI-compatible model with vLLM and give DefenseClaw its URL. Pass disable_any_whitespace, or vLLM can pad the judge's JSON answer with whitespace up to the token limit and the analysis is lost:
vllm serve /models/acme-judge-8b --served-model-name acme-judge-8b \
--structured-outputs-config '{"backend": "xgrammar", "disable_any_whitespace": true}'
defenseclaw setup llm --provider vllm --model acme-judge-8b --base-url http://127.0.0.1:8000/v1 --non-interactiveUntil a judge works, automatic selection runs YARA alone, so the server is still scanned. When a model is set but its key is missing, each scan prints LLM analyzer skipped with the name of that key; with no model set, it prints nothing. Treat that as a gap to close, not a setup: YARA matches known patterns, and it is the judge that reads a tool's description against what the tool does.
Removed keys
scanners.mcp_scanner.api and scanners.mcp_scanner.timeouts are not configuration keys, and defenseclaw config set refuses them. The api analyzer uses cisco_ai_defense.endpoint and cisco_ai_defense.api_key_env. A local stdio scan on native Windows stops the server's process tree after 60 seconds.
Pinned version
DefenseClaw pins cisco-ai-mcp-scanner 4.3.0, which needs Python 3.11 or newer (defenseclaw doctor shows Scanner: mcp-scanner with the installed version and warns when it differs from the pin). The package is the PyPI wheel, pinned by URL and hash in pyproject.toml.
It stays on 4.3.0 on purpose. Later mcp-scanner releases pin LiteLLM to one exact version with a known vulnerability, CVE-2026-84377: every 4.8.x release (4.8.5 included) pins litellm==1.93.0, which is fixed only in 1.93.2. DefenseClaw requires LiteLLM 1.103.10 or newer on the 1.103 line, and 4.3.0 is the newest mcp-scanner whose metadata allows it. DefenseClaw moves to 4.8.x when upstream publishes a release that relaxes the LiteLLM pin. Do not upgrade the scanner or LiteLLM by hand; the supported repair path restores the pinned set. The skill scanner has its own pin, above.
Continuous protection
MCP servers are admitted through the CLI, admitted when the agent's own commands add them, and rescanned on a schedule:
On managed Windows, the Claude Code and Kiro MCP servers of enrolled users, including project servers inside their profiles, receive the install-watcher scan: the scanner runs in the gateway service and the hook enumerator starts each server as its user, from the definition it published, in a folder it checked as that user. A user who is not signed in has their servers blocked until they sign in. See MCP servers in user profiles.
On managed Linux and macOS the gateway service cannot read home folders. The
Claude Code and Codex hooks read the server definition as the user and send it
with the tool call, and the gateway scans and admits a URL server (for example
one added with claude mcp add --transport http) at its first tool call: that
call is refused as still scanning, and a call after the verdict is decided by
it. A local (stdio) server of an enrolled user is not started by the gateway on
these platforms, so it gets no install scan; asset_policy.mcp lists still
apply to its calls.
Scan on add. defenseclaw mcp set <name> ... scans the server before
writing it into the connector's MCP config, unless you pass --skip-scan.
A scan failure stops the add.
Admit what the agent adds. The gateway reads every configured
connector's servers in every scope, including Claude Code's local scope
(claude mcp add) and each project's .mcp.json for every project Claude
Code knows, and within about 30 seconds scans and admits a server it has
not seen before, as mcp set would. A server that was there when the
gateway started is admitted the same way, except at the first start after
an upgrade from 0.8.x: the servers the earlier release already ran are
scanned once to record their baseline and keep running, so findings raise
alerts and a server the scanner cannot start shows scan failed instead
of being blocked. A server on a block list stays blocked. While a new
server's admission scan is pending, per-user default and permissive hooks
allow its tool calls with a warning that names the server; strict and
managed hooks block with retry guidance based on the scan timeout. The
gateway starts admission at once. A completed failed or rejected scan
blocks tool calls in every tier. Claude Code may already have started the
server's process when it opened the project. With
gateway.watcher.mcp.take_action: false, the pending gate is off;
explicit denies and completed scan failures still block.
Act on the verdict. The top severity maps through admission.mcp (below):
with the built-in defaults, only CRITICAL blocks the install and disables
the server. A HIGH, MEDIUM or LOW verdict admits the server with an
install-warning audit row, and its tool calls go ahead. Set
admission.mcp.actions.high: quarantine for strict admission.
Rescan. The gateway re-checks configured servers on a schedule
(watch.rescan_enabled, every watch.rescan_interval_min minutes; 60 by
default) and rescans a server when its entry or the scanner settings
changed. A config reload restarts the install watcher in place with the
new settings, so changing analyzers or the judge takes effect on the next
scan with no gateway restart. Set gateway.watcher.mcp.take_action: false
to record verdicts without acting on them.
For one-shot scans in CI or a daily job, run defenseclaw mcp scan --all. The
findings still enter mandatory local history and every matching v8
observability destination.
Configure the action mapping
The scanner produces a severity. What that severity does is set in config.yaml under admission:: admission.mcp.actions first, then admission.defaults.actions, which every asset type inherits. Unlike the skill scanner, the MCP scanner has no gate keys (fail_on_severity and review_queue_min belong to the skill scanner), so the action map is the control. Balanced admission quarantines CRITICAL servers and warns on HIGH, MEDIUM, LOW and INFO findings. The scan finding and warning are audited:
admission:
defaults:
actions: {critical: quarantine, high: quarantine, medium: warn, low: warn, info: warn}
mcp:
actions:
high: warn
medium: warn
low: warnAn action is block, quarantine, warn or allow, or the exact {install, file, runtime} triple (see Skill scanner). Change one severity with config set, and read the map in force with config get:
defenseclaw config set admission.mcp.actions.medium warn
defenseclaw config get admission.mcp --effectivedefenseclaw policy edit scanner --type mcp -s <severity> ... edits the same admission.mcp.actions. defenseclaw policy activate <name> writes a named policy's actions for every asset type as explicit maps, replacing your edits. Admission documents the whole block.
For strict MCP admission, set admission.mcp.actions.high: quarantine (and any other severities your organization chooses to refuse). Secure Client keeps its separate closed admission.
Block / allow individual servers
The scanner refuses loopback, private, link-local and multicast URLs, and starts only npx or uvx stdio servers. The rules, the error text and the ways to admit a server are in the next two sections.
Servers on local and internal addresses
The scanner does not connect to loopback (localhost, 127.0.0.1), private (10.x, 172.16-31.x, 192.168.x), link-local (169.254.x), carrier-grade NAT (100.64.x to 100.127.x) or multicast addresses, or to a host name that resolves to one:
error: scan failed: refusing to scan MCP URL 'https://10.20.30.40:8080/mcp': host '10.20.30.40' resolves to private address 10.20.30.40 (use --allow-private to opt in)From your shell, add --allow-private to scan such a server. The scan the gateway runs when a server is added has no such option, so the server is not scanned and admission blocks it. Its install-scan-error audit row says the MCP scanner does not connect to loopback, private, link-local or multicast addresses ... so the server was not scanned and names two ways to admit a server you trust:
- Allow it by name and URL with
defenseclaw mcp allow <name>, orasset_policy.mcp.allowedin the admin config on a managed device (the managed launcher refusesmcp). An allowed server is not scanned. - Set
admission.mcp.scan_on_installtofalse, which admits new MCP servers without a scan.
Servers started by a command (stdio) are scanned on your computer and are not affected.
A block follows the name. An allow is pinned to the server you reviewed: mcp allow copies its url, or its command and arguments, from the connector's MCP config into the rule, so a different server added later under the same name is scanned again. For a server that is not configured yet, pass --url, or --command and --args; otherwise the rule matches the name only and the command prints a note saying so.
defenseclaw mcp unblock <name> removes the server's block or allow entry, and its quarantine and disable state, so its scan verdict decides again. It says which entry it removed. Run defenseclaw mcp scan <name> afterwards to scan it now. With --connector, it clears only that connector's state.
When a server's latest scan failed, mcp list shows scan failed and a Severity of -, then a footer with one next step per server:
! 1 MCP server(s) could not be scanned (last scan failed): internal-docs (claudecode)
internal-docs (claudecode): refused, the URL is a private or loopback address; to scan it anyway: defenseclaw mcp scan internal-docs --connector claudecode --allow-privateAn older result is kept only as last_good_severity in mcp list --json, next to last_scan_error.
Local servers: npx and uvx only
A local (stdio) scan starts the server as you. DefenseClaw starts only npx or uvx with a package argument (npx.cmd and uvx.exe on Windows). A server started with node, python3, docker or a binary is refused:
not an allowlisted stdio launcher (allowed: npx, uvx)Pick one:
- publish it as an npm or PyPI package and start it with
npxoruvx; - serve it over HTTP and add it with
--url; - review it yourself, then
defenseclaw mcp allow <name> --command <cmd> --args '<json array>'and runmcp setagain. The pinned allow skips the scan for that definition only.
How the settings reach the scanner
Everything the scanner does comes from config.yaml. The gateway runs defenseclaw mcp scan --json for each scan, passing --analyzers and the three --scan-* flags from config, and the scan clears any inherited MCP_SCANNER_*, AI_DEFENSE_*, VIRUSTOTAL_*, SKILL_SCANNER_* and ENABLE_*_ANALYZER variable before it starts, so a value exported in your shell cannot change it. The judge's provider variables are derived from the resolved llm: settings. Any non-zero exit makes the scan a failure, and the install watcher fails closed on a failed scan.
Scanner settings are part of the effective policy digest, and a change applies without a gateway restart (config set prints a restart hint only for keys that need one).
A local scan runs the server
A local stdio scan starts the server as an ordinary subprocess that runs as
you. It is not isolated: while it runs, the server can reach whatever your
user can. DefenseClaw narrows what it starts. It launches only servers
started through npx or uvx with a package argument, refusing shell
interpreters, file paths, and code-evaluation flags (on native Windows, Codex
Desktop's bundled node_repl.exe is also accepted after ownership checks).
The subprocess does not inherit your shell environment: it gets a small
baseline such as PATH and HOME, plus the server entry's own env block,
minus any entry that would change what the launcher runs.
On native Windows the scan also stops the server's whole process tree after
60 seconds. On macOS and Linux DefenseClaw sets no time limit of its own; the
scan relies on the MCP scanner SDK's own timeouts. Scan only servers you would
be willing to run.
Scanner processes run under the gateway's process-tree supervisor. How it ends them and its known limits: Scanner processes are supervised.
1.0.7 local scan limit
GAP-0499: on macOS and Linux, a stdio server started for defenseclaw mcp scan can leave a long-lived child after the scan ends. The scan result does not prove that child stopped. Check and stop a remaining child process by its PID before starting another scan.
Availability and recovery
cisco-ai-mcp-scanner is declared for Python 3.11 and newer. DefenseClaw
itself needs Python 3.11 to 3.13 (the package refuses Python 3.10), so every
supported runtime includes MCP scanning.
On Python 3.11 or newer, an absent SDK means the environment is incomplete. Do
not patch a managed virtual environment with pip; use the
supported install or repair path. Source
contributors should synchronize the checkout's locked environment with
uv sync.
defenseclaw mcp exits cleanly with a concise dependency error if the SDK
isn't present; it never crashes the gateway.
Upgrading from v8
defenseclaw config migrate (and defenseclaw upgrade, which runs it) moves the v8 scanner keys to the ones above. The gateway reads a v8 file in memory until you migrate it; a v9 file rejects the old keys. Full record: Migrating to v9.
| v8 | v9 |
|---|---|
analyzers: auto or empty | analyzers: [] |
analyzers: "yara,llm" (comma-separated string) | analyzers: [yara, llm] |
analyzers: "auto,llm" (what the old wizard wrote, which dropped YARA) | analyzers: [yara, llm] |
a filled llm block | judge_source: override |
binary | removed; DefenseClaw runs the scanner it ships |
See also
- Skill scanner: the sibling scanner for skills, with the same admission pattern
- Unified LLM key: the
llm:block the judge inherits and how its key resolves - Block or allow an asset: the
asset_policylists and which rule wins - Admission: the
admission:block and the actions per severity - Migrating to v9: the v8 to v9 key moves
- CLI reference: every
defenseclaw mcpsubcommand
Skill scanner
Scan connector skills on demand and whenever one is installed or changed. DefenseClaw wraps cisco-ai-skill-scanner with the recommended quiet policy and an LLM judge, and writes its verdicts into the same admission policy as the watcher.
Registries
Subscribe DefenseClaw to public or internal skill / MCP catalogs. Sources are fetched, scanned, and clean entries are auto-promoted into asset_policy so admission decisions can attribute the rule back to its origin.