SkillSpector 扫描技能：安装、漏洞与报告解读

准备安装一个从 GitHub 拉下来的第三方 Agent Skill 时，如果源码里出现了 curl | bash、向外部地址 POST 数据，或者直接调用 exec()，最稳妥的做法不是先复制到 Agent 的技能目录，而是把它放在临时目录里扫描：

skillspector ./path-to-your-skill

基础扫描不依赖 LLM API Key，会执行规则匹配、AST 分析和依赖漏洞查询等静态检查。已经按当前官方 README 配置好模型服务后，可以再运行一次语义分析：

skillspector --llm ./path-to-your-skill

--llm 是对静态结果的上下文复核，不是绕过静态检查的开关。只要报告仍包含数据外泄、远程脚本执行或越权调用的证据，就不应直接安装。

SkillSpector 是 NVIDIA 开源的 Agent Skill 安全扫描器，近期登上 GitHub Trending，项目仓库是 NVIDIA/SkillSpector。它并不是“安装即放行”的安全认证，最终是否安装，仍应根据源码证据和运行权限判断。

先把扫描器跑起来：安装、路径与 API Key 报错

在 Linux 或 macOS 上，现有资料确认的基础流程是克隆仓库、创建虚拟环境并激活：

git clone https://github.com/NVIDIA/SkillSpector.git
cd SkillSpector
python3 -m venv .venv
source .venv/bin/activate

创建并激活 .venv 并不等于已经安装了 SkillSpector。现有资料没有给出一条跨版本都稳定的依赖安装命令，因此不要从旧教程里抄一个 pip install 命令直接执行。应以当前 官方仓库 README 的 Installation 部分为准，完成项目和依赖安装后，再验证 CLI：

skillspector --help

如果帮助信息能够正常显示，说明扫描器本身已经可用；此时再准备待检查的 Skill，而不是反复重装虚拟环境。

Windows PowerShell 应使用自己的激活脚本：

.\.venv\Scripts\Activate.ps1

随后用 PowerShell 自己的命令定位可执行文件：

Get-Command skillspector
skillspector --help

如果团队主要使用 Bash 脚本、Linux 容器和 Unix 路径，直接在 WSL 中执行前面的 Linux 流程，通常比来回处理两套路径更省事。

遇到常见阻碍时，可以按现象定位：

在 Bash 中，可以用下面两条命令确认“命令找不到”究竟发生在哪一层：

command -v skillspector
skillspector --help

如果 command -v 返回空值，先检查虚拟环境和安装状态；如果它指向系统中的其他路径，而不是当前 .venv 下的可执行文件，则可能是激活失败或 PATH 污染。不要仅凭终端提示符判断虚拟环境是否生效，路径输出更可靠。

Docker 方式适合把扫描放进隔离环境。资料中的构建和挂载命令如下：

cd /path/to/SkillSpector
docker build -t skillspector .

cd /path/to/your-skill
docker run --rm -v $(pwd):/scan skillspector

第一组命令必须在 SkillSpector 源码目录执行，否则 Docker 找不到构建上下文。第二组命令挂载的是待扫描 Skill；-v 左侧是宿主机路径，右侧是容器内路径。资料中的命令假定当前镜像会扫描 /scan，如果新版镜像要求显式传入目标路径，应以仓库 README 和 skillspector --help 为准。

Linux 和 macOS 可以使用 $(pwd)。PowerShell 中 $(pwd) 不是 Bash 写法，可以改用：

docker run --rm -v "${PWD}:/scan" skillspector

原生 Windows 与 Docker Desktop 还涉及宿主机路径转换，容器里看到空目录时，不要先怀疑扫描规则。更简单的做法是统一在 WSL 中挂载和执行，避免同时维护 /mnt/c/...、PowerShell 路径和容器路径三套写法。

至于 --llm，它需要当前版本所要求的模型凭证，而不同版本可能使用不同提供商、模型和配置方式。现有资料没有确认统一的环境变量名，因此这里不写死任何变量名。配置缺失时，先确保下面的基础命令能运行：

skillspector ./path-to-your-skill

基础静态扫描和 OSV.dev 依赖查询不需要 LLM API Key。排查时应把环境问题和扫描发现分开处理。

要扫什么：本地、远程输入与 64 种漏洞模式

SkillSpector 支持 Git 仓库、远程 URL、ZIP 文件、本地目录和单个文件。当前资料确认的本地调用方式包括：

skillspector ./path-to-your-skill
skillspector ./path-to-one-file
skillspector --help

远程 Git、URL 和 ZIP 的具体参数应以当前 skillspector --help 为准。不同版本可能调整输入参数，不要凭印象增加 scan 子命令或 --repo 一类未经确认的开关，也不要从旧文章复制整条远程扫描命令。遇到远程输入时，先查看帮助信息，再按当前版本语法传入目标即可。

它的核心检测范围在资料所示版本中包含 64 种漏洞模式、16 个类别。检测项除普通代码中的危险函数外，还包括 Prompt Injection、Data Exfiltration、Privilege Escalation、Supply Chain、Excessive Agency、System Prompt Leakage、Memory Poisoning、Tool Misuse、Trigger Abuse、YARA 签名、数据流追踪，以及 MCP 最小权限和 MCP 工具投毒等检查。

实际排查时，可以先把常见信号映射到风险类型：

资料中的 P1 示例对应指令覆盖，P2 示例对应数据外泄命令。规则编号会随版本调整，排查时应以报告里的规则名称、文件位置和具体证据为准，不能只记一个编号。

