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-dev

Docker（无需安装 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