Skill Scanner
Security scanning for AI agent skills — detect prompt injection, data exfiltration, and malicious code patterns before they run.
Skill Scanner combines pattern-based detection (YAML + YARA + Python checks), dependency intelligence, LLM analysis and adjudication, and behavioral dataflow analysis to catch threats that any single approach would miss. It supports OpenAI Codex Skills, Cursor Agent Skills, and related formats following the Agent Skills specification.
View on GitHub | PyPI Package | Join Discord
How It Works
1. Install — pip install cisco-ai-skill-scanner or use uv. Then configure a model for the LLM judge, hosted or local. The judge is what reads a skill for intent, and every recommended setup uses it.
2. Scan — Point the CLI at a local skill, a directory of skills, or a GitHub repository. Core analyzers (static, bytecode, pipeline) run automatically; add the LLM judge with --use-llm. Behavioral, OSV.dev, VirusTotal, Cisco AI Defense, adjudication, and cross-skill analysis are optional extras.
3. Review — Get findings in six output formats: summary, JSON, Markdown, table, SARIF, and interactive HTML. Each finding includes severity, threat category, file path, and remediation guidance.
What It Detects
| Threat Category | Description |
|---|---|
| Prompt Injection | Hidden instructions that override agent behavior |
| Data Exfiltration | Unauthorized data transmission to external servers |
| Command Injection | Shell command execution with untrusted input |
| Obfuscation | Base64 encoding, bytecode tricks, and code concealment |
| Hardcoded Secrets | API keys, tokens, and credentials in source code |
| Social Engineering | Deceptive skill descriptions and trigger manipulation |
| Supply Chain | Malicious dependencies and fetch-execute patterns |
| Unicode Steganography | Invisible characters and homoglyph deception |
| Known Vulnerabilities | Exactly pinned Python and JavaScript dependencies with OSV.dev advisories |
| Unpinned Dependencies | Floating versions across Python, Node, Ruby, Go, Rust, and other manifests |
| Suspicious Configuration URLs | Tunnel, paste, webhook, and file-sharing endpoints hidden in config files |
Documentation
| Guide | Description |
|---|---|
| Installation | Prerequisites, install methods, and environment configuration |
| Quick Start | Get scanning in under a minute |
| Recommended Settings | Pick a setup by goal, with measured recall, FPR and F1, and copy its config |
| Scan Policies | Presets, custom policy YAML, and common tweaks |
| LLM Providers | Configure the LLM judge for any provider, gateway or local model |
| CLI Reference | All commands, flags, and examples |
| GitHub Actions and Pre-commit | CI/CD integration with the reusable workflow and the pre-commit hook |
| Python SDK | Programmatic scanning with typed models |
| REST API | REST API server for upload and batch workflows |
| Results and Tuning | Read findings, build the review queue, and lower false positives |
| FAQ | Common questions and answers |
| Architecture | Scanning pipeline, system design, and extension points |
| Features | Analyzer inventory, rule packs, file intelligence, and current detection capabilities |
For deep-dives into individual analyzers, rule authoring, and threat taxonomy, see the full documentation in the repository.
Scope and Limitations
Skill Scanner is a detection tool. It identifies known and probable risk patterns, but it does not certify security.
- No findings does not equal no risk. A clean scan means no known threat patterns were detected — not that the skill is safe.
- Coverage is inherently incomplete. The scanner combines multiple engines, but novel attacks may evade all of them.
- False positives and false negatives can occur. Presets, the LLM judge and scoped suppressions reduce noise, but no configuration eliminates all errors. Recommended Settings gives the measured rates for each setup.
- Human review remains essential. Automated scanning is one layer in a defense-in-depth strategy.
License
Apache 2.0 — See LICENSE for details.
