ClawScan CLI
Overview
Use ClawScan to run one or more security scanners against agent skills, preserve
raw scanner evidence, and optionally pass the evidence to an external judge
harness. The public CLI is general-purpose; ClawHub-specific parity helpers
belong outside cmd/clawscan. Keep secrets in environment variables, never CLI
flags.
Command Surface
Run from the repo root during development:
go run ./cmd/clawscan <target> --scanner <scanner-id> [flags]Use the installed binary when available:
clawscan <target> --scanner <scanner-id> [flags]Choose the run mode:
| Need | Shape |
|---|---|
| Scan repo skills with one scanner | clawscan --scanner skillspector from a repo with ./skills/<name>/SKILL.md |
| Scan repo skills with the ClawHub profile | clawscan --profile clawhub from a repo with ./skills/<name>/SKILL.md |
| Scan one explicit target with a profile | clawscan ./my-skill --profile clawhub |
| Capture raw scanner evidence only | clawscan ./my-skill --scanner skillspector |
| Print raw JSON to stdout | Add --json. |
| Run all profiles from a config | clawscan ./my-skill --config ./security/clawscan.yml |
| Run one config profile | clawscan ./my-skill --config ./security/clawscan.yml --profile review |
| Install scanner dependencies | clawscan install aig cisco skillspector |
| List scanner catalog | clawscan scanners |
| Inspect one scanner | clawscan scanners skillspector |
| List resolved profiles | clawscan profiles |
| Print resolved profile YAML | clawscan profiles -v |
| List benchmark catalog | clawscan benchmark list |
| Run SkillTrustBench | clawscan benchmark SkillTrustBench --limit 10 --scanner skillspector --output run.json |
| Run ClawHub Security Signals | clawscan benchmark clawhub-security-signals --split eval_holdout --limit 10 --scanner skillspector --output run.json |
| Use stable scanner evidence | Add --scanner-result <id=path> for each fixture-backed scanner. |
| Add or override a judge harness | Add --judge '<command with placeholders>'. |
| Override or skip the readable overview | Add --overview '<command>' or --no-overview. |
| Use host-installed scanner/judge CLIs | Add --sandbox off only in an already-isolated environment. |
Helpful metadata:
clawscan --help
clawscan -h
clawscan --version
clawscan scanners
clawscan profiles
clawscan benchmark listUnless --json is passed, ClawScan writes the full artifact to
./clawscan-results/artifact.json by default, preserves per-scanner JSON files
in the same visible results bundle, and prints a concise key/value summary
ending in full_results: ./clawscan-results/artifact.json. Use
--output <path> to choose a different artifact path; explicit .json paths
keep that artifact file and write scanner JSON beside it.
Targets, Profiles, And Config
If no target is passed with --scanner, --profile, or --config, ClawScan
scans child skill directories under ./skills. If ./skills is missing or
contains no children with SKILL.md, it fails with a target-discovery error.
Plain clawscan without --scanner, --profile, or --config is invalid.
Benchmark runs use clawscan benchmark <benchmark-id> and do not accept scan
targets.
Built-in profiles:
| Profile | Scanners | Judge |
|---|---|---|
clawhub |
skills: skillspector, aig; plugins: only aig-mcp |
evidence-only Codex judge plus an evidence-only Codex overview |
clawhub-template |
aig-mcp over the whole shipped Template |
unchanged evidence-only verdict judge plus optional overview; see docs/template-audit.md |
clawhub-aig |
skillspector, aig |
same judge and overview as clawhub |
openclaw-install-policy |
skillspector |
none |
Profiles are loaded from embedded built-ins. Project .clawscan.yml /
.clawscan.yaml files are NOT loaded automatically: pass --config <path> to
load a specific config, or --discover-config to load the nearest one found
upward from the current directory. A project profile with the same name shadows
the built-in whole profile. --config <path> without --profile runs every
profile in that config and emits a clawscan-batch-v1 artifact. Discovery is
off by default because project configs can define scanner commands that execute
with the caller's environment and credentials.
Use clawscan profiles to inspect the built-in profile catalog. Use
clawscan profiles -v to print it as pasteable YAML.
CLI flags override the selected profile for one run. Passing --scanner
without --profile creates an ad hoc scanner-only run, so profile judges are
not invoked accidentally.
Minimal config:
version: 1
sandbox:
mode: docker
env:
- OPENAI_API_KEY
- CODEX_API_KEY
profiles:
review:
scanners:
- skillspector
json: true
judge:
command: judge --out {{ output }}sandbox.env is an allowlist of env var names to pass into the Docker runtime;
store names there, not secret values. CLI equivalents are --sandbox,
--sandbox-image, and repeatable --sandbox-env.
Scanners
Use clawscan scanners for the registry-backed scanner catalog and
clawscan scanners <scanner-id> for one scanner's repository, description,
env vars, and install guidance.
Accepted scanner IDs:
agentverus, aig, aig-mcp, cisco, relyable, skillspector, snyk, socketCredential rules:
| Scanner | Env vars |
|---|---|
aig |
required: LLM_API_KEY or OPENAI_API_KEY; optional local scanner config: DEFAULT_MODEL, DEFAULT_BASE_URL, DEFAULT_MODEL_CONTEXT_WINDOW, LOG_LEVEL |
aig-mcp |
plugin and Template targets; required: LLM_API_KEY or OPENAI_API_KEY; optional: DEFAULT_MODEL, DEFAULT_BASE_URL (same defaults as aig), DEFAULT_MODEL_CONTEXT_WINDOW; AIG_MCP_SCAN_ALLOW_HOST_EXEC=1 for --sandbox off |
socket |
required: SOCKET_CLI_API_TOKEN |
snyk |
required: SNYK_TOKEN |
skillspector |
optional provider config: SKILLSPECTOR_PROVIDER, SKILLSPECTOR_MODEL, NVIDIA_INFERENCE_KEY, OPENAI_API_KEY, OPENAI_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_PROXY_ENDPOINT_URL, ANTHROPIC_PROXY_API_KEY |
cisco |
optional upstream analyzers: SKILL_SCANNER_LLM_*, SKILL_SCANNER_META_LLM_*, VIRUSTOTAL_API_KEY, AI_DEFENSE_API_KEY, AI_DEFENSE_API_URL |
Artifact env fields record only present or missing; they must never contain
secret values. GenDigital/Gen Agent Trust Hub is not a built-in scanner because
there is no local CLI for ClawScan to invoke.
Dependency setup:
clawscan install aig cisco skillspectorclawscan install accepts one or more scanner IDs. It follows upstream scanner
install docs where they publish an install command, including A.I.G's
pip install aig-skill-scan, Cisco's uv pip install cisco-ai-skill-scanner, SkillSpector's
uv tool install git+https://github.com/NVIDIA/skillspector.git, Socket's
npm install -g socket, and AgentVerus'
npm install --save-dev agentverus-scanner. Snyk is launcher-based, so
ClawScan verifies uvx; built-in and simple API-backed scanners are skipped.
The aig adapter runs aig-skill-scan --repo <target> --language en -o <result.sarif.json> and stores the SARIF 2.1.0 document as raw scanner
evidence. The aig-mcp adapter copies an OpenClaw plugin directory
without node_modules and runs aig-mcp-scan 0.2.0 on that copy with an
OpenClaw plugin audit prompt. The clawhub profile runs only aig-mcp for
plugins. It runs in the Docker sandbox, whose runtime image removes the
scanner agent's shell and file-write tools; --sandbox off requires
AIG_MCP_SCAN_ALLOW_HOST_EXEC=1.
Starting in ClawScan v0.1.2, aig no longer uses the legacy A.I.G Docker/API
service. Replace AIG_MODEL with DEFAULT_MODEL, AIG_MODEL_BASE_URL with
DEFAULT_BASE_URL, and AIG_MODEL_API_KEY with LLM_API_KEY or
OPENAI_API_KEY; AIG_BASE_URL and AIG_API_KEY are retired. The local
scanner accepts directory targets only.
For normal runs, command-backed scanners and judges run in
ghcr.io/openclaw/clawscan-runtime:latest. clawscan install is mainly for
local development or --sandbox off environments.
Use --scanner-result when a test or fixture should supply stable scanner JSON:
clawscan ./my-skill \
--scanner skillspector \
--scanner-result skillspector=./fixtures/skillspector.json \
--jsonThe scanner must still be requested with --scanner or via the selected
profile.
Benchmarks
Use clawscan benchmark list for the registry-backed benchmark catalog.
Supported benchmarks:
cuhk-zhuque/SkillTrustBench
clawhub-security-signalsRun SkillTrustBench with the canonical Hugging Face ID or the short alias
SkillTrustBench:
clawscan benchmark SkillTrustBench \
--limit 10 \
--scanner skillspector \
--output /tmp/clawscan-benchmark.jsonSkillTrustBench uses split benchmark. The first live run downloads and caches
benchmark_full_v1.0.zip, then extracts only the requested case directories
into temporary scan targets.
Use --ids <path-or-url> with SkillTrustBench to run a fixed subset from a
plain text file with one ID per line or JSONL rows with an id field. The
source is streamed and may contain at most 5,520 unique IDs, at most 256 bytes
per trimmed ID, and at most 256 KiB (262,144 bytes) of retained ID text. These
are selection limits, not a total source-size limit; JSONL sources may exceed
256 KiB. Individual lines must be smaller than the parser's 1 MiB buffer limit. --ids
preserves source order, records idsSource, idsCount, and idsSha256 in the
artifact, and is mutually exclusive with --limit and --offset.
ClawHub Security Signals splits: train, validation, test,
eval_holdout. --limit 0 means run the full selected split. Use --offset
with --limit for reproducible chunks.
For clawhub-security-signals, --output ./clawscan-benchmark.json also
writes ./predictions.jsonl. Use --predictions-output <path> to choose
another path. --predictions-output is only supported for
clawhub-security-signals.
Benchmark artifacts use clawscan-benchmark-v1. Each case embeds the normal
clawscan-run-v1 artifact, expected verdict metadata, and evaluation status.
The summary includes case counts, scanner/judge statuses, and accuracy over
scored cases. Inspect the JSON artifact for full evidence.
Judge Harness
--judge runs through the platform shell and must produce a JSON object on
stdout or at {{ output }}.
Important placeholders:
| Placeholder | Meaning |
|---|---|
{{ workspace }} |
Temporary judge workspace with copied target files, scanner JSON, and metadata. |
{{ prompt }} / {{ prompt:path }} |
Render prompt template and interpolate the rendered prompt path. |
{{ output_schema }} / {{ output_schema:path }} |
Copy schema and interpolate the copied schema path. |
{{ output }} |
Path where the judge should write final JSON. |
Prompt files can reference requested scanner JSON:
```json
{{ scanners.skillspector }}
```If a prompt references an unrequested scanner, ClawScan should fail clearly.
The built-in clawhub profile uses this same judge mechanism with embedded
policy and output-schema files: an evidence-only Codex run (evidenceOnly: true, no artifact copy, file/shell/web/code tools disabled) decides from {{ scanner_results }} and
writes judge.result (verdict, confidence, dimension statuses and finding
predicates). Its evidence-only overview.command then runs Codex with
{{ judge.result }} and the scanner results and writes readable prose to
overview.result. Overview failures are recorded
but never change the verdict, gate, or exit status.
Verification
Use fixture-backed scanner smokes for local proof because they do not need secrets, scanner binaries, or Docker:
printf '{"status":"clean","findings":[]}' > /tmp/skillspector.json
go run ./cmd/clawscan ./README.md --scanner skillspector --scanner-result skillspector=/tmp/skillspector.json --sandbox off --output /tmp/clawscan-smoke.json
go run ./cmd/clawscan --help
go test -count=1 ./...
go vet ./...Common Mistakes
- Do not pass API keys as CLI flags.
- Do not run plain
clawscan; choose--scanner,--profile,--config, orclawscan benchmark <benchmark-id>. - Do not assume
clawscanscans.; no target means discover./skills. - Do not expect a profile judge when passing explicit
--scannerflags without--profile. - Do not use benchmark flags such as
--split,--limit, or--offsetoutsideclawscan benchmark <benchmark-id>. - Do not use
--configwithout--profilefor benchmark runs; all-profile config runs are target scans only. - Do not assume host-installed scanner CLIs are used by default; command-backed
scanners and judges use the Docker runtime unless
--sandbox offis set. - Do not add unsupported dataset names; built-ins are SkillTrustBench and
clawhub-security-signals. - Do not assume scanner failures are final policy verdicts; scanner output is raw evidence for comparison or judging.
For Template auditing, pass the validated extracted package directory to clawscan ./package --profile clawhub-template. Identity comes from the safe package.json.openclaw.template CLAW.md selector (which may be nested); all shipped files including node_modules are staged. Do not resolve/download external dependencies or fetch their ClawHub audits. Only AIG reads the artifact; the unchanged evidence-only judge converts scanner evidence to the publication verdict. New profile/prompt code needs a candidate Go binary and a verified source/runtime binding, not the old image. See docs/template-audit.md for the consumer and rollout contract.