Skill scanner

Agents are getting comfortable installing skills. A "skill" is a small bundle — instructions, optional tools, sometimes auto-applied — that an LLM picks up and follows. The same shape is also a great place to hide a prompt-injection or an exfiltration tool.

DefenseClaw integrates Cisco's open-source cisco-ai-skill-scanner so operator-installed and modified skills get a deterministic + LLM-assisted review. Verdicts feed the skill_actions admission policy by severity bucket, and the install watcher scans every new or changed skill and quarantines it when the policy says so. Exact proven vendor bundles remain visible as discovery-only inventory and do not enter scanner or enforcement paths.

1{2  "skill": "workspace-helper",3  "severity": "critical",4  "findings": ["path_escape", "external_exfiltration_intent"],5  "file": "quarantined",6  "runtime": "disabled",7  "install": "blocked"28}1{2  "skill": "workspace-helper",3  "severity": "critical",4  "findings": ["path_escape", "external_exfiltration_intent"],5  "file": "quarantined",6  "runtime": "disabled",7  "install": "blocked"28}

What you just saw

The watcher scanned a new skill where it was installed. Deterministic checks and optional LLM-assisted intent analysis produced a CRITICAL result, which skill_actions mapped to quarantine (the files move out of the skill folder), disabled runtime, blocked installation, and an audit event.

What it scans

The wrapper at cli/defenseclaw/scanner/skill.py accepts four target shapes — all positional except --path. URL fetches in particular take the URL itself as the positional target (no --remote involved). The --remote flag does exist, but for a different scenario: it forwards the scan request to a sidecar API for a skill installed on a remote host (see the "Remote sidecar" tab below).

• Local skill name (my-skill) — resolves through configured connector skill directories. On a multi-connector install, a bare name checks matching connector copies; pass --connector <name> to force one connector's skill source.
• --path <dir> — scan a directory you specify, useful inside a skill repo's pre-commit hook.
• https://... — fetch a remote skill bundle into a temp dir, scan, then clean up. The downloaded bytes never touch your skill directory.
• clawhub://author/skill@version — same fetch-to-temp flow, but resolves through the configured Clawhub registry source.

For each skill it runs:

1. Static checks — manifest validation, allow-list of tool names, suspicious filesystem paths.
2. Optional LLM-assisted analysis — by default it runs when a model is configured for scanners.skill and is off otherwise; --use-llm / --no-use-llm turns it on or off for one scan. The upstream scanner auto-detects the provider from the LiteLLM-shaped provider/model string, so OpenAI, Anthropic, Bedrock, Gemini, Vertex AI, Azure, Groq, Mistral, DeepSeek, OpenRouter, Ollama, vLLM, and other LiteLLM-supported providers all work without special-casing.
3. A consolidated ScanResult with severity, findings, and (when applicable) a recommended action.

One-shot scan

defenseclaw skill scan --all

defenseclaw skill scan --path ./my-skill

defenseclaw skill scan https://github.com/some-org/skill-bundle/archive/refs/heads/main.tar.gz

defenseclaw skill scan clawhub://author/skill@1.2.0

defenseclaw skill scan my-skill --remote

Configure the scanner

defenseclaw setup skill-scanner chooses the analyzers, the scan policy and the optional external checks. Run it bare for the wizard, which asks about each analyzer in turn, or pass flags with --non-interactive:

defenseclaw setup skill-scanner                    # interactive

defenseclaw setup skill-scanner \
  --non-interactive \
  --use-behavioral \
  --use-llm --llm-provider anthropic --llm-model claude-sonnet-4-5 \
  --enable-meta \
  --policy balanced

With --non-interactive, the analyzer flags only turn analyzers on and leave the others as they are. To turn one off, run the wizard.

The LLM provider and model are written to the unified top-level llm: block, which the MCP and plugin scanners and the guardrail judge share. Cisco AI Defense settings stay in cisco_ai_defense.

For VirusTotal, store the key before you turn the check on (the wizard asks for it and saves it the same way):

defenseclaw keys set VIRUSTOTAL_API_KEY
defenseclaw setup skill-scanner --non-interactive --use-virustotal

Continuous protection: the install watcher

Running a one-shot scan is a starting point. The real value is the install watcher. It runs inside the gateway, is on by default, and watches the skill folders of every configured connector:

The order is check the lists → scan in place → act on the verdict. The skill is not hidden while the scan runs (scans time out after five minutes), so an agent session that is already open can see it in that window. A scan that fails counts as a block. Watcher implementation lives in internal/watcher/watcher.go.

You don't have to wire any of that yourself. To record the severity verdicts without acting on them, set gateway.watcher.skill.take_action: false in ~/.defenseclaw/config.yaml; block-list matches and failed scans are still quarantined.

Configure the action mapping

The scanner's verdict is a severity. What that severity does lives in the active OPA policy file (policies/<name>.yaml) under skill_actions. The schema is real per-severity buckets (not threshold floors):