SkillSpector 的检测流程分为两个阶段。第一阶段是快速静态分析，包含正则匹配、AST 行为分析、数据流追踪、YARA 规则和依赖漏洞查询；第二阶段是可选的 LLM 语义分析，由模型结合上下文解释静态结果，过滤一部分误报，并带有反越狱保护。

这两个阶段不是替代关系。AST 能指出代码里存在危险调用，却未必知道参数是否来自用户；LLM 能补充业务上下文，但它的判断仍然不能取代源码证据。启用 --llm 前，还应确认当前版本会把哪些 Skill 内容发送给所配置的模型服务。包含密钥、客户数据或内部代码的 Skill，不适合未经确认直接送往外部模型。

依赖检查走 OSV.dev 获取已知漏洞信息，不需要 LLM API Key，并支持缓存。资料还说明，网络不可用时可以回退到本地列表，但这个回退结果不能等同于实时漏洞查询：本地列表可能没有收录刚发布的漏洞，也可能包含已经修复的旧通告。网络恢复后重新扫描，依赖情报才更完整。

实际排查可按以下顺序进行：先保留一份未经修改的原始 Skill 并扫描，保存报告；再人工核对高风险规则对应的文件、行号、输入来源和外部流向；随后处理权限、外传和依赖问题；最后对同一个目标重新扫描。如果风险来自多个 Skill 的组合调用，例如一个 Skill 提供不可信输入，另一个 Skill 拥有更高权限，那么单次单文件扫描通过也不能证明整个 Agent 工作流安全。

报告怎么看：分数只是入口，证据才决定是否安装

资料中的 v2.0.0 报告节选如下。这组输出可用于把终端字段与源码位置对应起来；当前版本如果调整了规则编号、字段名称或分值，应以实际输出为准。

$ skillspector ./my-skill
SkillSpector Security Report v2.0.0
[MEDIUM] SC3: Unpinned dependency in setup.py
→ requests (no version pin)
[LOW] AST1: exec() call in setup.py:15

资料所示版本给出的分档和推荐标签是：

21-50   MEDIUM    CAUTION
51-80   HIGH      DO NOT INSTALL
81-100  CRITICAL  DO NOT INSTALL

现有资料没有完整说明 SAFE 对应的具体分数边界，因此不要自行补写 0-20。实际排查时应直接读取报告中的 Recommendation 字段，而不是根据旧版本区间反推。

资料还列出了该版本的基础加权值：

CRITICAL +50
HIGH     +25
MEDIUM   +10
LOW      +5

这不是 CVSS，也不能脱离报告自行解释成统一行业标准。基础权重与最终等级分档在现有资料中的说明并不完全一致，因此不要自己用这些数字重算一个“官方结论”；最终以当前版本报告为准。

拿到报告后，可以按这个顺序阅读：

1. 先看 SAFE、CAUTION 或 DO NOT INSTALL，确认报告给出的总体建议。
2. 再看每条发现的严重等级、规则编号、文件路径和行号。
3. 追踪风险路径：数据从哪里来，经过了什么处理，最终流向哪里，是否跨越了原本的信任边界。
4. 优先处理权限提升、数据外泄和远程执行等能够直接影响宿主环境的问题。
5. 修复或移除触发点后重新扫描，确认对应规则消失，而不是只确认总分下降。

误报在静态扫描中很常见。exec() 本身不等于恶意，环境变量读取和外部请求也不必然是数据外泄。判断依据应是参数是否可控、目标是否可信、发送了什么数据，以及 Agent 运行身份拥有哪些权限。资料提到可选 LLM 阶段可以利用上下文降低部分误报，但它仍然只是辅助判断，最终应回到源码证据。

不建议因为一个合理调用就整条规则全局忽略。确属业务所需时，豁免应限定到具体目录、规则和代码路径，并记录原因；例如经过审查的构建脚本与未知 Skill 目录，不应使用同一条宽松策略。这样后续依赖升级或代码变动时，例外才不会悄悄扩大。

三个推荐标签可以直接转成处理动作。出现 DO NOT INSTALL 时，先隔离来源，不要复制进开发环境，移除或替换触发点后再复扫。出现 CAUTION 时，需要人工复核高风险项，固定依赖、收紧权限，并在隔离环境验证实际行为。出现 SAFE 时，只能理解为“当前规则和当前输入范围内没有发现已知问题”，不能扩展成“运行时和组合调用绝对安全”。

SkillSpector 还可以输出 SARIF，适合接入 CI/CD 或 IDE。当前材料没有确认统一的输出参数，所以应先执行 skillspector --help，按当前版本提供的选项生成 SARIF，再上传为流水线产物。团队可以自行把 HIGH、CRITICAL 或 DO NOT INSTALL 设为阻断条件；不要直接照搬旧文章中的 --sarif、--fail-on 等开关，除非当前帮助信息中确实存在。

SkillSpector 目前仍不能代替运行时防护。规则和评分会随版本变化，静态分析与可选语义分析都无法证明 Agent 在真实组合调用中的行为，多 Skill 交互还可能产生单次扫描看不到的风险，离线依赖回退也可能落后于最新漏洞情报。

因此，更稳妥的落地方式是：安装前扫描并保留原始报告，按证据人工复核，在隔离环境中以最小权限运行，修复后复扫，并持续更新依赖。即使报告给出 SAFE，它也应当是一道安装门禁，而不是永久有效的安全证明。

封面图：HTTP 451 in curl (bash)，作者 Qzekrom (screenshot)，Public domain，来自 Wikimedia Commons