项目简介
SkillSpector 分析 AI 代理技能中的漏洞、恶意模式与安全风险，支持 Git 仓库、URL、文件等多种输入格式，提供风险评分与各类格式的详细报告，并可选择使用 LLM 语义分析增强检测。
README 预览
# SkillSpector\n\n**Security scanner for AI agent skills.** Detect vulnerabilities, malicious patterns, and security risks before installing agent skills.\n\n[](https://www.python.org/downloads/)\n[](https://www.apache.org/licenses/LICENSE-2.0)\n\n## Overview\n\nAI agent skills (used by Claude Code, Codex CLI, Gemini CLI, etc.) execute with implicit trust and minimal vetting. Research shows that **26.1% of skills contain vulnerabilities** and **5.2% show likely malicious intent**.\n\nSkillSpector helps you answer: **"Is this skill safe to install?"**\n\n## Documentation\n\n- **[Development guide](docs/DEVELOPMENT.md)** — Architecture, package layout, and how to extend the analyzer pipeline.\n\n## Features\n\n- **Multi-format input**: Scan Git repos, URLs, zip files, directories, or single files\n- **64 vulnerability patterns** across 16 categories: prompt injection, data exfiltration, privilege escalation, supply chain, excessive agency, output handling, system prompt leakage, memory poisoning, tool misuse, rogue agent, trigger abuse, dangerous code (AST), taint tracking, YARA signatures, MCP least privilege, and MCP tool poisoning\n- **Two-stage analysis**: Fast static analysis + optional LLM semantic evaluation\n- **Live vulnerability lookups**: SC4 queries [OSV.dev](https://osv.dev) for real-time CVE data with automatic offline fallback\n- **Multiple output formats**: Terminal, JSON, Markdown, and SARIF reports\n- **Risk scoring**: 0-100 score with severity labels and clear recommendations\n\n## Quick Start\n\n### Installation\n\nCreate and activate a virtual environment first (all `make` targets assume the venv is active). Use **uv** or **pip**; the Makefile uses `uv` if available, otherwise `pip`.\n\n```bash\n# Clone the repository\ngit clone https://github.com/NVIDIA/skillspector.git\ncd skillspector\n\n# Create and activate virtual environment\nuv venv .venv && source .venv/bin/activate\n# or: python3 -m venv .venv && source .venv/bin/activate\n\n# Install fo
常见问题 (5)
故障排除如何修复 SkillSpector TP4（mcp_tool_poisoning）LLM 批次串行运行导致扫描超时的问题？
升级到包含 PR #731 的 SkillSpector 构建版本，该 PR 已于 2026-10-06 合并到 main。此修复将 src/skillspector/nodes/analyzers/mcp_tool_poisoning.py 中的 _check_tp4 从：
batch_outcome = analyzer.run_batches_detailed(batches)改为：
batch_outcome = run_async(analyzer.arun_batches_detailed(batches))这样便使用了与语义分析器和元审查相同的共享并发运行器。设置并发上限，例如：
export SKILLSPECTOR_MAX_LLM_CONCURRENCY=4值为 1 仍会强制串行执行。结果仍按批次顺序排列，因此 TP4_MAX_FINDINGS 和账本投影的行为保持不变。在测试中，TP4 从约 270 秒降至 75 秒，完整扫描从 320 秒降至 206 秒。如果无法立即升级，可以增大 SKILLSPECTOR_MAX_WORKFLOW_SECONDS 或减少代码块数量作为临时解决方案。
故障排除如何让 SkillSpector 在自定义 YARA 规则编译失败时判定为失败，而不是返回 SAFE？
此问题影响 commit 9749372 处的 SkillSpector 2.11.2。该问题已由 PR #557 修复，因此请升级到包含该 PR 的 main 构建版本或发布版本。
升级后，无效的 .yar 文件会产生一条包含其路径和原因的 WARNING，static_yara 会被报告为 degraded/partial（降级/部分），并且 --fail-on-incomplete 会以非零状态退出，而不是返回 SAFE。
如果无法立即升级，请在扫描前验证每一条自定义规则：
for f in rules/*.yar; do
python -c "import sys,pathlib,yara; p=pathlib.Path(sys.argv[1]); p.read_text(encoding='utf-8'); yara.compile(filepath=str(p))" "$f" || exit 1
done这会同时检查 UTF-8 解码和 YARA 编译。移除 UTF-8 BOM 可使用：
sed -i '1s/^\xEF\xBB\xBF//' rules/acme.yar将 Windows-1252 编码的规则转换为 UTF-8 可使用：
iconv -f WINDOWS-1252 -t UTF-8 rules/acme.yar -o rules/acme.yar.utf8 \
&& mv rules/acme.yar.utf8 rules/acme.yar在受影响的版本上，可以使用 SKILLSPECTOR_LOG_LEVEL=DEBUG 运行以查看被跳过规则的相关消息，但不要依赖退出码，因为扫描仍会成功完成。
故障排除如何修复 SkillSpector 对包含 “Send BTC” 的 Bitcoin 资助文档报出的 ransomware_behavior 误报？
误报发生的原因是:ransomware_behavior YARA 规则使用其不区分大小写的 send\s+.*btc 勒索信模式匹配了通用的付款描述文字,并且使用了 any of them,因此无需出现加密或勒索要求即可触发匹配。该问题已在 PR #608(commit a0d489e6,于 2026-10-08 合并,Jira SKILLSPECT-232)中修复:该规则现在要求 Bitcoin 付款措辞周围必须具备勒索相关的上下文,并过滤从句开头的付款建议,同时保留加密、重命名、覆盖和威胁指标。请将 SkillSpector 更新到包含 commit a0d489e6 的版本,然后重新运行 ClawHub/SkillSpector 审计。如果无法立即更新,请暂时修改充值说明的措辞,以避免使用通用的 send ... BTC 模式,例如 "Fund the account using Bitcoin,",然后重新扫描。
故障排除为什么 `skillspector --help` 会显示缺少 API 密钥的警告并且运行缓慢？
这发生在 skillspector.graph 于模块导入时执行 graph = create_graph() 的情况下，导致 CLI 即使只是运行 --help 或 --version 也会构建并初始化所有分析器。升级到包含 PR #436 的版本，该版本用惰性、线程安全的图代理替换了急切（eager）的图构建。图仅在首次真正调用 graph.invoke() 或 graph.ainvoke() 时才会编译，而现有 API 保持不变。升级后，清除提供商凭据，并使用 time skillspector --help 进行验证：帮助信息应立即渲染，且不会出现缺少密钥的警告。当实际扫描初始化不可用的分析器时，仍会出现缺少凭据的警告。
故障排除如何修复 SkillSpector 将 .ZIP 或 .ZiP 压缩包当作普通文件处理而不解压的问题？
出现这种情况是因为 InputHandler.resolve()、_download_file() 和 _download_transitive_file() 使用了区分大小写的 .endswith(".zip") 检查。请将 SkillSpector 更新到包含已合并 PR #727 的版本，该版本能够不区分大小写地识别 ZIP 扩展名。如果无法更新，请将压缩包重命名为使用小写扩展名：
mv skill.ZIP skill.zip
mv skill.ZiP skill.zip对于以 application/octet-stream 提供的下载文件，请确保 URL 或保存的文件名以小写的 .zip 结尾。源代码级别的解决方法是将这三个方法中的检查都改为 filename.lower().endswith(".zip")。