Skip to content
Back to search

skill-scanner

SkillWorks with Claude CodeGitHub

Security Scanner for Agent Skills

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cisco-ai-defense/skill-scanner with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cisco-ai-defense/skill-scanner'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cisco-ai-defense-skill-scanner/badge.svg)](/listings/cisco-ai-defense-skill-scanner)

HTML

<a href="/listings/cisco-ai-defense-skill-scanner"><img src="/api/listings/cisco-ai-defense-skill-scanner/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites:** CPython 3.11–3.14 and [uv](https://docs.astral.sh/uv/) (recommended) or pip.

Wheels include the CEL helper for glibc Linux x86-64/ARM64, macOS 14+ x86-64/ARM64 and Windows x86-64. Other platforms build from the source distribution, which needs Go 1.27.1+. See [Installation and Configuration](docs/user-guide/installation-and-configuration.md) for details.

# Using uv (recommended)
uv pip install cisco-ai-skill-scanner

# As a standalone tool
uv tool install cisco-ai-skill-scanner   # or: pipx install cisco-ai-skill-scanner

# Using pip
pip install cisco-ai-skill-scanner

# Using Homebrew (macOS 14+)
brew tap cisco-ai-defense/skill-scanner https://github.com/cisco-ai-defense/skill-scanner
brew install cisco-ai-defense/skill-scanner/skill-scanner

