Openclaw Skill Scanner

Scan local or staged ClawHub skills before installation; report High/Critical findings and optionally quarantine managed skills. A scan is not proof of safety.

Skill Scanner Guard

Use a separately reviewed installation of cisco-ai-defense/skill-scanner. The default scanner checkout is <workspace>/skill-scanner; override it with SKILL_SCANNER_DIR. These scripts do not establish that a scanner checkout, OpenClaw installation, or candidate skill is trustworthy. Do not execute a candidate skill as part of review.

Scan before installing

bash

bash {baseDir}/scripts/scan_and_add_skill.sh /absolute/path/to/skill
bash {baseDir}/scripts/clawhub_scan_install.sh publisher/skill --version VERSION

ClawHub staging additionally requires npx. Downloads stay in a private staging directory outside the default skill roots. Existing destination folders are not replaced. High/Critical findings block; Medium/Low/Info findings allow with a warning. --force overrides findings only, never scanner errors or incomplete severity summaries. --tag is rejected rather than silently ignored.

These are explicit wrappers, not an interception hook for openclaw skills install, ClawHub installs performed elsewhere, skill updates, or Workshop apply. Never describe a successful scan as a safety guarantee.

Scan installed skills

bash

bash {baseDir}/scripts/scan_openclaw_skills.sh
bash {baseDir}/scripts/scan_openclaw_skills.sh --only-roots /path/to/skill/root
bash {baseDir}/scripts/scan_openclaw_skills.sh --catalog --agent main

Filesystem-only mode checks managed, default workspace, project .agents, default-state personal .agents, workshop, and discoverable bundled sources. Grouped skills are discovered up to six levels deep, stopping at SKILL.md. Symlink skill directories require explicit review; discovery errors are not reported as a successful complete scan.

--catalog explicitly executes the installed OpenClaw CLI. Use it only with an installation you trust. It uses skills list --json and skills info --json to include configured agent workspaces and extra/plugin/bundled sources. It does not inspect every user's private library, disconnected nodes, remote hosts, or shadowed skills outside the selected roots. Unavailable local manifests fail inventory creation. No candidate skill code is executed by discovery.

Paths

OPENCLAW_HOME, OPENCLAW_STATE_DIR, OPENCLAW_PROFILE, and OPENCLAW_WORKSPACE_DIR select the layout. Named profiles do not inherit the default personal .agents/skills root. The legacy .clawdbot state fallback is retained when neither an explicit state nor a named profile is selected.

Wrapper overrides: OPENCLAW_SKILLS_DIR, OPENCLAW_QUARANTINE_DIR, OPENCLAW_STAGE_DIR, SKILL_SCANNER_DIR, SKILL_SCANNER_REPORT_DIR, OPENCLAW_BUNDLED_SKILLS_DIR, and OPENCLAW_BIN (one executable, not a shell command). Per-agent configuration is resolved through explicit catalog mode, not by guessing or evaluating OpenClaw configuration files.

Reports default to <workspace>/skill_scans; managed installs to <state>/skills; quarantine to <state>/skills-quarantine.

Optional systemd watcher

The units in references/ are templates for the default Linux user layout. Review the ExecStart and watched paths before enabling them, especially with a profile, custom workspace, or renamed installation directory. Environment variables are not expanded inside systemd path directives. A path unit is not a recursive watcher and does not guarantee interception before a skill loads.

auto_scan_user_skills.sh scans grouped managed skills individually and quarantines High/Critical results outside the managed skill tree. It never accepts quarantine paths from report text. Failed scans and malformed reports return nonzero without declaring skills safe. Cross-filesystem quarantine is refused rather than performed as a non-atomic copy/delete.

See COMPATIBILITY.md for the upstream reference and test scope.