SkillSpector
AI Agent 技能安全扫描器。 在安装 Agent 技能之前，检测漏洞、恶意模式和安全风险。
概述
AI Agent 技能（用于 Claude Code、Codex CLI、Gemini CLI 等）以隐式信任方式执行，且几乎不经过审查。研究表明，26.1% 的技能存在漏洞 ，5.2% 表现出明显的恶意意图。
SkillSpector 帮助你回答："这个技能安装起来安全吗？"
文档
- ** 开发指南 ** ------ 架构、包结构，以及如何扩展分析器流水线。
功能特性
-
多格式输入：支持扫描 Git 仓库、URL、zip 文件、目录或单个文件
-
64 种漏洞模式，覆盖 16 个类别：提示注入、数据窃取、权限提升、供应链攻击、过度代理、输出处理、系统提示泄漏、记忆投毒、工具滥用、流氓 Agent、触发器滥用、危险代码（AST）、污点追踪、YARA 签名、MCP 最小权限以及 MCP 工具投毒
-
两阶段分析：快速静态分析 + 可选的 LLM 语义评估
-
实时漏洞查询：SC4 查询 OSV.dev 获取实时 CVE 数据，并支持自动离线回退
-
多种输出格式：终端、JSON、Markdown 和 SARIF 报告
-
风险评分：0-100 分制，附带严重级别标签和清晰建议
快速上手
安装
首先创建并激活虚拟环境（所有 make 目标均假定 venv 已激活）。可使用 uv 或 pip ；Makefile 优先使用 uv，若不可用则回退到 pip。
# Clone the repository git clone https://github.com/NVIDIA/skillspector.git cd skillspector # Create and activate virtual environment uv venv .venv && source .venv/bin/activate # or: python3 -m venv .venv && source .venv/bin/activate # Install for production use make install # Or install with development dependencies make install-devDocker（无需安装 Python）
通过构建内置的 Dockerfile 本地镜像，无需安装 Python 即可运行 SkillSpector。该镜像基于 Docker 官方 Python 3.12-slim-bookworm 镜像。
构建镜像：
make docker-build # or: docker build -t skillspector .挂载当前目录到容器工作目录 /scan 来扫描本地目录：
docker run --rm -v " $PWD :/scan " skillspector scan ./my-skill/ --no-llm通过传入本地 .env 文件中的凭证来启用 LLM 分析：
cat > .env
| Provider (`SKILLSPECTOR_PROVIDER`) | Credential env var | Endpoint | Default model |
| `openai` | `OPENAI_API_KEY` (+ optional `OPENAI_BASE_URL`) | api.openai.com (or any OpenAI-compatible URL) | `gpt-5.4` |
| `anthropic` | `ANTHROPIC_API_KEY` | api.anthropic.com | `claude-opus-4-6` |
| `nv_build` | `NVIDIA_INFERENCE_KEY` | build.nvidia.com | `deepseek-ai/deepseek-v4-flash` |标准 OpenAI export SKILLSPECTOR_PROVIDER=openai export OPENAI_API_KEY=sk-... skillspector scan ./my-skill/ # Anthropic export SKILLSPECTOR_PROVIDER=anthropic export ANTHROPIC_API_KEY=sk-ant-... skillspector scan ./my-skill/ # NVIDIA build.nvidia.com export SKILLSPECTOR_PROVIDER=nv_build export NVIDIA_INFERENCE_KEY=nvapi-... skillspector scan ./my-skill/ # 本地 Ollama 或任何兼容 OpenAI 的端点 export SKILLSPECTOR_PROVIDER=openai export OPENAI_API_KEY=ollama export OPENAI_BASE_URL=http://localhost:11434/v1 export SKILLSPECTOR_MODEL=llama3.1:8b skillspector scan ./my-skill/ # 覆盖提供商的默认模型 export SKILLSPECTOR_MODEL=gpt-5.2 skillspector scan ./my-skill/ # 跳过 LLM 分析（更快，仅静态分析） skillspector scan ./my-skill/ --no-llm
## Vulnerability Patterns
[](#vulnerability-patterns)
SkillSpector detects **64 vulnerability patterns** across 16 categories:
### Prompt Injection (5 patterns)
[](#prompt-injection-5-patterns)
| ID | Pattern | Severity | Description |
| P1 | Instruction Override | HIGH | Commands to ignore safety constraints |
| P2 | Hidden Instructions | HIGH | Malicious directives in comments/invisible text |
| P3 | Exfiltration Commands | HIGH | Instructions to transmit context externally |
| P4 | Behavior Manipulation | MEDIUM | Subtle instructions altering agent decisions |
| P5 | Harmful Content | CRITICAL | Instructions that could cause physical harm |
### Data Exfiltration (4 patterns)
[](#data-exfiltration-4-patterns)
| ID | Pattern | Severity | Description |
| E1 | External Transmission | MEDIUM | Sending data to external URLs |
| E2 | Env Variable Harvesting | HIGH | Collecting API keys and secrets |
| E3 | File System Enumeration | MEDIUM | Scanning directories for sensitive files |
| E4 | Context Leakage | HIGH | Transmitting conversation context externally |
### Privilege Escalation (3 patterns)
[](#privilege-escalation-3-patterns)
| ID | Pattern | Severity | Description |
| PE1 | Excessive Permissions | LOW | Requesting access beyond stated functionality |
| PE2 | Sudo/Root Execution | MEDIUM | Invoking elevated system privileges |
| PE3 | Credential Access | HIGH | Reading SSH keys, tokens, passwords |
### Supply Chain (6 patterns)
[](#supply-chain-6-patterns)
| ID | Pattern | Severity | Description |
| SC1 | Unpinned Dependencies | LOW | No version constraints on packages |
| SC2 | External Script Fetching | HIGH | curl \| bash and remote code execution |
| SC3 | Obfuscated Code | HIGH | Base64/hex encoded execution |
| SC4 | Known Vulnerable Dependencies | HIGH | Dependencies with known CVEs (live OSV.dev lookup) |
| SC5 | Abandoned Dependencies | MEDIUM | Unmaintained packages without security updates |
| SC6 | Typosquatting | HIGH | Package names similar to popular packages |
### Excessive Agency (4 patterns)
[](#excessive-agency-4-patterns)
| ID | Pattern | Severity | Description |
| EA1 | Unrestricted Tool Access | HIGH | Unfettered tool access without constraints |
| EA2 | Autonomous Decision Making | HIGH | High-impact decisions without human-in-the-loop |
| EA3 | Scope Creep | MEDIUM | Capabilities extending beyond stated purpose |
| EA4 | Unbounded Resource Access | MEDIUM | No rate limits or quotas on resource consumption |
### Output Handling (3 patterns)
[](#output-handling-3-patterns)
| ID | Pattern | Severity | Description |
| OH1 | Unvalidated Output Injection | HIGH | Model output used without sanitization |
| OH2 | Cross-Context Output | MEDIUM | Output flows across trust boundaries without validation |
| OH3 | Unbounded Output | MEDIUM | No limits on output size or generation rate |
### System Prompt Leakage (3 patterns)
[](#system-prompt-leakage-3-patterns)
| ID | Pattern | Severity | Description |
| P6 | Direct Leakage | HIGH | Instructions that expose system prompts or internal rules |
| P7 | Indirect Extraction | MEDIUM | Extraction via rephrasing, translation, or side-channels |
| P8 | Tool-Based Exfiltration | HIGH | System prompts exfiltrated via file writes or network requests |
### Memory Poisoning (3 patterns)
[](#memory-poisoning-3-patterns)
| ID | Pattern | Severity | Description |
| MP1 | Persistent Context Injection | HIGH | Content designed to persist across interactions |
| MP2 | Context Window Stuffing | MEDIUM | Filler content displacing safety constraints |
| MP3 | Memory Manipulation | HIGH | Tampering with agent memory or stored state |
### Tool Misuse (3 patterns)
[](#tool-misuse-3-patterns)
| ID | Pattern | Severity | Description |
| TM1 | Tool Parameter Abuse | HIGH | Crafted parameters for unintended behavior (shell=True, --force) |
| TM2 | Chaining Abuse | HIGH | Tool chains that bypass individual safety checks |
| TM3 | Unsafe Defaults | MEDIUM | Overly permissive defaults (disabled TLS, no auth) |
### Rogue Agent (2 patterns)
[](#rogue-agent-2-patterns)
| ID | Pattern | Severity | Description |
| RA1 | Self-Modification | CRITICAL | Modifying own code or configuration at runtime |
| RA2 | Session Persistence | HIGH | Unauthorized persistence via cron jobs or startup scripts |
### Trigger Abuse (3 patterns)
[](#trigger-abuse-3-patterns)
| ID | Pattern | Severity | Description |
| TR1 | Overly Broad Trigger | MEDIUM | Trigger patterns matching common words |
| TR2 | Shadow Command Trigger | HIGH | Triggers that shadow built-in commands or other skills |
| TR3 | Keyword Baiting Trigger | MEDIUM | Generic triggers designed to maximize activation |
### Behavioral AST (8 patterns)
[](#behavioral-ast-8-patterns)
| ID | Pattern | Severity | Description |
| AST1 | exec() Call | CRITICAL | Direct exec() enabling arbitrary code execution |
| AST2 | eval() Call | HIGH | Direct eval() evaluating arbitrary expressions |
| AST3 | Dynamic Import | HIGH | __import__() loading arbitrary modules at runtime |
| AST4 | subprocess Call | HIGH | External command execution via subprocess |
| AST5 | os.system / exec-family | HIGH | Shell commands via os module |
| AST6 | compile() Call | MEDIUM | Code object creation from strings |
| AST7 | Dynamic getattr() | MEDIUM | Arbitrary attribute access with non-literal names |
| AST8 | Dangerous Execution Chain | CRITICAL | exec/eval combined with dynamic source (network, encoded data) |
### Taint Tracking (5 patterns)
[](#taint-tracking-5-patterns)
| ID | Pattern | Severity | Description |
| TT1 | Direct Taint Flow | HIGH | Data flows directly from a source to a sink without sanitization |
| TT2 | Variable-Mediated Taint Flow | MEDIUM | Data flows from source to sink through intermediate variables |
| TT3 | Credential Exfiltration Chain | CRITICAL | Credentials (env vars, secrets) flow to network output sinks |
| TT4 | File Read to Network Exfiltration | HIGH | File contents flow to network output sinks |
| TT5 | External Input to Code Execution | CRITICAL | Network or user input flows to exec/eval/subprocess sinks |
### YARA Signatures (4 patterns)
[](#yara-signatures-4-patterns)
| ID | Pattern | Severity | Description |
| YR1 | Malware Match | CRITICAL | YARA rule match for known malware signatures |
| YR2 | Webshell Match | CRITICAL | YARA rule match for webshell patterns |
| YR3 | Cryptominer Match | HIGH | YARA rule match for crypto mining indicators |
| YR4 | Hack Tool / Exploit Match | HIGH | YARA rule match for hack tools or exploit code |
### MCP Least Privilege (4 patterns)
[](#mcp-least-privilege-4-patterns)
| ID | Pattern | Severity | Description |
| LP1 | Underdeclared Capability | HIGH | Code uses capabilities not listed in declared permissions |
| LP2 | Wildcard Permission | MEDIUM | Permission list contains wildcards (*, all, full, any) |
| LP3 | Missing Permission Declaration | MEDIUM | No permissions field but code has detectable capabilities |
| LP4 | Overdeclared Permission | LOW | Permission declared but no corresponding code capability found |
### MCP Tool Poisoning (4 patterns)
[](#mcp-tool-poisoning-4-patterns)
| ID | Pattern | Severity | Description |
| TP1 | Hidden Instructions | HIGH | Hidden directives in metadata (HTML comments, zero-width chars, base64, data URIs) |
| TP2 | Unicode Deception | HIGH | Homoglyphs, RTL overrides, mixed-script identifiers in tool metadata |
| TP3 | Parameter Description Injection | MEDIUM | Injection patterns in parameter definitions (overrides, system tokens, malicious defaults) |
| TP4 | Description-Behavior Mismatch | MEDIUM | Declared tool description does not match actual code behavior (LLM-powered) |
All detected patterns are listed in the tables above.
## Risk Scoring
[](#risk-scoring)
### Score Calculation
[](#score-calculation)
- **CRITICAL issues**: +50 points
- **HIGH issues**: +25 points
- **MEDIUM issues**: +10 points
- **LOW issues**: +5 points
- **Executable scripts**: 1.3x multiplier
### Severity Levels
[](#severity-levels)
| Score | Severity | Recommendation |
| 0-20 | LOW | SAFE |
| 21-50 | MEDIUM | CAUTION |
| 51-80 | HIGH | DO NOT INSTALL |
| 81-100 | CRITICAL | DO NOT INSTALL |
## Example Output
[](#example-output)
### Terminal Output
[](#terminal-output)SkillSpector 安全报告 v2.0.0 技能：suspicious-skill 来源：./suspicious-skill/ 扫描时间：2026-01-29 10:30:00 UTC 风险评估 指标 数值 评分 78/100 严重级别 HIGH 建议 请勿安装 组件（3 个） 文件 类型 行数 可执行 SKILL.md markdown 142 否 scripts/sync.py python 87 是 requirements.txt text 3 否 问题（2 个） HIGH：环境变量收集（E2） 位置：scripts/sync.py:23 发现：for key, val in os.environ.items():... 置信度：94% 说明：此代码收集包含 API 密钥和敏感信息的环境变量，并将其发送至外部服务器。 HIGH：外部数据传输（E1） 位置：scripts/sync.py:45 发现：requests.post("https://api.skill.io/env"... 置信度：89% 说明：数据正被发送至外部服务器。结合上述环境变量收集行为，表明存在凭证窃取风险。
## Configuration
[](#configuration)
### Environment Variables
[](#environment-variables)
| Variable | Description | Required |
| `SKILLSPECTOR_PROVIDER` | Active LLM provider: `openai`, `anthropic`, or `nv_build`. Each provider has its own bundled `model_registry.yaml` and default model (see the LLM Analysis table above). Defaults to `nv_build`. | Optional |
| `NVIDIA_INFERENCE_KEY` | Credential for the `nv_build` provider (build.nvidia.com). | Required for LLM analysis when `SKILLSPECTOR_PROVIDER=nv_build` |
| `OPENAI_API_KEY` | Credential for the OpenAI provider (`SKILLSPECTOR_PROVIDER=openai`). Also serves as the tier-2 fallback in the credential waterfall when the active provider returns no credentials. | Required for LLM analysis when `SKILLSPECTOR_PROVIDER=openai` |
| `OPENAI_BASE_URL` | Override the OpenAI endpoint (e.g. point at Ollama). | Optional |
| `ANTHROPIC_API_KEY` | Credential for the Anthropic provider (`SKILLSPECTOR_PROVIDER=anthropic`). | Required for LLM analysis when `SKILLSPECTOR_PROVIDER=anthropic` |
| `SKILLSPECTOR_MODEL` | Override the active provider's default model. See the LLM Analysis table for each provider's default. | Optional |
| `SKILLSPECTOR_MODEL_REGISTRY` | Override the bundled per-provider YAML registry (`src/skillspector/providers/ .yaml`) with a custom path. | Optional |
| `SKILLSPECTOR_LOG_LEVEL` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `WARNING`). | Optional |
### CLI Options
[](#cli-options)skillspector scan --help 选项： -f, --format terminal \| json \| markdown \| sarif 输出格式 默认值：terminal -o, --output PATH 输出文件路径 --no-llm 跳过 LLM 分析（仅静态分析） -V, --verbose 显示详细进度 --help 显示此帮助信息并退出
## Development
[](#development)
### Setup
[](#setup)
All `make` targets assume a virtual environment is already created and activated. The Makefile uses **uv** if available, else **pip**.克隆仓库、创建 venv、激活、安装开发依赖 git clone https://github.com/NVIDIA/skillspector.git cd skillspector uv venv .venv && source .venv/bin/activate # 或：python3 -m venv .venv && source .venv/bin/activate make install-dev # 运行测试 make test # 运行测试并生成覆盖率报告 make test-cov # 运行代码检查 make lint # 格式化代码 make format
## How It Works
[](#how-it-works)
SkillSpector uses a two-stage detection pipeline:
### Stage 1: Static Analysis
[](#stage-1-static-analysis)
- Fast regex-based pattern matching across 11 static analyzers
- AST-based behavioral analysis detecting dangerous calls (exec, eval, subprocess, etc.)
- Live vulnerability lookups via OSV.dev for known CVEs in dependencies
- Scans all files in the skill
- High recall (catches most issues)
- Moderate precision (some false positives)
### Stage 2: LLM Semantic Analysis (Optional)
[](#stage-2-llm-semantic-analysis-optional)
- Evaluates context and intent
- Filters false positives
- Provides human-readable explanations
- Improves precision to ~87%
The LLM prompt includes anti-jailbreak protections to prevent malicious skills from manipulating the analysis.
## Live Vulnerability Lookups (SC4)
[](#live-vulnerability-lookups-sc4)
SC4 uses the [OSV.dev](https://osv.dev) API to check dependencies against the full Open Source Vulnerabilities database --- covering tens of thousands of advisories across PyPI and npm.
- **No API key required** --- OSV.dev is free and unauthenticated.
- **Batch queries** --- all dependencies are checked in a single HTTP call.
- **Automatic fallback** --- if OSV.dev is unreachable (air-gapped/offline), a small built-in fallback list is used.
- **Caching** --- results are cached in-memory for 1 hour to avoid redundant API calls during a session.
The tool requires outbound HTTPS access to `api.osv.dev` for live vulnerability data. When that is not available, findings are limited to the static fallback list.
## Limitations
[](#limitations)
- **Non-English content**: May miss patterns in other languages
- **Image-based attacks**: Cannot analyze text in images
- **Encrypted/binary code**: Cannot analyze compiled or encrypted content
- **Runtime behavior**: Static analysis only, no dynamic execution
- **Offline SC4**: Without network access to `api.osv.dev`, SC4 uses a small static fallback list
## Research Background
[](#research-background)
Based on research from "Agent Skills in the Wild: An Empirical Study of Security Vulnerabilities at Scale" (Liu et al., 2026):
- **Dataset**: 42,447 skills from major marketplaces
- **Vulnerable**: 26.1% contain at least one vulnerability
- **High-severity**: 5.2% show likely malicious intent
- **Key finding**: Skills with executable scripts are 2.12x more likely to be vulnerable
## Python API Integration
[](#python-api-integration)from skillspector import graph # 调用 LangGraph 工作流 result = graph . invoke ({ "input_path" : "/path/to/skill" , "output_format" : "json" , # terminal、json、markdown 或 sarif "use_llm" : True , # False 表示仅静态分析 }) # 访问结果 print ( f"风险评分：{ result 'risk_score' } /100" ) print ( f"严重级别：{ result 'risk_severity' } " ) print ( f"建议：{ result 'risk_recommendation' } " ) for finding in result "filtered_findings" : print ( f" { finding \[ 'severity' } ] { finding 'rule_id' } : { finding 'message' } " )
## 许可证
[](#license)
Apache License 2.0 ------ 详情请参阅 [LICENSE](/NVIDIA/SkillSpector/blob/main/LICENSE)。
## 贡献
[](#contributing)
欢迎贡献！请阅读我们的贡献指南并提交 pull request。
## 支持
[](#support)
- **问题反馈**：GitHub Issues