返回更新列表
新发布Oct 29, 2026

SkillSpector v2.13.2

用于 AI 代理技能的安全扫描器。在安装 Claude Code、Codex 和 MCP 技能之前,检测其中的漏洞、恶意模式、安全风险、提示注入、数据外泄和供应链风险。

分享

SkillSpector

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

Python 3.12+ License: Apache 2.0

概述

AI agent 技能(供 Claude Code、Codex CLI、Gemini CLI 等使用)在运行时依赖隐式信任,且几乎不经过审查。在研究数据集中已分析的 31,132 个技能子集里,26.1% 的技能存在漏洞,5.2% 表现出可能的恶意意图。

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

SkillSpector 是 NVIDIA Verified Skills 流水线的一部分,该流水线会在发布前扫描、评估并签名 agent 技能。通过检查的技能会发布到 NVIDIA 技能目录。

文档

功能特性

  • 多格式输入:扫描 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。

比较 MCP Registry 快照

分类