
SkillSpector v2.13.2
用于 AI 代理技能的安全扫描器。在安装 Claude Code、Codex 和 MCP 技能之前,检测其中的漏洞、恶意模式、安全风险、提示注入、数据外泄和供应链风险。
SkillSpector
面向 AI agent 技能的安全扫描器。 在安装 agent 技能之前检测漏洞、恶意模式和安全风险。
概述
AI agent 技能(供 Claude Code、Codex CLI、Gemini CLI 等使用)在运行时依赖隐式信任,且几乎不经过审查。在研究数据集中已分析的 31,132 个技能子集里,26.1% 的技能存在漏洞,5.2% 表现出可能的恶意意图。
SkillSpector 帮助你回答:“这个技能安装起来安全吗?”
SkillSpector 是 NVIDIA Verified Skills 流水线的一部分,该流水线会在发布前扫描、评估并签名 agent 技能。通过检查的技能会发布到 NVIDIA 技能目录。
文档
- 在安装前扫描 agent 技能 — 托管指南:何时扫描、如何阅读报告,以及如何对安装进行门控。
- 开发指南 — 架构、包布局,以及如何扩展分析器流水线。
- 安全策略 — 私下向 NVIDIA PSIRT 报告疑似漏洞。
- 分析资源上限 — 失败即关闭的 bundle、解析器、嵌套工件、账本和发现项上限。
- Pi 扩展 — 将 SkillSpector 安装为 Pi 工具,以便在 agent 会话内部扫描技能。
- OpenCode 扩展 — 将 SkillSpector 安装为 OpenCode 工具和
/skillspector命令,以便在 agent 会话内部扫描技能。 - LLM 分析器基础指南 — 如何在
LLMAnalyzerBase之上构建由 LLM 驱动的分析器节点。 - 依赖源重定向 — SC10 发现项如何标记更改其软件包获取来源的技能。
- 实时漏洞查询(SC4) — SC4 如何对照 OSV.dev 检查依赖项。
- 评估数据集扫描 — 静态模式分析器会跳过哪些评估数据集文件。
- MCP 最小权限分析(LP1–LP4) 和 MCP 工具投毒检测(TP1–TP4) — MCP 分析器的设计说明。
功能特性
- 多格式输入:扫描 Git 仓库、URL、zip 文件、目录或单个文件
- 17 个类别下的 71 种漏洞模式:提示注入、数据外泄、权限提升、供应链、过度代理、输出处理、系统提示泄露、内存投毒、工具滥用、流氓 agent、反拒绝、触发器滥用、危险代码(AST)、污点跟踪、YARA 签名、MCP 最小权限和 MCP 工具投毒
- 两阶段分析:快速静态分析 + 可选的 LLM 语义评估
- 实时漏洞查询:SC4 查询 OSV.dev 获取实时 CVE 数据,并自动回退到离线模式
- 多种输出格式:终端、JSON、Markdown 和 SARIF 报告
- 风险评分:0-100 分,附带严重性标签和明确建议
- 基线 / 误报抑制:通过 glob 规则或指纹基线接受已知发现项,使重新扫描只暴露新问题(文档)
快速开始
安装
开源软件声明: 本项目将下载并安装额外的第三方开源软件项目。使用前请审阅这些开源项目的许可条款。
在受支持的平台上,请使用 Python 3.12 或 3.13 进行安装,以便使用预构建的 YARA wheel。下面的示例明确选择 3.13;关于更新的解释器,请参阅 Python 安装说明。对于源码安装,请先创建并激活虚拟环境(所有 make 目标都假定 venv 已激活)。可使用 uv 或 pip;Makefile 会优先使用 uv(如果可用),否则使用 pip。
使用 uv 快速安装(仅 CLI):
uv tool install --python 3.13 git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspector
如果你计划运行 skillspector mcp,请在安装时安装 MCP 附加组件:
uv tool install --python 3.13 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'
来自源:
# Clone the repository
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector
# Create and activate virtual environment
uv venv --python 3.13 .venv && source .venv/bin/activate
# or: python3.13 -m venv .venv && source .venv/bin/activate
# Install for production use
make install
如需贡献,请按照开发环境搭建中的说明,为受支持的 Python 解释器和开发依赖进行配置。
Python 安装说明
该包在 pyproject.toml 中声明了 Python >=3.12,<3.16。该范围并不保证所有依赖和平台都有预构建的 wheel。PyPI 上的 yara-python 4.5.4 提供了 CPython 3.12/3.13 的 wheel,但没有 CPython 3.14/3.15 的 wheel。在较新的解释器上安装它需要具备 C 工具链和 Python 开发头文件的原生源码构建。此类构建可能因 OpenSSL 4 头文件而失败;issue #1008 跟踪了该安装问题以及上游 wheel 的可用性。
如果安装过程中在编译 YARA 时失败,请使用上述命令显式选择 Python 3.12 或 3.13。若要通过 pipx 进行仅 CLI 的全新安装,请先安装 Python 3.13 并使 python3.13 在 PATH 中可用,然后运行:
pipx install --python python3.13 git+https://github.com/NVIDIA/skillspector.git
上游的 wheel 构建更新 与向 PyPI 发布新版本是两回事。在选择更新的解释器之前,请先检查已发布的文件;可能仍然需要从源码构建。
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
使用 LLM 分析进行扫描,通过本地 .env 文件传入凭据:
cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF
docker run --rm \
-v "$PWD:/scan" \
--env-file .env \
skillspector scan ./my-skill/
或者直接从你的 shell 环境传递凭据:
docker run --rm \
-v "$PWD:/scan" \
-e SKILLSPECTOR_PROVIDER=anthropic \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
skillspector scan ./my-skill/
通过写入挂载目录,将报告写入主机文件系统:
docker run --rm --user "$(id -u):$(id -g)" \
-v "$PWD:/scan" \
skillspector scan ./my-skill/ --no-llm --format json --output report.json
用于重复静态扫描的可选别名:
alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm
基本用法
# Scan a local skill directory
skillspector scan ./my-skill/
# Scan a single SKILL.md file
skillspector scan ./SKILL.md
# Scan a Git repository
skillspector scan https://github.com/user/my-skill
# Scan a zip file
skillspector scan ./my-skill.zip
大小限制
SkillSpector 对远程和归档输入强制执行两个独立的限制,以约束超大下载和 zip 炸弹的影响:
- 单次摄取上限:
INGEST_MAX_BYTES(100 MiB)——应用于流式 URL 下载、zip 归档的总解压大小,以及 Git 仓库克隆后的磁盘占用。 - Zip 成员上限:
INGEST_MAX_ZIP_MEMBERS(10,000)——限制单个 zip 中的条目数量。
请注意,单文件 1 MB 分析上限(MAX_FILE_BYTES)是一个独立的下游限制:它约束各个分析器从已摄取目录中读取的内容量。上述摄取上限则约束最初能有多少内容落到磁盘上。违反任一摄取上限都会以 IngestLimitExceededError 失败关闭。
输出格式
# Terminal output (default) - pretty formatted
skillspector scan ./my-skill/
# JSON output - machine readable
skillspector scan ./my-skill/ --format json --output report.json
# Markdown output - for documentation
skillspector scan ./my-skill/ --format markdown --output report.md
# SARIF output - for CI/CD integration and IDE tooling
skillspector scan ./my-skill/ --format sarif --output report.sarif
递归集合扫描
--recursive 会将包含 SKILL.md 的直接子目录作为独立技能进行扫描,默认聚合上限为 32 个技能。要调高或调低该上限:
skillspector scan ./my-skills/ --recursive --max-skills 100 --no-llm --format json
--max-skills 需要本地递归收集和一个正整数;0 并不表示无限制。发现、字节、发现记录、时间和报告大小预算仍然适用,因此增加计数并不能保证完整覆盖。当达到计数限制时,CLI 会指出该限制并建议调整它或单独扫描子技能。被省略的技能仍会显示在聚合报告中,覆盖范围保持不完整。在 CI 中使用 --fail-on-incomplete 以在覆盖不完整时失败;默认退出策略保持不变。
批量扫描
从 contrib/batch_scan/ 并行扫描整个技能目录:
python -m contrib.batch_scan.batch_scan ./my-skills/ --no-llm
python -m contrib.batch_scan.batch_scan ./my-skills/ --workers 20 -f json -o report.json
python -m contrib.batch_scan.batch_scan ./tests/fixtures/ -f terminal --workers 20
支持多语言检测(zh/ja/ko)以及终端/JSON/Markdown 输出。
对于需要更高并发的 LLM 扫描,请参照
.env.example 配置多个 API 密钥——密钥池可提升吞吐量
和容错能力,前提是这些密钥不共享账户级别的速率限制。
详情请参阅贡献指南。
关于 LLM 支持的说明: 默认配置以 DeepSeek 为目标,作为 最便宜的公开选项。DeepSeek-Chat 预计将停止服务,且贡献者 没有可用于测试本地模型的硬件。批量扫描器最初是 使用 OpenAI 兼容端点进行测试的——DeepSeek 缺乏 结构化输出支持,因此需要手动打补丁进行 JSON 解析。如果你能 贡献一个更通用的后端(Ollama、vLLM 或其他提供商), 非常欢迎提交 PR。