---
name: clawscan-cli
description: Use when running or explaining the ClawScan CLI, including one-off agent-skill scans, benchmark runs, scanner fixtures, judge harness commands, env var validation, and interpreting clawscan-run-v1 and clawscan-benchmark-v1 artifacts.
---

# 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:

```bash
go run ./cmd/clawscan <target> --scanner <scanner-id> [flags]
```

Use the installed binary when available:

```bash
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:

```bash
clawscan --help
clawscan -h
clawscan --version
clawscan scanners
clawscan profiles
clawscan benchmark list
```

Unless `--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:

```yaml
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:

```text
agentverus, aig, aig-mcp, cisco, relyable, skillspector, snyk, socket
```

Credential 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:

```bash
clawscan install aig cisco skillspector
```

`clawscan 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:

```bash
clawscan ./my-skill \
  --scanner skillspector \
  --scanner-result skillspector=./fixtures/skillspector.json \
  --json
```

The 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:

```text
cuhk-zhuque/SkillTrustBench
clawhub-security-signals
```

Run SkillTrustBench with the canonical Hugging Face ID or the short alias
`SkillTrustBench`:

```bash
clawscan benchmark SkillTrustBench \
  --limit 10 \
  --scanner skillspector \
  --output /tmp/clawscan-benchmark.json
```

SkillTrustBench 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:

````md
```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:

```bash
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`, or
  `clawscan benchmark <benchmark-id>`.
- Do not assume `clawscan` scans `.`; no target means discover `./skills`.
- Do not expect a profile judge when passing explicit `--scanner` flags without
  `--profile`.
- Do not use benchmark flags such as `--split`, `--limit`, or `--offset`
  outside `clawscan benchmark <benchmark-id>`.
- Do not use `--config` without `--profile` for 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 off` is 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.
