Index of every page on this site: llms.txt
All skills
openclaw avatar

/clawscan-cli

@7b51dc8
by openclawopenclaw/clawscan156 stars
30
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/openclaw/clawscan/clawscan-cli

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈62 tokens for metadata: the name and description. ≈3.5k when used: this file. ≈53 more on demand in 1 file.

Description uses 3.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈248 characters, or 3.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

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

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:

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:

cuhk-zhuque/SkillTrustBench
clawhub-security-signals

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

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:

```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, 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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides instructions for interacting with the ClawScan CLI, a security scanning tool for AI agents. It follows security best practices by requiring secrets to be passed via environment variables rather than command-line flags and defaults to a containerized sandbox execution environment for external scanners.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: MEDIUM · 1 issue

Signed by skilld at 7b51dc8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 2 weeks ago

README badge

README badge for openclaw/clawscan/clawscan-cli