Scanners

--scanner selects a scanner adapter to run, writes its raw JSON evidence into the results artifact, and can be repeated to compare multiple scanners in one run:

clawscan ./my-skill \
  --scanner skillspector \
  --scanner cisco

Discover the scanner catalog from the CLI:

clawscan scanners
clawscan scanners skillspector

Profile scanner configuration

A trusted config can mix built-in scanner IDs with user-defined command scanners. The config schema uses the existing profiles.<name>.scanners list:

version: 1

profiles:
  review:
    scanners:
      - id: skillspector
        gate:
          rules:
            - id: do-not-install
              path: risk_assessment.recommendation
              equals: DO_NOT_INSTALL
              action: block
            - id: critical-finding
              path: filtered_findings[].severity
              equals: CRITICAL
              action: block
      - id: clawscan-static
        gate:
          rules:
            - id: any-finding
              path: findings[]
              exists: true
              action: warn
      - id: my-scanner
        command: my-scanner --json {{target}}
        env:
          - MY_SCANNER_MODE
        secretEnv:
          - MY_SCANNER_TOKEN
        targets:
          - skill
          - plugin
        gate:
          rules:
            - id: high-risk
              path: result.risk
              equals: high
              action: warn
          blockOnExitCode: nonzero

String entries select built-in scanners without gate policy. An object with a registered built-in id and no command selects that built-in and can attach gate rules. The rules inspect its existing JSON output; the scanner does not need to implement ClawScan-specific policy or change its exit codes.

An object with a command defines a user-provided scanner for that config-backed run. The same JSON rules work for built-in and command scanners:

JSON gate rules

gate.rules evaluates the scanner's raw JSON without rewriting it. Every rule has:

Specify exactly one of equals or exists: true. A rule fires at most once, even when several paths or array items match. The fired artifact records the path that matched. A path list is an ordered fallback: ClawScan evaluates the first path with a non-empty value and ignores later aliases, whether or not its value matches. Empty strings and null fall through to the next alias. An explicitly empty traversed array remains authoritative, letting a preferred filtered result override legacy raw-result fields. Missing paths, empty arrays, and type mismatches do not fire. Within one path segment, | alternatives are resolved separately for each object, using the first present field; if that field is empty, the rule can still fall through to the next path. For fallback: root, a present root field prevents later path aliases from being consulted. For example, findings[].severity|risk_severity checks severity and then risk_severity on each finding. An immutable third-party scanner can be gated without a wrapper:

scanners:
  - id: third-party
    command: third-party scan --json {{target}}
    gate:
      rules:
        - id: critical-risk
          path:
            - result.risk
            - result.risk_level
          equals: critical
          normalize: identifier
          action: block
        - id: any-policy-violation
          path: result.violations[]
          exists: true
          action: warn

Exit-code rules

Each exit-code rule accepts one integer from 0 through 124, a list such as [1, 2, 3], or the string nonzero. The block and warning rules may not claim the same exit code. Exit codes 125 and above are reserved for shell, container-runtime, and signal failures, so ClawScan does not treat them as scanner verdicts. For example:

gate:
  blockOnExitCode: [2, 3]
  warnOnExitCode: 1

JSON and exit-code rules can be combined on the same scanner. A gate-eligible process exit code is preserved alongside raw JSON, and all fired rules participate in the same strongest-action decision.

After every selected scanner finishes, ClawScan records the strongest fired action as the top-level artifact gate: block wins over warn, and an artifact with no fired rules records "gate": "pass". Each fired rule is also listed in gateRules with its scanner ID, rule ID, and action. Exit-code rules include exitCode; JSON rules include path and, for equals, the matched value. Gate actions are record-only: block does not stop later scanners or the judge, and it does not change ClawScan's process exit status. For enforcement, inspect gate and gateRules on a single run, runs[].gate and runs[].gateRules in a batch, or cases[].run.gate and cases[].run.gateRules in a benchmark. The human scan summary aggregates the strongest batch action; the benchmark summary does not aggregate gate actions.

Skipped or failed scanners do not fire gate rules. A nonzero command that still returned valid JSON has status completed and can fire both JSON and exit-code rules. Valid JSON from a timeout, signal, or reserved infrastructure exit is still preserved, but the failed scanner does not fire gate rules and its exitCode is omitted.

The command must write JSON to stdout. ClawScan preserves valid stdout as the scanner's raw evidence; empty or non-JSON stdout produces a failed scanner result. Required environment variables are checked before any scanner starts. Artifacts record each requirement as only present or missing.

Do not print secrets into evidence. ClawScan preserves valid scanner

stdout as raw JSON evidence, so any secret the scanner writes into that JSON

is persisted. Values declared in secretEnv are redacted from scanner error

text, but ClawScan does not rewrite raw evidence. A user-defined scanner must

not echo its API keys, tokens, or other credentials into the JSON report it

emits.

User-defined scanners use the same execution path as built-in command-backed scanners. They run in the Docker sandbox by default, and declared env and secretEnv names are added to its environment allowlist. Put every sensitive value in secretEnv; values declared only in env are treated as non-secret and may appear in scanner error text. ClawScan preserves valid scanner stdout as raw JSON evidence, so scanner authors must not print secrets into that JSON. Use --sandbox off only when you intentionally want the command to run on the host. User-defined scanners are local to the resolved config and do not appear in the built-in clawscan scanners catalog.

Trust boundary: only load user-defined scanners from config files you

control. A scanner entry is executable code. The default sandbox limits its

host access, but does not make an untrusted command safe to run.

Target kinds

Clawscan classifies each explicit target before dispatching scanners and records the result in the artifact target.kind field:

The built-in clawhub profile runs skillspector and clawscan-static for plugin targets as it does for skills. VirusTotal and Socket also support plugins when selected explicitly or through a custom profile. Other scanners that assume skill layouts return an explicit skipped result naming the unsupported kind, and adapters can opt in per kind as upstream tools add plugin support. A directory carrying both SKILL.md and openclaw.plugin.json is rejected as ambiguous rather than guessed; point Clawscan directly at the desired manifest to disambiguate a valid dual-layout package.

Plugin targets are never auto-discovered. Zero-target discovery still scans only child skill directories under ./skills; pass a plugin directory explicitly to avoid silently scanning arbitrary package directories. Pointing Clawscan at an openclaw.plugin.json file scans the surrounding plugin directory.

Plugin ids follow OpenClaw's install grammar, including @scope/name ids. Manifests accept the same JSON5 syntax as OpenClaw, including comments, trailing commas, single-quoted strings, and unquoted keys.

Available scanners

Want to add your scanner to the list? Follow the guide in docs/scanners.md

Snyk Agent Scan 0.6 reports named findings in risk_indexes maps under scan_path_responses. ClawScan preserves that upstream JSON and includes those findings in issues_found; clean components with empty risk maps contribute zero. Operator-owned gate rules that inspect Snyk's older issues arrays need to use the current Snyk JSON schema.