The presets and settings in [Recommended Settings](https://cisco-ai-defense.github.io/docs/skill-scanner/recommended-settings) need 2.2.0 or newer (`skill-scanner --version`).

<details> <summary><strong>Cloud Provider Extras</strong></summary>

# AWS Bedrock support (IAM credentials, no API key)
pip install cisco-ai-skill-scanner[bedrock]

# Google AI Studio / Gemini support
pip install cisco-ai-skill-scanner[google]

# Google Vertex AI support
pip install cisco-ai-skill-scanner[vertex]

# Azure OpenAI support
pip install cisco-ai-skill-scanner[azure]

# On-device Apple Foundation Model (experimental: macOS 26+, Apple Intelligence, full Xcode)
pip install "apple-fm-sdk>=0.2.1,<0.3"

# All cloud providers
pip install cisco-ai-skill-scanner[all]

</details>

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 479 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Skill Scanner
  2. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  3. [![CPython 3.11–3.14](https://img.shields.io/badge/CPython-3.11--3.14-blue.svg)](https://www.python.org/downloads/)
  4. [![PyPI version](https://img.shields.io/pypi/v/cisco-ai-skill-scanner.svg)](https://pypi.org/project/cisco-ai-skill-scanner/)
  5. [![CI](https://github.com/cisco-ai-defense/skill-scanner/actions/workflows/python-tests.yml/badge.svg)](https://github.com/cisco-ai-defense/skill-scanner/actions/workflows/python-tests.yml)
  6. [![Discord](https://img.shields.io/badge/Discord-Join%20Us-7289da?logo=discord&logoColor=white)](https://discord.com/invite/nKWtDcXxtx)
  7. [![Cisco AI Defense](https://img.shields.io/badge/Cisco-AI%20Defense-049fd9?logo=cisco&logoColor=white)](https://www.cisco.com/site/us/en/products/security/ai-defense/index.html)
  8. [![AI Security Framework](https://img.shields.io/badge/AI%20Security-Framework-orange)](https://learn-cloudsecurity.cisco.com/ai-security-framework)
  9. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/cisco-ai-defense/skill-scanner)
  10. A best-effort security scanner for AI Agent Skills that detects prompt injection, data exfiltration, and malicious code patterns. It combines **pattern-based detection** (YAML + YARA-X), **AST and dataflow analysis**, an optional **LLM-as-a-judge**, and a bounded **CEL decision layer** over typed detector facts.
  11. > **Important:** This scanner provides best-effort detection, not comprehensive or complete coverage. A scan that returns no findings does not guarantee that a skill is free of all threats. See [Scope and Limitations](#scope-and-limitations) below.
  12. Supports [OpenAI Codex Skills](https://openai.github.io/codex/) and [Cursor Agent Skills](https://docs.cursor.com/context/rules) formats following the [Agent Skills specification](https://agentskills.io). With `--lenient`, also scans non-standard formats such as Claude Code `.claude/commands/*.md` and flat markdown skill repos.
  13. ---
  14. ## Highlights
  15. - **Multi-Engine Detection** - Static analysis, behavioral dataflow, LLM semantic analysis, and cloud-based scanning for layered, best-effort coverage
  16. - **Typed CEL Decisions** - The core scanner uses the official `cel-go` v0.32.0 runtime to correlate bounded facts after deterministic detection and before optional LLM analysis
  17. - **Measured Presets** - `low-noise` and `quiet` presets and LLM caps, with recall, false-positive rate and F1 published for each ([Recommended Settings](https://cisco-ai-defense.github.io/docs/skill-scanner/recommended-settings))
  18. - **CI/CD Ready** - SARIF output for GitHub Code Scanning, [reusable GitHub Actions workflow](docs/github-actions.md), exit codes for build failures
  19. - **Pre-commit Hook** - [Standard pre-commit framework](https://pre-commit.com/) integration to scan skills before every commit
  20. - **Extensible** - Plugin architecture for custom analyzers
  21. **[Join the Cisco AI Discord](https://discord.com/invite/nKWtDcXxtx)** to discuss, share feedback, or connect with the team.
  22. ---
  23. ## Scope and Limitations
  24. Skill Scanner is a detection tool. It identifies known and probable risk patterns, but it does not certify security.
  25. **Key limitations:**
  26. - **No findings ≠ no risk.** A scan that returns "No findings" indicates that no known threat patterns were detected. It does not guarantee that a skill is secure, benign, or free of vulnerabilities.
  27. - **Coverage is inherently incomplete.** The scanner combines signature-based detection, LLM-based semantic analysis, behavioral dataflow analysis, optional cloud services, and configurable rule packs. While this approach improves coverage, no automated tool can detect every technique, especially novel or zero-day attacks.
  28. - **False positives and false negatives can occur.** Presets, the LLM judge and scoped suppressions reduce noise, but no configuration eliminates all incorrect classifications. Pick a measured setup from [Recommended Settings](https://cisco-ai-defense.github.io/docs/skill-scanner/recommended-settings) and tune the [scan policy](docs/user-guide/custom-policy-configuration.md) to your risk tolerance.
  29. - **Human review remains essential.** Automated scanning is one component of a defense-in-depth strategy. High-risk or production deployments should pair scanner results with manual code review and/or threat modeling.
  30. ### Measured results
  31. On held-out skills (MaliciousSkillBench's frozen test split, 839 malicious and 545 harmless):
  32. - **Rules alone** catch 7.7% of malicious skills at HIGH, at a 4.0% false-positive rate.
  33. - **With the LLM judge** (Gemma 4 26B, `balanced`), 66.7% reach review at MEDIUM+ (15.4% FPR), and
  34. 33.7% are blocked at HIGH (6.4% FPR).
  35. Every figure, with its corpus and method, is in [Measured Results](docs/reference/measured-results.md)
  36. and on the [evaluation Space](https://huggingface.co/spaces/Vineethsain/skill-scanner-vs-skillspector).
  37. ---
  38. ## Documentation
  39. The documentation website is **[cisco-ai-defense.github.io/docs/skill-scanner](https://cisco-ai-defense.github.io/docs/skill-scanner)**.
  40. Deep-dive pages live in [`docs/`](docs/README.md).
  41. | Guide | Description |
  42. |-------|-------------|
  43. | [Quick Start](docs/getting-started/quick-start.md) | Get started in 5 minutes |
  44. | [Recommended Settings](https://cisco-ai-defense.github.io/docs/skill-scanner/recommended-settings) | Pick a setup for the lowest FPR or the highest F1, with copy-paste configs |
  45. | [LLM Providers](https://cisco-ai-defense.github.io/docs/skill-scanner/llm-providers) | Configure the LLM judge for any provider, gateway or local model |
  46. | [Results and Tuning](https://cisco-ai-defense.github.io/docs/skill-scanner/results-and-tuning) | Read findings, build a review queue, lower false positives |
  47. | [Architecture](docs/architecture/index.md) | System design and components |
  48. | [CEL Decision Layer](docs/architecture/cel-decision-layer.md) | Typed facts, safety bounds, rollout modes, and telemetry |
  49. | [Threat Taxonomy](docs/architecture/threat-taxonomy.md) | Complete AITech threat taxonomy with examples |
  50. | [Taxonomy Reference](docs/architecture/taxonomy-reference.md) | Definitions of every AITech and AISubtech code |
  51. | [LLM Analyzer](docs/architecture/analyzers/llm-analyzer.md) | LLM configuration and usage |
  52. | [System One Analyzer](docs/architecture/analyzers/system-one-analyzer.md) | Optional advisory screening tier, and why it cannot gate |
  53. | [Meta-Analyzer](docs/architecture/analyzers/meta-analyzer.md) | Optional second-pass review (off by default; measured cost) |
  54. | [Behavioral Analyzer](docs/architecture/analyzers/behavioral-analyzer.md) | Dataflow analysis details |
  55. | [Scan Policy](docs/user-guide/custom-policy-configuration.md) | Custom policies, presets, and tuning guide |
  56. | [Policy Quick Reference](docs/reference/policy-quick-reference.md) | Compact reference for policy sections and knobs |
  57. | [Measured Results](docs/reference/measured-results.md) | Every published figure, with its corpus, population and model |
  58. | [Rule Authoring](docs/architecture/analyzers/writing-custom-rules.md) | How to add signature, YARA, and Python rules |
  59. | [GitHub Actions](docs/github-actions.md) | Reusable workflow for CI/CD integration |
  60. | [API Reference](docs/user-guide/api-server.md) | REST API documentation |
  61. | [Development Guide](docs/development/setup-and-testing.md) | Contributing and development setup |
  62. ---
  63. ## Installation
  64. **Prerequisites:** CPython 3.11–3.14 and [uv](https://docs.astral.sh/uv/) (recommended) or pip.
  65. Wheels include the CEL helper for glibc Linux x86-64/ARM64, macOS 14+ x86-64/ARM64 and Windows
  66. x86-64. Other platforms build from the source distribution, which needs Go 1.27.1+. See
  67. [Installation and Configuration](docs/user-guide/installation-and-configuration.md) for details.
  68. ```bash
  69. # Using uv (recommended)
  70. uv pip install cisco-ai-skill-scanner
  71. # As a standalone tool
  72. uv tool install cisco-ai-skill-scanner # or: pipx install cisco-ai-skill-scanner
  73. # Using pip
  74. pip install cisco-ai-skill-scanner
  75. # Using Homebrew (macOS 14+)
  76. brew tap cisco-ai-defense/skill-scanner https://github.com/cisco-ai-defense/skill-scanner
  77. brew install cisco-ai-defense/skill-scanner/skill-scanner
  78. ```
  79. The presets and settings in [Recommended Settings](https://cisco-ai-defense.github.io/docs/skill-scanner/recommended-settings)
  80. need 2.2.0 or newer (`skill-scanner --version`).
  81. <details>
  82. <summary><strong>Cloud Provider Extras</strong></summary>
  83. ```bash
  84. # AWS Bedrock support (IAM credentials, no API key)
  85. pip install cisco-ai-skill-scanner[bedrock]
  86. # Google AI Studio / Gemini support
  87. pip install cisco-ai-skill-scanner[google]
  88. # Google Vertex AI support
  89. pip install cisco-ai-skill-scanner[vertex]
  90. # Azure OpenAI support
  91. pip install cisco-ai-skill-scanner[azure]
  92. # On-device Apple Foundation Model (experimental: macOS 26+, Apple Intelligence, full Xcode)
  93. pip install "apple-fm-sdk>=0.2.1,<0.3"
  94. # All cloud providers
  95. pip install cisco-ai-skill-scanner[all]
  96. ```
  97. </details>
  98. ---
  99. ## Quick Start
  100. ### Recommended settings
  101. Every recommended setup runs the LLM judge (`--use-llm`): rules alone catch only about 8% of
  102. held-out malicious skills.
  103. | Goal | Command | Held-out recall / FPR / F1 |
  104. |------|---------|----------------------------|
  105. | Highest F1 | `skill-scanner scan ./skill --use-llm --policy balanced --fail-on-severity high`, and review everything at MEDIUM+ | 66.7% / 15.4% / 75.5% |
  106. | Smaller review queue (your own skills) | `skill-scanner scan ./skill --use-llm --policy low-noise --fail-on-severity high` | 63.2% / 13.4% / 73.5% |
  107. | Lowest false-positive rate | `skill-scanner scan ./skill --use-llm --policy quiet --fail-on-severity high` | 50.3% / 7.2% / 64.9% |
  108. | Nothing leaves the machine | any of the above, with the judge on a [local model](https://cisco-ai-defense.github.io/docs/skill-scanner/llm-providers) | as above |
  109. Rates are for the MEDIUM+ review queue on MaliciousSkillBench's held-out split, with Gemma 4 26B as
  110. the judge. Measured precision for each, and the same setups for pre-commit, GitHub Actions, Python and
  111. the REST API, are in [Recommended Settings](https://cisco-ai-defense.github.io/docs/skill-scanner/recommended-settings).
  112. ### Environment Setup
  113. ```bash
  114. # The LLM judge, used by every recommended setup (local models: see LLM Providers)
  115. export SKILL_SCANNER_LLM_API_KEY="your_api_key"
  116. export SKILL_SCANNER_LLM_MODEL="claude-sonnet-5-5" # the default
  117. # On-device Apple Foundation Model (experimental, no API key). Behavioral
  118. # alignment verification is skipped with a warning on this model.
  119. # export SKILL_SCANNER_LLM_MODEL="apple-fm/system"
  120. # Optional: disabled, minimal, low, medium, high, xhigh, or max
  121. export SKILL_SCANNER_LLM_REASONING_EFFORT="low"
  122. # For VirusTotal binary scanning
  123. export VIRUSTOTAL_API_KEY="your_virustotal_api_key"
  124. # For Cisco AI Defense
  125. export AI_DEFENSE_API_KEY="your_aidefense_api_key"
  126. ```
  127. ### Interactive Wizard
  128. Not sure which flags to use? Run `skill-scanner` with no arguments to launch the interactive wizard:
  129. ```bash
  130. skill-scanner
  131. ```
  132. The wizard walks you through selecting a scan target, analyzers, policy, and output format, then shows the assembled command before running it. It recommends the LLM judge and leaves the meta-analyzer off. Great for learning the CLI.
  133. ### CLI Usage
  134. ```bash
  135. # First test: core analyzers only (static + bytecode + pipeline + correlation)
  136. skill-scanner scan /path/to/skill
  137. # Real use: add the LLM judge
  138. skill-scanner scan /path/to/skill --use-llm --policy balanced --fail-on-severity high
  139. # Scan with behavioral analyzer (dataflow analysis)
  140. skill-scanner scan /path/to/skill --use-behavioral
  141. # Scan with all engines
  142. skill-scanner scan /path/to/skill --use-behavioral --use-llm --use-aidefense
  143. # Rules + LLM judge, with the preset that has the fewest false positives
  144. skill-scanner scan /path/to/skill --use-llm --policy quiet
  145. # Decomposed judge: three focused passes, about three times the tokens
  146. skill-scanner scan /path/to/skill --use-llm --llm-decompose
  147. # Scan with trigger analyzer for vague description checks
  148. skill-scanner scan /path/to/skill --use-trigger
  149. # Run LLM analyzer multiple times and keep majority-agreed findings
  150. skill-scanner scan /path/to/skill --use-llm --llm-consensus-runs 3
  151. # Scan multiple skills recursively
  152. skill-scanner scan-all /path/to/skills --recursive --use-behavioral
  153. # Scan multiple skills with cross-skill overlap detection
  154. skill-scanner scan-all /path/to/skills --recursive --check-overlap
  155. # Scan a GitHub repository (owner/repo shorthand or full URL)
  156. skill-scanner scan-repo owner/repo
  157. skill-scanner scan-repo https://github.com/owner/repo --use-llm
  158. # Lenient mode: tolerate malformed skills instead of failing
  159. skill-scanner scan /path/to/skill --lenient
  160. skill-scanner scan-all /path/to/skills --recursive --lenient
  161. # Lenient mode with non-standard skill formats (no SKILL.md required)
  162. skill-scanner scan .claude/commands/deploy --lenient
  163. skill-scanner scan-all .claude/commands --recursive --lenient
  164. # Use a custom metadata filename instead of SKILL.md
  165. skill-scanner scan /path/to/skill --skill-file README.md
  166. # CI/CD: rules + judge, fail the build on HIGH
  167. skill-scanner scan-all ./skills --recursive --use-llm --policy low-noise --fail-on-severity high --format sarif --output results.sarif
  168. # Generate interactive HTML report with attack correlation groups
  169. skill-scanner scan /path/to/skill --use-llm --format html --output report.html
  170. # Use custom YARA rules
  171. skill-scanner scan /path/to/skill --custom-rules /path/to/my-rules/
  172. # Use custom taxonomy + threat mapping profiles (JSON/YAML)
  173. skill-scanner scan /path/to/skill --taxonomy /path/to/taxonomy.json --threat-mapping /path/to/threat_mapping.json
  174. # VirusTotal hash scan with optional unknown-file uploads
  175. skill-scanner scan /path/to/skill --use-virustotal --vt-upload-files
  176. # Use a scan policy preset (balanced, low-noise, quiet, strict, permissive) with the judge
  177. skill-scanner scan /path/to/skill --use-llm --policy low-noise
  178. # Inspect CEL decisions without suppressing findings
  179. skill-scanner scan /path/to/skill --cel-mode shadow --format json
  180. # Use a custom org policy file
  181. skill-scanner scan /path/to/skill --policy my_org_policy.yaml
  182. # Generate a policy file to customise, starting from a preset
  183. skill-scanner generate-policy --preset low-noise -o my_org_policy.yaml
  184. # Interactive policy configurator (TUI)
  185. skill-scanner configure-policy
  186. ```
  187. Consensus mode keeps a finding only when it appears in more than half of the
  188. configured runs. When those votes disagree on severity, the highest observed
  189. severity wins, independent of response order. Failed runs and successful runs
  190. that omit the finding cast no vote but remain in the denominator. This makes
  191. severity selection stable for majority-agreed findings. It does not make an
  192. individual LLM sample deterministic, and descriptive fields from equal-severity
  193. votes, single-run output, and non-majority findings can still vary between scans.
  194. **LLM provider note:** `--llm-provider` accepts `anthropic`, `openai` or `openai-compatible`.
  195. For Bedrock, Vertex AI, Azure, Gemini, Ollama, gateways and local servers, set provider-specific model
  196. strings and environment variables (see [LLM Providers](https://cisco-ai-defense.github.io/docs/skill-scanner/llm-providers)).
  197. If `--use-llm` is set and the judge cannot start, the scan stops with an error rather than passing with rules only.
  198. ### Python SDK
  199. ```python
  200. from skill_scanner import SkillScanner
  201. from skill_scanner.core.analyzers import BehavioralAnalyzer
  202. # Create scanner with analyzers
  203. scanner = SkillScanner(analyzers=[
  204. BehavioralAnalyzer(),
  205. ])
  206. # Scan a skill
  207. result = scanner.scan_skill("/path/to/skill")
  208. print(f"Findings: {len(result.findings)}")
  209. print(f"Max severity: {result.max_severity}")
  210. # Note: is_safe indicates no HIGH/CRITICAL findings were detected.
  211. # It does not guarantee the skill is free of all risk.
  212. if not result.is_safe:
  213. print("Issues detected -- review findings before deployment")
  214. ```
  215. ---
  216. ## Security Analyzers
  217. | Analyzer | Detection Method | Scope | Requirements |
  218. |----------|------------------|-------|--------------|
  219. | **Static** | YAML + YARA patterns | All files | None |
  220. | **Bytecode** | .pyc integrity verification | Python bytecode | None |
  221. | **Pipeline** | Command taint analysis | Shell pipelines | None |
  222. | **Correlation** | Bounded structured source/sink correlation | Python, JavaScript, TypeScript, and package facts | None |
  223. | **Behavioral** | AST dataflow analysis | Python files | None |
  224. | **LLM** | Semantic analysis | SKILL.md + scripts | API key |
  225. | **Meta** | Second-pass review (off by default) | All findings | API key |
  226. | **VirusTotal** | Hash-based malware | Binary files | API key |
  227. | **AI Defense** | Cloud-based AI | Text content | API key |
  228. ---
  229. ## CLI Options
  230. | Option | Description |
  231. |--------|-------------|
  232. | `--policy` | Scan policy: preset name (`strict`, `balanced`, `permissive`, `low-noise`, `quiet`) or path to custom YAML |
  233. | `--use-behavioral` | Enable behavioral analyzer (dataflow analysis) |
  234. | `--use-llm` | Enable LLM analyzer (requires API key) |
  235. | `--llm-provider` | LLM provider for CLI routing: `anthropic`, `openai` or `openai-compatible` |
  236. | `--llm-decompose` | Run the judge once per focus and union the findings (about three times the model calls) |
  237. | `--adjudicate` | Demote-only LLM review of deterministic HIGH/CRITICAL literal-regex false positives |
  238. | `--use-osv` | Query OSV.dev for known-vulnerable pinned dependencies (network, no key) |
  239. | `--rule-packs PACK...` | Enable optional signature packs (e.g. `atr`, `promptguard`); `--rule-packs list` shows them |
  240. | `--system-one-endpoint URL` | Optional advisory System One screen; never changes a finding (needs `--system-one-model`) |
  241. | `--llm-consensus-runs N` | Run LLM analysis `N` times, keep majority-agreed findings, and retain their highest observed severity |
  242. | `--llm-max-tokens N` | Maximum output tokens for LLM responses (default: 8192) |
  243. | `--llm-reasoning-effort LEVEL` | Optional reasoning depth (`disabled`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`); unset preserves the provider default |
  244. | `--use-virustotal` | Enable VirusTotal binary scanner |
  245. | `--vt-api-key KEY` | Provide VirusTotal API key directly (optional) |
  246. | `--vt-upload-files` | Upload unknown binaries to VirusTotal (optional) |
  247. | `--use-aidefense` | Enable Cisco AI Defense analyzer |
  248. | `--aidefense-api-url URL` | Override AI Defense API URL (optional) |
  249. | `--use-trigger` | Enable trigger specificity analyzer |
  250. | `--enable-meta` | Enable the meta-analyzer. Off by default and not recommended: it cost 16.4 points of recall in measurement |
  251. | `--verbose` | Include per-finding policy fingerprints, co-occurrence metadata, and keep meta-analyzer false positives |
  252. | `--format` | Output: `summary`, `json`, `markdown`, `table`, `sarif`, `html`. The `html` format produces a self-contained interactive report with collapsible correlation groups, expandable code snippets, and pipeline taint flow diagrams |
  253. | `--detailed` | Include detailed findings in Markdown output |
  254. | `--compact` | Compact JSON output |
  255. | `--output PATH` | Default output file path (overridden by `--output-<fmt>`) |
  256. | `--fail-on-findings` | Exit with error if HIGH/CRITICAL found (shorthand for `--fail-on-severity high`) |
  257. | `--fail-on-severity LEVEL` | Exit with error if findings at or above LEVEL exist (critical, high, medium, low, info) |
  258. | `--custom-rules PATH` | Use custom YARA rules from directory |
  259. | `--trusted-rule-pack PATH` | Load an administrator-trusted schema-v2 signature/YARA/CEL pack (repeatable) |
  260. | `--cel-mode MODE` | Set the CEL decision layer to `off`, `shadow`, or `enforce` |
  261. | `--taxonomy PATH` | Load custom taxonomy profile (JSON/YAML) for this run |
  262. | `--threat-mapping PATH` | Load custom scanner threat mapping profile (JSON) for this run |
  263. | `--lenient` | Tolerate malformed skills (coerce bad fields, fill defaults) instead of failing. When `SKILL.md` is absent, falls back to scanning `.md` files in the directory |
  264. | `--skill-file FILENAME` | Custom metadata filename to use instead of `SKILL.md` (e.g. `README.md`) |
  265. | `--check-overlap` | (`scan-all`) Enable cross-skill description overlap checks |
  266. | Command | Description |
  267. |---------|-------------|
  268. | *(no command)* | Launch interactive scan wizard (when run in a terminal) |
  269. | `interactive` | Launch interactive scan wizard (explicit) |
  270. | `scan` | Scan a single skill directory |
  271. | `scan-all` | Scan multiple skills (with `--recursive`, `--check-overlap`) |
  272. | `scan-repo` | Clone a GitHub repository (`owner/repo` or URL) and scan its skills |
  273. | `generate-policy` | Generate a scan policy YAML for customisation |
  274. | `configure-policy` | Interactive TUI to build/edit a custom scan policy (`--input` supported) |
  275. | `list-analyzers` | Show available analyzers |
  276. | `validate-rules` | Validate bundled rules plus optional `--rules-file` signatures and repeatable `--trusted-rule-pack` v2 packs |
  277. The `balanced` (default), `low-noise`, `quiet` and `strict` presets use CEL `shadow`; `permissive`
  278. uses CEL `off`. Every bundled CEL rule currently has `rollout: shadow`, so even a
  279. global `--cel-mode enforce` retains findings until an individual rule is
  280. qualified and promoted. The ATR pack remains opt-in through
  281. `--rule-packs atr` and is not part of the current core + CEL release gate.
  282. ---
  283. ## Example Output
  284. ```
  285. $ skill-scanner scan ./my-skill --use-behavioral
  286. ============================================================
  287. Skill: my-skill
  288. ============================================================
  289. Status: [OK] No findings
  290. Max Severity: NONE
  291. Total Findings: 0
  292. Scan Duration: 0.15s
  293. ```
  294. > **Note:** "No findings" means the scanner did not detect any known threat patterns -- it is not a guarantee that the skill is free of all risk. See [Scope and Limitations](#scope-and-limitations).
  295. ---
  296. ## GitHub Actions
  297. Scan skills automatically on every push or PR using the [reusable workflow](docs/github-actions.md):
  298. ```yaml
  299. # .github/workflows/scan-skills.yml
  300. name: Scan Skills
  301. on:
  302. pull_request:
  303. paths: [".cursor/skills/**"]
  304. jobs:
  305. scan:
  306. uses: cisco-ai-defense/skill-scanner/.github/workflows/scan-skills.yml@2.3.2
  307. with:
  308. scanner_version: "2.3.2"
  309. skill_path: .cursor/skills
  310. policy: low-noise
  311. use_llm: true
  312. llm_model: anthropic/claude-sonnet-5-5
  313. secrets:
  314. llm_api_key: ${{ secrets.SKILL_SCANNER_LLM_API_KEY }}
  315. permissions:
  316. security-events: write
  317. contents: read
  318. actions: read
  319. ```
  320. Results appear as inline annotations in PRs via GitHub Code Scanning. See the [full guide](docs/github-actions.md) for LLM integration, secret configuration, and branch protection setup.
  321. ---
  322. ## Pre-commit Hook
  323. Scan skills, with the judge, before every commit using the [pre-commit](https://pre-commit.com/) framework:
  324. ```yaml
  325. # .pre-commit-config.yaml
  326. repos:
  327. - repo: https://github.com/cisco-ai-defense/skill-scanner
  328. rev: 2.3.2 # the latest release tag (no "v" prefix)
  329. hooks:
  330. - id: skill-scanner
  331. ```
  332. Turn the judge on in `.skill_scannerrc` at the repository root (`use_llm` is off by default):
  333. ```json
  334. {
  335. "skills_path": ".claude/skills",
  336. "policy": "low-noise",
  337. "use_llm": true,
  338. "llm_model": "anthropic/claude-sonnet-5-5",
  339. "severity_threshold": "high",
  340. "fail_fast": true
  341. }
  342. ```
  343. The hook scans only the skills a commit touches. The key comes from `SKILL_SCANNER_LLM_API_KEY`,
  344. or from cloud credentials for Bedrock and Vertex AI. `llm_model` and `llm_provider` fall back to
  345. `SKILL_SCANNER_LLM_MODEL` and `SKILL_SCANNER_LLM_PROVIDER`, so the hook can point at a local model.
  346. If the judge cannot be built, the commit is blocked with exit code 2 instead of passing on the rules
  347. alone. For a `bedrock/` model, add `additional_dependencies: [boto3]` to the hook. Run
  348. `pre-commit install` once, or `skill-scanner-pre-commit --install` without the pre-commit framework.
  349. ---
  350. ## Contributing
  351. We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  352. ## License
  353. Apache 2.0 - See [LICENSE](LICENSE) for details.
  354. Copyright 2026 Cisco Systems, Inc. and its affiliates
  355. ---
  356. <p align="center">
  357. <a href="https://github.com/cisco-ai-defense/skill-scanner">GitHub</a> •
  358. <a href="https://discord.com/invite/nKWtDcXxtx">Discord</a> •
  359. <a href="https://pypi.org/project/cisco-ai-skill-scanner/">PyPI</a>
  360. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.