NVIDIA SkillSpector 保姆级部署教程：AI 智能体技能安全扫描器
一句话定位：NVIDIA 官方开源的 AI 智能体技能（Agent Skill）安全扫描器——在你给 Claude Code、Codex CLI、Gemini CLI 装上第三方 skill 之前，先用它扫一遍，识别漏洞、恶意指令、数据外泄、供应链投毒等风险，给出 0–100 分风险评分与是否可安装的明确结论。
slogan：Is this skill safe to install?（这个 skill 装上之前安不安全？）
仓库地址：https://github.com/NVIDIA/SkillSpector · 许可证：Apache 2.0 · ⭐ 23,696 · 隶属 NVIDIA Verified Skills 流水线
▲ 图 1–2：SkillSpector 仓库 README 顶部全部官方徽章清点——共 2 枚，已完整收录：① Python 3.12+ 版本徽章；② Apache 2.0 许可证徽章。来源：NVIDIA/SkillSpector README 第 5–6 行。经递归扫描仓库 git tree（含 assets/、docs/、contrib/ 等全部目录）与 README 全文（含所有 ![...] 引用），本仓库无官方 logo、banner、截图、架构图、SVG 图示或任何位图文件；docs/ 下 DEVELOPMENT / SUPPRESSION / ANALYSIS_RESOURCE_BOUNDS / PI_EXTENSION / OPENCODE_EXTENSION 等文档亦无内嵌图片。故正文仅展示以上 2 枚 README 官方徽章，无遗漏、无替代图。
一、项目简介
随着 Claude Code、Codex CLI、Gemini CLI 等 AI 编码智能体普及，「skill（技能）」成为新的第三方代码分发形态：一份 Markdown 指令 + 配套脚本，智能体会带着你的环境变量、文件系统和工具权限直接执行。问题在于，这些 skill 在安装时几乎不做任何安全审查，等同于在本机隐式信任陌生人的代码。
NVIDIA 在论文里分析了 31,132 个 skill 样本，结果触目惊心：26.1% 的 skill 含有可被利用的漏洞，5.2% 表现出明显的恶意意图。SkillSpector 就是 NVIDIA 为解决这个问题开源的官方扫描器——它属于 NVIDIA Verified Skills 流水线的一环，官方在发布、签名、上架 NVIDIA skills 目录之前用它做扫描。
它支持扫描 Git 仓库、URL、zip 包、本地目录或单个 SKILL.md 文件，内置 17 大类共 71 条漏洞模式，覆盖提示词注入、数据外泄、权限提升、供应链、过度授权、输出处理、系统提示词泄露、记忆投毒、工具滥用、流氓智能体、反拒绝（jailbreak）、触发滥用、危险代码 AST、污点追踪、YARA 特征、MCP 最小权限与 MCP 工具投毒。扫描结果可输出终端彩色报告、JSON、Markdown 或 SARIF（供 CI/CD 与 IDE 集成）。
二、功能特点
| 能力 | 说明 |
|---|---|
| 🔍 多格式输入 | Git 仓库、URL、zip 压缩包、本地目录、单个 SKILL.md 文件，一条命令扫完 |
| 🛡️ 71 条漏洞模式 / 17 大类 | 提示词注入、数据外泄、权限提升、供应链投毒、过度授权、MCP 工具投毒、YARA 恶意软件特征等 |
| 🧠 两阶段分析 | 先跑快速静态分析（AST + 规则 + YARA），可选再调 LLM 做语义级二次评估 |
| 🌐 实时 CVE 查询 | SC4 规则直查 OSV.dev，联网失败自动离线降级 |
| 📊 风险评分 | 0–100 分制，带 severity 等级与「是否可安装」的明确建议（SAFE / CAUTION / UNSAFE） |
| 📄 多种输出格式 | 终端、JSON、Markdown、SARIF，方便接 CI/CD 与 IDE 报告 |
| 🧪 基线 / 误报抑制 | 把已知可接受的发现写入 .skillspector-baseline.yaml，复扫只报新增问题 |
| 🤖 MCP Server 模式 | 把扫描器本身注册成 MCP 工具，让 Claude Code 等智能体在装 skill 前自动调用扫描做门禁 |
| 🐳 Docker 零依赖运行 | 不想装 Python？直接 docker build 后挂载目录扫描 |
| 📦 批量扫描 | contrib/batch_scan/ 支持多 worker 并行扫整个 skill 集合，多语言检测（zh/ja/ko） |
| 🔒 安全上限 | 单文件 1 MB 分析上限、单次 ingest 100 MiB、zip 成员 10,000 上限，防 zip bomb 与超大输入 |
三、环境要求
- Python 版本：Python 3.12 及以上（官方徽章明确标注
python-3.12+）。 - 包管理器：推荐 uv（Makefile 会优先用 uv，否则退回 pip）；也支持纯 pip + venv。
- 操作系统：Linux / macOS / Windows（WSL2）均可；官方镜像基于 Docker 官方 Python
3.12-slim-bookworm。 - 网络：首次扫描若依赖联网会请求 OSV.dev；如走 LLM 语义分析，需配置 OpenAI / Anthropic / NVIDIA Build / Gemini / Ollama 等任一兼容端点的凭据。
- 磁盘：建议预留 500 MB 以上空间用于依赖与缓存；远程拉取有 100 MiB ingest 上限。
- Docker（可选）：纯 Docker 路线无需 Python，只需本机 Docker 守护进程。
四、保姆级部署步骤
4.1 最简安装（uv 一行命令，CLI 模式）
如果你只想要命令行扫描能力，用 uv 直接从 GitHub 拉取安装（下面用 SSH 地址等价写法，亦可换成 README 给出的 HTTPS git+ 仓库地址）：
uv tool install git+ssh://git@github.com/NVIDIA/skillspector.git
# 后续升级：
uv tool update skillspector装完直接在终端敲 skillspector --help，能看到帮助即成功。
4.2 需要 MCP Server 模式（给智能体当门禁）
如果你打算把 SkillSpector 注册成 MCP 工具（让 Claude Code 等智能体在装 skill 前自动调用），安装时要带上 [mcp] 额外依赖：
uv tool install 'skillspector[mcp] @ git+ssh://git@github.com/NVIDIA/skillspector.git'已经按 4.1 装过纯 CLI 版？用 --force 重装即可：
uv tool install --force 'skillspector[mcp] @ git+ssh://git@github.com/NVIDIA/skillspector.git'4.3 从源码安装（开发者路线）
想改代码、跑测试或扩展分析器，从源码拉（SSH 克隆）：
# 克隆仓库
git clone git@github.com:NVIDIA/skillspector.git
cd skillspector
# 创建并激活虚拟环境
uv venv .venv && source .venv/bin/activate
# 或者用纯 Python：
# python3 -m venv .venv && source .venv/bin/activate
# 生产安装
make install
# 或带开发依赖安装
make install-dev4.4 Docker 路线（不想装 Python）
本机不想碰 Python 环境，直接用仓库自带的 Dockerfile：
# 构建镜像
make docker-build
# 或等价于：
docker build -t skillspector .
# 扫描当前目录下的 my-skill 目录（静态分析，不开 LLM）
docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm
# 把报告写到宿主机
docker run --rm --user "$(id -u):$(id -g)" \
-v "$PWD:/scan" \
skillspector scan ./my-skill/ --no-llm --format json --output report.json想带 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/反复使用可以加个别名：
alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm五、配置说明（LLM 语义分析）
默认只跑静态分析已经能挡住大部分规则级问题；要拿到「描述—行为不匹配」这类语义级判断，需要配一个 OpenAI 兼容端点。用 SKILLSPECTOR_PROVIDER 切换提供商，官方内置支持以下几家：
| 提供商 | 凭据环境变量 | 默认模型 |
|---|---|---|
openai | OPENAI_API_KEY（可选 OPENAI_BASE_URL） | gpt-5.4 |
anthropic | ANTHROPIC_API_KEY | claude-opus-4-6 |
nv_build | NVIDIA_INFERENCE_KEY | z-ai/glm-5.3 |
gemini | GOOGLE_CLOUD_PROJECT（ADC 鉴权） | gemini-3.8-flash |
bedrock | AWS Profile / AWS_REGION | us.anthropic.claude-sonnet-4-6 |
ollama | 无需 Key（本地 OLLAMA_BASE_URL） | llama3.1:8b |
openai_compatible | SKILLSPECTOR_COMPAT_API_KEY + SKILLSPECTOR_COMPAT_BASE_URL | llama-3.1-70b-versatile |
claude_cli / gemini_cli / opencode_cli | 无需 Key（复用本机 CLI 登录态） | 本地运行时默认模型 |
一份最常用的 OpenAI 配置示例：
export SKILLSPECTOR_PROVIDER=openai
export OPENAI_API_KEY=sk-...
skillspector scan ./my-skill/不想花钱调 LLM，直接加 --no-llm 跳过语义分析：
skillspector scan ./my-skill/ --no-llm六、使用方法
6.1 基础扫描
# 扫本地 skill 目录
skillspector scan ./my-skill/
# 扫单个 SKILL.md
skillspector scan ./SKILL.md
# 扫 Git 仓库（本地克隆地址或远程 HTTPS URL 均可）
skillspector scan git@github.com:你的用户名/your-skill.git
# 扫 zip 包
skillspector scan ./my-skill.zip6.2 输出格式
# 终端彩色报告（默认）
skillspector scan ./my-skill/
# JSON（机器可读，接 CI）
skillspector scan ./my-skill/ --format json --output report.json
# Markdown（写进文档）
skillspector scan ./my-skill/ --format markdown --output report.md
# SARIF（接 GitHub Code Scanning / IDE）
skillspector scan ./my-skill/ --format sarif --output report.sarif6.3 批量扫描一整个 skill 集合
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.json6.4 基线抑制误报
第一次扫完，把可接受的发现写入基线，后续复扫只报新增问题：
# 把当前所有发现写入基线
skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml
# 后续扫描时加载基线——只报新发现
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml
# 想看被基线抑制了哪些
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed6.5 注册成 MCP 工具（给智能体当门禁）
把 SkillSpector 注册到 Claude Code，之后智能体在装 skill 前会自动调用扫描：
claude mcp add skillspector -- skillspector mcp或者用 HTTP 传输（仅监听回环）：
skillspector mcp --transport http --host 127.0.0.1 --port 8000MCP 工具对外暴露一个 scan_skill(target, use_llm=true, output_format="json") 函数，返回 risk_score、severity、recommendation、safe_to_install 和 findings。
七、常见问题 FAQ
问一：SkillSpector 是 NVIDIA 官方维护的吗？和 NVIDIA skills 目录什么关系？
答：是。SkillSpector 隶属 NVIDIA Verified Skills 流水线，是 NVIDIA 用来扫描、评估、签名第三方 agent skill 后再上架 NVIDIA skills 目录 的官方工具，Apache 2.0 开源。
问二：我不调 LLM，只用静态分析，扫描效果会不会大打折扣？
答：静态分析已经覆盖 71 条规则中的绝大多数——AST 危险调用、YARA 恶意特征、环境变量收集、curl|bash、typosquatting、zip bomb 等都能拦。LLM 主要补「描述与行为不匹配」「隐藏指令语义」这类需要读上下文的判断。日常装 skill 前用 --no-llm 足够；要做企业级入库审核再开 LLM。
问三：扫描结果报了一堆误报怎么办？
答：用基线抑制。第一次扫完跑 skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml 把当前已知发现固化，提交进版本库；之后复扫加 --baseline，风险评分只反映未 triaged 的新问题。基线支持精确指纹与 glob 规则两种模式。
问四：能接到 GitHub Actions 做 CI 门禁吗？
答：能。用 --format sarif --output report.sarif 输出 SARIF 文件，直接喂给 GitHub Code Scanning；或者用 --format json + 自定义脚本判断 risk_score 阈值后 exit 1。批量扫描脚本 contrib/batch_scan/ 已支持 --workers 并行。
问五：HTTP 传输模式安全吗？能不能暴露到公网？
答：官方设计上 HTTP 只监听回环（127.0.0.1 / ::1），绑定可路由地址会被直接拒绝；本地路径和 file:// 在 HTTP 模式下也会被自动拒绝，防越权读文件。要跨机器访问，请在前面加 nginx + mTLS 反代，不要直接把端口暴露公网。
相关链接
- 项目仓库：NVIDIA/SkillSpector
- 官方托管指南：Scan agent skills before installation
- NVIDIA Verified Skills 总览：docs.nvidia.com/skills
- NVIDIA skills 官方目录：NVIDIA/skills
- 开发指南：docs/DEVELOPMENT.md
- 误报抑制指南：docs/SUPPRESSION.md
- 资源上限说明：docs/ANALYSIS_RESOURCE_BOUNDS.md
- MCP 协议：Model Context Protocol
- CVE 数据源：OSV.dev