kubouchiyuya/komainu

你的 AI 整天都在安装来自陌生人的代码 —— 一个 skill，一个 plugin，一个 repo，或者一个 package。它**读取**这些文件作为指令，并**以极快的机器速度代替你运行**它们的脚本，而这通常发生在你没有看着的时候。仅仅一个被植入恶意代码的文件，就会将你那好用的 agent 变成别人的工具，而你可能永远都蒙在鼓里。 **狛犬就是那道缺失的权限关卡。** 它得名于神社门前驱邪的守护狮犬 —— 它以只读方式 clone，读取每一个文件，寻找第三方代码攻击 *agent* 的方式，隔离危险内容（绝不删除），并交还一个干净的副本 —— 或者直接拒绝。**在整个过程中，绝对不会执行任何代码。** ``` komainu import https://github.com/owner/repo # → 安全 你可以使用它 # → 审查 应先由人工查看 # → 危险 已拒绝 ``` ## ✨ 核心功能 - **以攻击者武器化代码的方式阅读代码** —— **11 个类别**：prompt injection（提示词注入）、自动运行陷阱、机密窃取、伪装的恶意软件、guardrail 篡改、supply chain/dependency 风险、MCP 工具中毒、持久化与 reverse shell、破坏性 payload、path traversal（路径遍历）以及权限提升。 - **绝不执行它检查的内容。** 纯只读的静态分析。一个永远不会触发的陷阱就无法伤害你 —— 这就是全部的保证。 - **隔离而非删除。** 所有危险内容都会被移动到 `_QUARANTINE/` 并附有清单。你可以检查它、恢复它，或者不管它。 - **为每个 agent 自动触发。** PATH shim 拦截任何通过 shell 调用原始 clone/install 的行为 —— 适用于 Claude Code、OpenAI Codex、Grok、Cursor、Aider、Gemini CLI —— 此外还包含一个确定性的 Claude Code hook。 - **零依赖。** 纯 Python stdlib。在 mac、Linux 和 Windows 上提供完全一致的判定结果。 - **设计上的诚实。** `SAFE` 意味着“没有静态威胁 + 没有自动运行的代码”，而不是“随便运行都安全”。文档从不夸大其词。 ## 🚀 快速开始 ``` # 作为一个 Claude Code 插件 claude plugin marketplace add kubouchiyuya/komainu claude plugin install komainu # 开启 universal shell gate（任何执行 shell 的 agent） komainu install-shims echo 'export PATH="$HOME/.komainu/bin:$PATH"' >> ~/.zshrc ``` 然后审查任何内容： ``` komainu import https://github.com/owner/repo # clone → scan → sterilize → report komainu scan ./local/dir # vet something you already have komainu selfcheck # check your environment sh skills/komainu/tests/smoke.sh # 16 offline assertions ``` ## 🚪 它能阻止的威胁 —— 11 个类别 | 威胁 | 通俗解释 | 狛犬 (Komainu) | |---|---|---| | 🩹 **Prompt injection（提示词注入）** | README 里隐藏的一行指令命令你的 AI 泄露你的密钥 | 检测针对 AI 的文本（英/日/中）+ 不可见/双向/标签 unicode；隔离，剥离隐藏字符 | | ⚡ **自动运行** | 当你 clone/open/`npm install` 时它就会运行 | 在 clone 时解除 git hooks、`.gitattributes` 过滤器、submodules、lifecycle scripts、`.vscode`/`.envrc`/`.pth`/`conftest.py`/`build.rs` 的武装 | | 📤 **数据窃取** | 读取 `~/.ssh`/`.env` 并使用 `curl` 发送出去 | 标记机密读取 + 网络请求、`curl \| sh`、出站 POST —— 一经发现即隔离 | | 🧬 **伪装的恶意软件** | base64 数据块、不透明的二进制文件 | 标记动态代码 eval、编码的 payload、不透明的二进制文件、提交的机密信息 | | 🔓 **Guardrail 篡改** | 重写你的 `settings.json`/`CLAUDE.md`/hooks 以关闭防护 | 专门监控 → **直接拒绝** | | 📦 **Supply chain（供应链）** | 来自 git/URL 的依赖、registry 覆盖、无 lockfile | 标记 dependency-confusion（依赖混淆）和未锁定的 supply chain（npm Shai-Hulud 时代） | | 🧩 **MCP 工具中毒** | 隐藏在 MCP 工具描述中的指令 | OWASP MCP03 —— 标记中毒的描述和远程获取 server 的命令 | | 🕳️ **持久化 / 后门** | reverse shell、cron job、被添加的 SSH key | 标记 `/dev/tcp`、`nc -e`、`authorized_keys`、cron/launchd/systemd | | 💥 **破坏性操作** | `rm -rf /`、fork bomb、磁盘擦除 | 标记大规模删除、fork bomb、`dd`/`mkfs` | | 🧨 **Path traversal（路径遍历）** | zip-slip、在 repo 之外写入 | 标记 `extractall`、`../` 写入 | | ⬆️ **权限提升** | setuid、`sudo`、`chown root` | 标记 setuid 位、`sudo`、root 所有权 | 完整分类及残留风险分析 → [threat-model.md](skills/komainu/references/threat-model.md)。 ## 🧭 工作原理 10 个阶段；其中第 2-5 阶段**不**触碰任何运行中的代码。拦截 → 最小化的只读 clone（锁定 SHA，丢弃 `.git`，关闭 filters/hooks）→ 扫描 → 消毒 → 判定 → 沙盒化 install（`--ignore-scripts`，无网络）→ 重新验证 → 优化 → 激活 → 审计。深入了解 → [工作原理](skills/komainu/docs/how-it-works.md)。 ## 🧪 测试 / CI | 命令 | 目的 | |---|---| | `sh skills/komainu/tests/smoke.sh` | 16 项离线断言：每个类别均能检测并消毒，干净的 repo 通过测试，shim 进行拦截 | | GitHub Actions (`ci.yml`) | 在每次 push 时运行 smoke 测试套件 —— 上方的徽章即是证明 | ## 🌐 适用于所有 AI、所有操作系统 两层执行机制，因此即使一层被绕过，另一层依然有效。扫描引擎采用单一的纯 Python 实现，因此**判定结果在任何地方都是一致的** —— 只有执行层有所不同。 | 层级 | 覆盖范围 | 强度 | |---|---|---| | **PATH shim** | 任何通过 shell 驱动的 agent（Claude Code、OpenAI Codex、Grok、Cursor、Aider、Gemini CLI） —— mac/Linux，Windows 上的 PowerShell | 强力 / 确定性 | | **Claude Code hook** | Claude Code 内部的 Bash-tool clone | 强力 / 确定性 | | **路由代码片段** | 通过其配置文件实现的 Codex / Grok / Cursor / Gemini | 建议/参考 | ## ⚖️ 诚实的局限性 - `SAFE` ≠ 可以随意运行任何东西 —— 它意味着没有静态威胁 + 没有自动运行的代码。 - 静态扫描可能会漏掉新型/混淆的 payload；真正的防线在于*什么都不运行*，而不是依赖于规则列表。 - Regex 规则可能会被绕过 —— `KOMAINU_BYPASS=1` 是经过审计的逃生出口。 - 如果一个 repo 的整体目的就是恶意的，清理它就会使其丧失原本的功能，因此 Komainu 会选择拒绝 (DANGER)，而不是提供一个被掏空的空壳副本。 ## 📜 许可证 MIT —— 详见 [LICENSE](LICENSE)。当 Komainu 引入第三方代码时，它会保留来源的 LICENSE 和署名。

标签：AI安全, Chat Copilot, Python, 云安全监控, 提示词注入防护, 无后门, 逆向工具, 静态分析