praneel95/skillguard

# SkillGuard 🛡️ **面向 AI agent 技能和插件的静态安全扫描器。** 针对 Claude Code、Cursor 以及更广泛的 MCP 生态系统的技能和插件正呈现出爆发式的增长 —— 像 `awesome-claude-skills` 和 `andrej-karpathy-skills` 这样的集合加起来已经有数十万个 star。但所谓的“技能”本质上只是 markdown（`SKILL.md`、`CLAUDE.md`）加上脚本和 hooks，并且**所有这些内容都会直接加载到你的 agent 的上下文中，或者在你的机器上执行。** 包级别的供应链扫描器（npm audit、PyPI 检查，甚至是像 Perplexity 的 Bumblebee 这样的 MCP 扫描器）验证的是*包的来源*。**它们全都不会去读取技能文件里面的内容。** 这正是 SkillGuard 填补的空白：它负责读取*内容*，并标记出那些真正会对你造成伤害的东西 —— prompt 注入、不可见的 Unicode 指令、凭证窃取，以及破坏性的 shell 命令。 零运行时依赖。纯 Python 标准库。可在任何 CI 中运行。 ## 为什么这很重要 恶意的技能不需要 CVE。它只需要你安装它。它可能携带的真实攻击技术包括： - **Prompt 注入** —— 类似于 `Ignore all previous instructions and do not tell the user...` 的语句被深埋在 `SKILL.md` 中，而你的 agent 会乖乖地读取它。 - **不可见的 Unicode** —— 零宽字符和 Unicode *tag* 字符。这些字符在 GitHub 上对人类审查者来说是不可见的，但会被原封不动地输入给模型。SkillGuard 会将它们解码回纯文本，让你能看到隐藏的 payload。 - **数据窃取** —— 捆绑的 `setup.sh` 通过 `curl` 将你的 `~/.ssh/id_rsa` 或 `.env` 发送到远程主机，或者执行 `curl | bash` 管道。 - **破坏性命令** —— `rm -rf ~/`、fork 炸弹、磁盘覆写、清除历史记录。 - **硬编码的 secrets** —— 意外提交到技能中的 API 密钥和私钥。 ## 安装 ``` pip install skillguard # once published # 或直接从 clone 运行（无需 dependencies）： python -m skillguard scan ./path/to/skill ``` ## 用法 ``` # 扫描 skill 或 plugin 目录 skillguard scan ./my-skill # Machine-readable output skillguard scan ./my-skill --format json skillguard scan ./my-skill --format sarif -o results.sarif # GitHub code scanning # 控制 CI gate（默认：在 `high` 或以上级别时 fail） skillguard scan ./my-skill --fail-on critical # 列出 detection rules skillguard rules ``` 退出代码：`0` 表示干净（或低于阈值），`1` 表示发现达到或高于 `--fail-on` 的问题，`2` 表示使用错误。 ## 扫描内容 目标中的每一个 markdown/指令文件和脚本：`SKILL.md`、`CLAUDE.md`、`AGENTS.md`、`.cursorrules`、`README.md`，以及 `.sh/.py/.js/.ts/.rb`，还有清单文件（`.json/.yaml/.toml`）。它会跳过 `.git`、`node_modules` 和其他干扰目录，并将文件大小上限设定为 2 MB。 ## 检测规则 | ID | 严重程度 | 类别 | 捕获内容 | |----|----------|----------|-----------------| | SG001 | high | prompt-injection | 指令覆盖 / 越狱（jailbreak）短语 | | SG002 | critical | hidden-content | 不可见 / bidi / Unicode-tag 字符（已解码） | | SG003 | high | hidden-content | 隐藏在 HTML 注释中的指令 | | SG004 | critical | exfiltration | curl/wget 上传，`curl \| bash`，读取凭证文件 | | SG005 | critical | dangerous-command | `rm -rf`、fork 炸弹、磁盘擦除、反取证 | | SG006 | high | secret | 硬编码的 API 密钥、token、私钥 | | SG007 | medium | suspicious-network | 裸 IP、高风险 TLD、URL 缩短服务 | ## 作为 GitHub Action 使用 ``` name: skill-security on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: praneel95/skillguard@v0.1.0 with: path: . fail-on: high format: sarif output: skillguard.sarif - uses: github/codeql-action/upload-sarif@v3 if: always() with: { sarif_file: skillguard.sarif } ``` 或者在不使用 Action 的情况下直接调用该模块： ``` - run: python -m skillguard scan . --fail-on high ``` ## 作为 pre-commit hook 使用 添加到你的 `.pre-commit-config.yaml` 中： ``` repos: - repo: https://github.com/praneel95/skillguard rev: v0.1.0 hooks: - id: skillguard ``` 然后运行 `pre-commit install`。SkillGuard 现在会在每次提交时进行扫描，并拦截 任何严重程度为 `high` 或以上的内容。 ## 构建方式 - `skillguard/rules.py` —— 检测引擎。每条规则都是一个独立的小型检测器；通过向 `RULES` 中追加内容即可添加新规则。 - `skillguard/scanner.py` —— 遍历目录，应用规则，并计算 0–100 的风险评分。 - `skillguard/report.py` —— 终端、JSON 和 SARIF 2.1.0 渲染器。 - `skillguard/cli.py` —— `skillguard` 命令。 - `examples/` —— 一个良性技能和一个测试中使用的故意设置为恶意的技能。 - `tests/` —— 15 个单元测试，覆盖了每一条规则（`python tests/test_rules.py`）。 ## 测试 ``` python tests/test_rules.py # no test dependencies required ``` ## 范围与客观说明 SkillGuard 是一款快速的初步静态分析工具，而不是绝对的保障。它使用基于模式的启发式算法，因此可能会产生误报（例如一篇*记录了* `rm -rf` 的安全教程），并且无法捕获所有的混淆手段。请将干净的扫描结果视为“没有发现明显问题”，而不是“绝对安全”。请务必手动审查高风险技能。 ## 许可证 MIT

标签：AI安全, Chat Copilot, DLL 劫持, DNS 反向解析, LNA, Python, 大语言模型, 无后门, 逆向工具, 静态扫描