SkillSpector

AI 智能体技能的安全扫描器。 在安装智能体技能之前检测漏洞、恶意模式和安全风险。

概述

AI 智能体技能（供 Claude Code、Codex CLI、Gemini CLI 等使用）在隐式信任和极少审查的情况下执行。在研究数据集中已分析的 31,132 个技能子集里，26.1% 的技能包含漏洞，5.2% 表现出可能的恶意意图。

SkillSpector 帮助你回答：“这个技能安装起来安全吗？”

SkillSpector 是 NVIDIA Verified Skills 流水线的一部分，该流水线在发布前对智能体技能进行扫描、评估和签名。通过检查的技能会发布到 NVIDIA 技能目录。

文档

安装前扫描智能体技能 — 托管指南：何时扫描、如何阅读报告，以及如何对安装进行门控。
开发指南 — 架构、包布局，以及如何扩展分析器流水线。
分析资源上限 — 故障关闭式（fail-closed）的包、解析器、嵌套工件、账本和发现项上限。
Pi 扩展 — 将 SkillSpector 安装为 Pi 工具，以便在智能体会话内部扫描技能。
OpenCode 扩展 — 将 SkillSpector 安装为 OpenCode 工具和 /skillspector 命令，以便在智能体会话内部扫描技能。

功能特性

多格式输入：扫描 Git 仓库、URL、zip 文件、目录或单个文件
17 个类别下的 71 种漏洞模式：提示注入、数据外泄、权限提升、供应链、过度代理、输出处理、系统提示泄露、记忆投毒、工具滥用、失控智能体、反拒绝、触发器滥用、危险代码（AST）、污点跟踪、YARA 签名、MCP 最小权限，以及 MCP 工具投毒
两阶段分析：快速静态分析 + 可选的 LLM 语义评估
实时漏洞查询：SC4 查询 OSV.dev 获取实时 CVE 数据，并自动离线回退
多种输出格式：终端、JSON、Markdown 和 SARIF 报告
风险评分：0-100 分，附带严重性标签和明确的建议
基线 / 误报抑制：通过 glob 规则或指纹基线接受已知发现项，使重新扫描仅暴露新问题（文档）

快速开始

安装

开源软件声明： 本项目将下载并安装额外的第三方开源软件项目。使用前请审阅这些开源项目的许可条款。

首先创建并激活虚拟环境（所有 make 目标都假定 venv 已激活）。使用 uv 或 pip；Makefile 在可用时使用 uv，否则使用 pip。

使用 uv 快速安装（仅 CLI）：

uv tool install git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspector

如果你计划运行 skillspector mcp，请在安装时安装 MCP 附加组件：

uv tool install '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 .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

使用 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

批量扫描

从 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。

比较 MCP Registry 快照

首先获取原始注册表载荷捕获文件（registry-before.json 和 registry-after.json）。将一次扫描报告保存为 previous.json，然后将之后的扫描与该生成的本地报告进行比较：

skillspector scan registry-before.json --mcp-registry --format json --output previous.json
skillspector scan registry-after.json --mcp-registry --format json \
  --mcp-registry-compare previous.json --output compared.json

可选的 comparison 对象列出新增和移除的服务器身份、发生变化的规范化字段及其先前值和当前值，以及一个 unchanged_count。身份由服务器名称和版本构成，因此新版本会显示为新增，而旧版本若未出现在新扫描中则显示为移除。采集来源和扫描时间戳不参与比较。unmodeled_changes 列出身份相同但原始记录哈希发生变化、而规范化字段匹配的记录；这些记录不计入未变更。这可能表明快照模型之外的字段发生了变化，或原始记录中的数组重新排序。仅包和远程顺序变化不算作规范化字段变更。changed 中的条目也可能包含快照模型之外的变更；请检查原始记录以查看这些变更。使用相同的选择范围比较报告：当前输入中缺失的服务器会被报告为已移除，但这并不能证明它已从注册表中移除。

比较文件必须是由此注册表模式生成的本地报告，且具有有效的规范化快照。格式错误、过大或重复的服务器身份将被拒绝。此选项需要 --mcp-registry，并且与用于发现抑制的 --baseline 相互独立：它从不抑制发现或改变风险评分，也不会获取或执行所列服务器的端点。

抑制误报（baseline）

抑制已知/已接受的发现，使风险评分仅反映未分类的问题，并让重新扫描仅暴露新的发现。完整参考请参见抑制指南。

# Accept all current findings into a baseline (run once), then commit it.
skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml

# Scan against the baseline — only NEW findings are reported and scored.
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml

# Review what was suppressed (still excluded from the score).
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed

基线也可以使用容忍漂移的 glob 规则（按规则 id、文件路径或消息）——参见 .skillspector-baseline.example.yaml。精确指纹基线是证据绑定的：更改被扫描的源代码或 SkillSpector 版本会使该发现保持活跃，直到再次被审查。当选定的基线或基线输出存储在 skill 目录内时，SkillSpector 会将该确切文件从内容分析中排除，因此其抑制文本无法产生发现或进入重新生成的指纹；同级文件仍保留在正常扫描范围内。

显式扫描范围

对于包含一个 SKILL.md 或 skill.md 的本地目录，重复使用 --exclude 以在内容分析前省略选定的文件：

skillspector scan ./my-skill --exclude 'tests/*' --exclude 'fixtures/*.json'

模式是区分大小写的 glob，与整个相对 POSIX 路径匹配； * 也会匹配 /。请为模式加引号，以免 shell 对其进行展开。这是一个显式的调用方选项，而非由作者控制的忽略文件。匹配任一清单名称（SKILL.md 或 skill.md）的模式会被拒绝，递归、多技能、传递、注册表以及非目录输入同样会被拒绝。未匹配的模式仍会记录在报告中。