admission:
  scan_on_install: true
  allow_list_bypass_scan: true                # first-party skills bypass scanning when the allow_list matches

skill_actions:
  critical:
    file:    quarantine
    runtime: disable
    install: block
  high:
    file:    quarantine
    runtime: disable
    install: block
  medium:
    file:    none                              # no filesystem action
    runtime: enable                            # agent can still call it
    install: none
  low:
    file:    none
    runtime: enable
    install: none
  info:
    file:    none
    runtime: enable
    install: none

first_party_allow_list:
  - target_type: skill
    target_name: codeguard
    reason: first-party DefenseClaw skill
    source_path_contains: [".openclaw/workspace/skills/codeguard", ".openclaw/skills/codeguard", ".zeptoclaw/skills/codeguard", ".claude/skills/codeguard"]

Each severity bucket has three independent actions:

• file — none or quarantine. Whether to move the skill bundle out of the agent's skill directory.
• runtime — enable or disable. Whether the agent can invoke the skill at all.
• install — none or block. Whether to refuse a fresh install.

first_party_allow_list is a policy-file key (not ~/.defenseclaw/config.yaml) — bundles whose source path contains any of the listed substrings are exempted from skill_actions. The shipped file also lists the first-party DefenseClaw plugin. See Policies for the full schema and Defaults for what each shipped rule pack sets these to.

To switch profiles for the entire skill_actions table:

defenseclaw policy activate strict       # quarantines medium+ — see Defaults page for the diff
defenseclaw policy activate default      # quarantines high+
defenseclaw policy activate permissive   # quarantines critical only

Provide the LLM key (optional but recommended)

LLM-assisted analysis is what catches the new malicious skills you don't yet have a regex for.

defenseclaw keys set DEFENSECLAW_LLM_KEY

Under the hood DefenseClaw injects the unified key into the scanner subprocess as SKILL_SCANNER_LLM_API_KEY and SKILL_SCANNER_LLM_MODEL, plus the matching provider-native variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, AWS_BEARER_TOKEN_BEDROCK, GOOGLE_API_KEY, AZURE_OPENAI_API_KEY, GROQ_API_KEY, etc.) via inject_llm_env. See Unified LLM key for the resolution order and Bifrost provider catalog.

Availability and recovery

cisco-ai-skill-scanner is a hard runtime dependency, and supported release-managed runtimes include it. If it is absent from a packaged runtime, treat the installation as damaged; do not patch its managed virtual environment with pip. Use the supported install or repair path. Source contributors should synchronize the checkout's locked environment with uv sync.

If the SDK is missing when you run a scan, DefenseClaw prints a concise dependency error and exits cleanly; it does not crash the gateway.

Manage individual skills

The watcher's verdict is the default. Operators always have manual override:

defenseclaw skill list                              # on-disk skills + state, across ALL active connectors
defenseclaw skill list --connector codex            # one connector
defenseclaw skill scan my-skill --connector codex   # scan Codex's matching copy
defenseclaw skill block my-skill --reason "untrusted publisher"
defenseclaw skill block my-skill --connector codex --reason "Codex-only override"
defenseclaw skill quarantine my-skill --reason "review pending"
defenseclaw skill restore my-skill                    # un-quarantine
defenseclaw skill allow my-skill --reason "vetted"
defenseclaw skill unblock my-skill                    # clear block, file and runtime state
defenseclaw skill disable my-skill                    # runtime off, file untouched
defenseclaw skill enable my-skill
defenseclaw skill info my-skill                       # detailed view

To install a skill through the scanner, use defenseclaw skill install <name>. It installs a copy into each configured connector's skill directory and scans each copy. By default it only reports findings; pass --action to apply skill_actions. Pass --force to overwrite an existing skill and --connector to install for one connector. defenseclaw skill search <query> searches the ClawHub registry with a locally installed or npx-cached clawhub client. Add --allow-remote-fetch only if you accept that npx downloads and runs the clawhub package from the npm registry.

Without --connector, policy and runtime commands apply to matching configured connector copies where present or the unscoped fallback policy where that command uses one. Pass --connector <name> when the same skill exists under more than one connector and you want only that connector's copy.

skill list, skill info, skill scan and the AIBOM inventory report the same policy verdict: blocked, quarantined or allowed from an explicit action, otherwise rejected, warning or clean from the latest scan and the skill_actions mapping. The list's Status column only says whether the skill is loaded (ready), removed from disk (removed) or missing. A rejected verdict means the policy refuses the skill at install time. A copy that is already on disk stays loaded until you run skill block, skill disable or skill quarantine, or accept it with skill allow.

Every action is audited (skill-block, skill-quarantine, etc.) so the trail is intact even when the manual override contradicts the watcher.

See also

• MCP scanner — sibling scanner for MCP servers, same admission pattern via mcp_actions
• Unified LLM key — the env var the LLM-assisted analysis reads
• Defaults — the skill_actions table for each shipped rule pack
• Policies — the layered architecture (admission → scanner → action mapping)
• Reference → CLI — full defenseclaw skill subcommand reference