[Scanner]: skills-inspector — offline static analyzer for agent extensions

Scanner name

skills-inspector

Upstream URL

https://github.com/atarico/skills-inspector

Request type

New built-in scanner adapter

CLI/API shape

skills-inspector --json

Prints a single JSON document to stdout. Supports skill and plugin targets
(it walks up from a SKILL.md to the enclosing .claude-plugin/plugin.json,
marketplace.json or opencode.json when one exists, since auditing a SKILL.md
without its manifest produces a false clean).

Note on gating: the exit code is always 0 by design — the tool reports and
has no veto. Gate policy would need to be JSON-path based rather than
blockOnExitCode.

Credentials and setup

None. No API keys, no network access, no LLM calls, no telemetry.
Python 3.10+, standard library only, zero runtime dependencies.

Install: pip install "git+https://github.com/atarico/skills-inspector.git@"

Expected artifact

A JSON report. Each finding carries rule id, severity, confidence,
disclosure status (undeclared / euphemistic / declared), capability,
file+line, sanitized evidence, and impact.

The report also carries mandatory "not_analyzed" and "coverage_limits"
sections — a report that omits what it could not inspect implies a
completeness the tool does not have.

I'm currently adding a published JSON Schema and a schema_version key
before proposing anything concrete.

Example proof

I've been building this for about two months. It's a detection engine
rather than a harness: 111 implemented rules across 14 families, plus
single-file taint tracking (source → sink across variables, redirects and
env exports), a reachability graph that separates active from conditional
and dormant files, structural parsing of the agent control plane
(settings.json, .mcp.json, opencode.json, hooks, subagents, permissions),
and disclosure-gap scoring against the unit's own description.

Corpus: 143 fixtures (56 benign / 82 malicious / 3 documented known-misses),
with exact per-fixture expected finding sets pinned in fixtures/EXPECTED.json.
Those numbers are self-measured and I'd rather not lean on them — I'm working
toward running it against SkillTrustBench and clawhub-security-signals so
there's an external number to compare against clawscan-static on the same
corpus.

Rules catalogue: https://github.com/atarico/skills-inspector/blob/main/RULES.md

I'm not proposing a PR yet. Before that I want to land packaging, the
published schema, and those benchmark numbers. Two questions that would
shape the work:

1. Is a pinned git SHA install acceptable, following the SkillSpector
   precedent in docker/clawscan-runtime/Dockerfile, or is PyPI publication
   expected for a new adapter?
2. Should the runtime-image pin land in the same PR as the adapter, or
   separately? CONTRIBUTING.md asks for one topic per PR, but the adapter
   isn't usable in the default Docker sandbox without the image entry.

Separately: docs/scanners.md and CONTRIBUTING.md both link to
docs/scanners.md#adding-a-built-in-scanner-adapter, but that heading
doesn't exist in the tree. Happy to send a docs-only PR writing that
section if it'd be useful.

Start by reading docs/scanners.md, CONTRIBUTING.md, and docker/clawscan-runtime/Dockerfile, then inspect the existing built-in scanner adapters and their installation and gating conventions. The issue says packaging, a published JSON Schema, benchmark numbers, and a decision about the runtime-image pin are prerequisites; completion criteria are not yet settled.