skill-security-scan

skill-security-scan

<!-- Pattern provenance: portions of the detection-pattern taxonomy and the five-category breakdown are adapted from alirezarezvani/claude-skills (skill-security-auditor), licensed under the MIT License. The verbatim license text is preserved at [LICENSES/skill-security-auditor.MIT.txt](../../../../LICENSES/skill-security-auditor.MIT.txt). No verbatim code is copied; only the conceptual taxonomy and category framing. -->

Advisory static-analysis gate that scans a SKILL.md or agent markdown file for five categories of security risk. Emits one of LOW-RISK | REVIEW | HIGH-RISK plus a findings report, with a mandatory advisory disclaimer footer. Advisory only: output is not a security audit, certification, or warranty. The skill executes in the operator's environment under the operator's account; the operator remains responsible for review.

Detection categories

1. Code-execution anti-patterns — dynamic-eval primitives, shell-spawn with

user-controlled args, obfuscation signatures. See [references/rules/code-exec.yaml](./references/rules/code-exec.yaml).

1. Prompt-injection — frontmatter role-hijack and body proximity-gated patterns,

with Soleur prose allowlist. See [references/regex-patterns.md](./references/regex-patterns.md).

1. Supply-chain risk — osv.dev batch query against parsed manifest references,

with ecosystem allowlist + REVIEW-on-unknown + network-error-as-REVIEW.

1. Filesystem boundary violations — path traversal, symlink-out, write attempts

to credential dotfiles. See [references/rules/filesystem-boundary.yaml](./references/rules/filesystem-boundary.yaml).

1. Third-Party Telemetry Surface — utm-tagged links, redirect-tracking domains,

outbound-beacon URLs, vendor-branding footers. URL host-aware allowlist (not raw substring match — adversarial https://attacker.com/?ref=soleur.ai is detected as host=attacker.com). See [references/first-party-allowlist.yaml](./references/first-party-allowlist.yaml).

Verdict semantics

| Verdict | Meaning | Operator action | |---|---|---| | LOW-RISK | No findings, or only finding-level metadata WARN tags | Proceed silently | | REVIEW | At least one category emitted REVIEW | Read findings; decide | | HIGH-RISK | At least one category emitted HIGH-RISK | Block-by-default; override via structured artifact |

Aggregation rule: max-severity across the five categories wins. Per-finding severity: WARN contributes REVIEW to the aggregate verdict, never HIGH-RISK alone.

Invocation

Scan a file:

bash ${CLAUDE_PLUGIN_ROOT:-plugins/soleur}/skills/skill-security-scan/scripts/run-scan.sh < path/to/SKILL.md

Scan stdin content (used by agent-finder post-fetch / skill-creator post-scaffold integrations):

echo "$skill_md_content" | bash ${CLAUDE_PLUGIN_ROOT:-plugins/soleur}/skills/skill-security-scan/scripts/run-scan.sh

Output: markdown findings table on stdout, mandatory advisory disclaimer footer (non-removable), and .scan-meta.json written next to the input file (or to $XDG_RUNTIME_DIR/skill-security-scan-$$/ for stdin input).

Override mechanism

When the scanner returns HIGH-RISK and the operator judges the finding to be a false-positive or accepted-risk, override by committing a structured artifact:

knowledge-base/engineering/security/skill-overrides/YYYY-MM-DD-<slug>.md

The artifact is the sole audit-trail (no git trailer involved — squash-merge-safe). Schema: [references/override-artifact-schema.json](./references/override-artifact-schema.json). Process: [references/override-mechanism.md](./references/override-mechanism.md).

Self-defense

The scanner is itself an attack surface. Defenses:

• Rule-pack SHA pinning via [references/rules/manifest.yaml](./references/rules/manifest.yaml).

run-scan.sh validates rule-file SHAs at every run; tampering → REVIEW with reason rule pack tampered.

• OSV untrusted-input handling: schema validation, body-size cap, ecosystem

allowlist (unknown ecosystem → REVIEW, never LOW-RISK), network-failure → REVIEW.

• Fail-loud self-test:

[scripts/run-self-test.sh](./scripts/run-self-test.sh) runs the scanner over known-malicious + known-clean fixtures; any false-negative or false-positive on the seed set fails the test loudly. Wired into CI per .github/workflows/skill-security-scan-corpus.yml.

PII redaction

Findings persisted to .scan-meta.json and override artifacts run through email/IP/IBAN-shape redaction before write (per gdpr-gate GDPR-DataMin-1). Operator-facing stdout is unredacted; persisted forms are redacted. Sentry mirrors of scanner errors use reportSilentFallback(err, { feature: 'skill-security-scan', extra: { ...redacted } }).

Integrations

• skill-creator Step 5: post-validation scan before packaging.
• agent-finder §4b.5: cooperative-fast-path scan post-fetch / pre-write.
• PreToolUse hook on Write to .claude/skills/ and .claude/agents/:

load-bearing block-on-HIGH-RISK gate at the tool layer.

• Lefthook commit-time advisory: belt-and-suspenders for IDE / CLI commit paths.
• CI pre-merge required check + post-merge audit: defense-in-depth against

tool-layer bypass.

See [references/override-mechanism.md](./references/override-mechanism.md) for operator workflows.