Overview
OpenClaw skills are Python or TypeScript packages that extend the agent. DefenseClaw scans them through the watcher pipeline and through the operator command defenseclaw skill scan. The scanner itself is Cisco's skill_scanner Python SDK — DefenseClaw wires it into the verdict pipeline, feeds findings to the audit store, and applies the OPA admission module.
Configure it
defenseclaw setup skill-scanner
The interactive wizard surfaces the settings implemented in cmd_setup.py: behavioral analysis, LLM analysis, meta-analyzer filtering, trigger checks, VirusTotal, Cisco AI Defense, unified LLM provider/model, consensus runs, policy preset, and lenient parsing.
Non-interactive form:
defenseclaw setup skill-scanner \
--non-interactive \
--use-behavioral \
--use-llm \
--enable-meta \
--llm-provider openai \
--llm-model gpt-4o-mini \
--policy balanced
See the autogenerated setup command page for all flags.
What each analyzer catches
| Analyzer | Signal | Example |
|---|---|---|
| Injection | Prompt-injection / command-injection patterns in skill YAML and inline code | system("{{ user_input }}"), templated shell |
| Secrets | API keys, tokens, connection strings embedded in skill files | sk-ant-api03-..., AWS access keys |
| Malicious tools | Unsafe tool bindings: exec, eval, destructive FS ops without confirmation | subprocess.run(shell=True) |
| Obfuscation | Base64-embedded code, high-entropy strings, unused indirection | exec(base64.b64decode(...)) |
| Trust divide | Skills that cross privilege boundaries without explicit declaration | Skill marked trust=untrusted that invokes a trusted tool |
Findings are shaped as EventScanFinding rows in the audit store (see schemas) with rule_id, line_number, severity, and scanner=skill. The OPA module at policies/rego/admission.rego consumes them to decide admission.
Profiles
| Profile | Severity floor | Analyzer set |
|---|---|---|
permissive | Lower-noise scanner policy | Minimal analyzer posture for early rollout |
balanced | Default scanner policy | Behavioral + semantic checks when enabled |
strict | Higher-sensitivity scanner policy | Use when false positives are acceptable during hardening |
The policy value is saved under scanners.skill_scanner.policy; analyzer toggles live under the same scanners.skill_scanner block, while shared LLM values land in the top-level llm: block.
Verify it worked
defenseclaw skill scan some-skill --path ~/.claw/skills/some-skill
defenseclaw status | grep -i scanner
defenseclaw skill scan prints findings in a table and supports --json for CI gates.
Undo
defenseclaw setup skill-scanner --non-interactive --policy permissive
Or edit config.yaml directly if you need a setting that is not exposed through the setup wizard.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
skill-scanner: not installed in init | Python wheel missing the SDK | Reinstall with pip install defenseclaw (bundled) or pip install skill-scanner |
| Many findings after upgrade | Policy drift from a new default ruleset | Run defenseclaw skill scan <name> --json and triage; set --policy permissive temporarily |
| LLM checks do not run | Unified llm: provider/model or key is missing | Run defenseclaw setup skill-scanner interactively or set DEFENSECLAW_LLM_KEY |