mx-klr/sentinel

# 🛡️ Sentinel — 您的代码安全卫士 **Sentinel 在您使用 Claude Code 或 Pi 等 AI 编程助手时为您保驾护航。** 每当您要求 AI 助手安装包、克隆仓库或编写代码时，恶意代码都有可能趁虚而入——隐藏的木马、被盗的凭据，或伪装成有用工具的后门。Sentinel 会自动监控这些威胁，让您无需操心。 ## Sentinel 能防范什么？ ### 1. 恶意包 当您的 AI 安装包时（例如 `npm install something` 或 `pip install something`），Sentinel 会在安装**之前**进行检查： - **名称是否可疑？** 攻击者会创建与流行包名称几乎相同的包（例如用 `lodsh` 代替 `lodash`）。一个拼写错误，您就可能安装了恶意软件。 - **是否是全新的？** 发布不到一周且下载量很少的包属于高风险。 - **是否存在已知漏洞？** Sentinel 会检查安全公告数据库。 - **是否在安装期间运行代码？** 有些包会在您安装的瞬间执行隐藏脚本。 ### 2. 仓库中的木马代码 当您的 AI 克隆 GitHub 仓库时，Sentinel 会扫描整个代码库，查找： - **隐藏的后门** —— 秘密连接到攻击者服务器的代码 - **凭据窃取** —— 读取您的密码、SSH 密钥或 API token 的代码 - **混淆的载荷** —— 故意打乱以隐藏其真实功能的代码 - **加密货币挖矿程序** —— 使用您的计算机挖掘加密货币的代码 ### 3. 代码中泄露的机密 Sentinel 会检测意外（或故意）嵌入的凭据： - AWS 访问密钥 - GitHub token - Stripe 支付密钥 - OpenAI / Anthropic API 密钥 - 私有加密密钥 - 密码和通用 API 机密 ### 5. AI 劫持（Prompt Injection） 这是最新、最阴险的攻击向量。当您克隆仓库时，其中可能包含劫持您 AI 助手的隐藏指令： - **恶意的 CLAUDE.md 文件** —— 这些文件看起来像正常的项目说明，但它们会指示您的 AI 授予自身无限权限、禁用安全检查或秘密运行命令 - **注释中的隐藏指令** —— README 文件中的 HTML 注释（在 GitHub 上阅读时不可见），指示您的 AI 执行恶意命令 - **不可见字符** —— 零宽 Unicode 字符，将 prompt injection 载荷隐藏在看似正常的文本中 - **虚假的 MCP 服务器配置** —— 将您的 AI 连接到攻击者控制的服务器的配置文件，赋予他们远程访问您机器的权限 - **YOLO 模式技巧** —— 禁用所有安全确认的配置，以便 AI 在不询问您的情况下执行危险操作 当您克隆仓库时，Sentinel 会自动扫描所有这些内容。如果发现任何内容，它会拒绝遵循恶意指令，直到您明确批准。 ### 6. 可疑的 AI 生成代码 当您的 AI 助手编写访问敏感区域（您的文件、环境变量、网络）的代码时，Sentinel 会将其标记出来，以便您进行审查。 ## 它是如何工作的？ Sentinel 运行在您的 **AI 助手内部**（Claude Code 或 Pi）。您无需做任何操作——它会自动工作。 ### 三层防护 ``` ┌─────────────────────────────────────────────────────┐ │ Layer 1: GATE │ │ Checks packages BEFORE they're installed │ │ ⏱️ ~1 second · completely free │ ├─────────────────────────────────────────────────────┤ │ Layer 2: SCAN │ │ Scans code files for malicious patterns │ │ ⏱️ ~1-5 seconds · completely free │ ├─────────────────────────────────────────────────────┤ │ Layer 3: AI TRIAGE │ │ Your AI reviews ambiguous findings │ │ ⏱️ ~2-5 seconds · minimal token cost │ └─────────────────────────────────────────────────────┘ ``` 大部分工作由前两层完成，它们是**即时且免费的**——不消耗 AI token。AI 分诊层仅在发现真正模棱两可的情况时（罕见）才会启动。 ## 当 Sentinel 发现问题时会发生什么？ ### 🛑 严重威胁 — 硬性停止 您的 AI 助手**立即停止**并告诉您它发现了什么。 示例： **在继续任何操作之前，您必须明确说是。** 如果您不确定，请说不。 ### ⚠️ 警告 — 提示 您的 AI 标记了异常情况，但继续工作。 示例： ### 📝 信息 — 静默记录 次要的观察结果会被记录，但不会打断您的工作。您可以随时询问 "sentinel status" 来查看它们。 ## 设置指南 ### 步骤 1：安装技能 **对于 Claude Code 用户：** 将 `sentinel` 文件夹复制到您的 Claude Code 技能目录中： ``` ~/.claude/skills/sentinel/ ``` **对于 Pi 用户：** 将 `sentinel` 文件夹复制到您的 Pi 技能目录中： ``` ~/.pi/skills/sentinel/ ``` 或者，如果您是通过 git 仓库收到的： ``` # Claude Code ln -s /path/to/sentinel ~/.claude/skills/sentinel # Pi ln -s /path/to/sentinel ~/.pi/skills/sentinel ``` ### 步骤 2：首次对话 下次您与 AI 助手开始对话时，Sentinel 将自动激活并询问您几个设置问题： **问题 1：知识库连接** - 如果您使用 Obsidian、Notion 或类似工具：说是并提供详细信息 - 如果您不知道这意味着什么：**直接说不** —— Sentinel 在没有它的情况下也能完美运行 - 您随时可以通过说 "sentinel settings" 来连接一个 **问题 2：自动记录（仅当您连接了知识库时）** 选择一项： - **所有发现** —— 记录所有内容，包括次要的观察结果 - **警告及以上** —— 记录警告和严重威胁（推荐） - **仅严重** —— 仅记录硬性停止 - **无自动记录** —— 您手动决定保存什么 ### 步骤 3：完成 就是这样。Sentinel 现在自动运行。您无需记住命令或检查任何内容。它静默监控，仅在重要时发声。 ## 您可以向 AI 询问的内容 您无需记住命令。只需自然交谈： | 您想要什么 | 该说什么 | |---------------|-------------| | 扫描您当前的项目 | "Can you scan this project for security issues?" | | 检查包是否安全 | "Is lodash safe to install?" | | 查看扫描结果 | "What did sentinel find?" | | 将结果保存到您的笔记 | "Save that scan to my brain" | | 更改设置 | "Update sentinel settings" | | 暂时关闭 | "Turn off sentinel for now" | | 重新打开 | "Turn sentinel back on" | ## 了解严重性级别 ### 🛑 严重 — “这几乎肯定很危险” 这些发现代表了**与恶意软件 overwhelmingly 相关**的模式： - 解码隐藏载荷并执行它们的代码 - 通过管道直接传输到 shell 命令的下载 - 连接到可疑 IP 地址 - 旨在窃取您凭据的包 - 包中的已知安全漏洞 **该怎么做：** 除非您绝对确定这是安全的，否则不要继续。请您的 AI 详细解释。如果有疑问，请说不。 ### ⚠️ 警告 — “这值得您关注” 这些发现**可疑但可能是合法的**： - 下载量很少的新包（可能是新的但合法的） - 访问系统命令的代码（可能是构建工具） - 看起来经过混淆的代码（可能只是被压缩的） - 硬编码的 IP 地址（可能是合法的服务器） **该怎么做：** 阅读解释。如果它对您正在构建的内容有意义，那可能没问题。如果说不通，请您的 AI 进一步调查。 ### 📝 信息 — “了解一下很好” 这些是**次要的观察结果**，并不表示危险： - 锁定文件中没有完整性哈希的包 - 相对较新的包上的单个维护者 - 看起来良性的安装脚本 **该怎么做：** 无需操作。这些已记录供您参考。如果您好奇，可以查看它们。 ## 常见问题 **Q: Sentinel 会减慢我的 AI 助手的速度吗？** 不会。门禁检查耗时不到 1 秒。代码扫描耗时 1-5 秒。您不会注意到它。 **Q: Sentinel 需要花钱或使用我的 AI token 吗？** 前两层（门禁和扫描）是完全免费的——它们使用模式匹配，而不是 AI。AI 分诊层仅在罕见的模棱两可的情况下触发，使用最少的 token（相当于一条短消息）。 **Q: Sentinel 能捕获所有内容吗？** 没有任何安全工具能捕获所有内容。Sentinel 捕获最常见和最危险的攻击模式。它比没有保护要好得多，而大多数开发者目前正是处于无保护状态。把它想象成烟雾探测器——它无法预防每场火灾，但它会向您发出最明显危险的警报。 **Q: 我有一些我自己编写的文件（笔记、文档、草稿），我会将它们带入项目中。Sentinel 会标记它们吗？** 可能会，因为 Sentinel 无法判断文件是您编写的还是从攻击者那里下载的。但这很容易解决——您只需告诉 Sentinel 哪些文件夹包含您自己的内容。 **三种将文件夹标记为受信任的方法（选择最简单的一种）：** **选项 A — 文件夹选择器（推荐给非技术用户）：** 只需说 "sentinel trust"，就会打开一个普通的 Finder 窗口。浏览到您的文件夹，点击选择，完成。Sentinel 会确认它找到的内容并要求您批准。 **选项 B — 拖放：** 在聊天窗口旁边打开 Finder。抓住一个文件夹并将其直接拖入聊天中。文件夹路径将显示为文本。Sentinel 会识别它并询问：“Want to trust this folder?” **选项 C — 输入路径：** 如果您知道路径，只需说 "sentinel trust /path/to/my/folder"。 **常见的受信任文件夹：** - 您的笔记或草稿文件夹 - 手机文件同步到的文件夹 - 您的个人工作文档目录 - 您保存给自己发送内容的文件夹 一旦受信任，这些文件夹内的内容对 Sentinel 来说是完全不可见的——从不扫描，从不警告。您可以随时添加更多文件夹，并使用 "sentinel untrust" 删除它们。 您还可以在任何项目内创建一个 `.sentinel-trust.json` 文件，以将该项目内的特定文件夹标记为您自己的内容。 **Q: Sentinel 标记了我自己的代码！我该怎么办？** 当您编写的代码看起来与攻击模式相似时，就会发生这种情况——例如，如果您正在编写安全工具、记录攻击或出于合法目的使用 eval/exec。只需告诉您的 AI： - "That is my code, it is fine" —— AI 将在本次会话中接受它 - "Add this to the allowlist" —— AI 将永久抑制该特定发现 - "I write security tools, disable the prompt injection rules" —— AI 将关闭整个规则类别 Sentinel 会在您的项目中创建一个 `.sentinel-allow.json` 文件来记住您的覆盖设置。您也可以直接编辑此文件。 **Q: 如果 Sentinel 标记了实际上是安全的内容怎么办？** 这种情况可能会发生，尤其是对于警告。阅读解释，如果您确信它是安全的，请告诉您的 AI 继续。Sentinel 宁可谨慎行事——虚惊一场总比漏掉威胁好。 **Q: 我可以与朋友分享 Sentinel 吗？** 可以！只需分享 sentinel 文件夹。他们将其复制到他们的技能目录中，下次对话时就会受到保护。 **Q: Sentinel 向外部发送什么数据？** Sentinel 会查询公共包注册表（npmjs.org、pypi.org）以检查包信誉——这与您安装任何内容时包管理器所做的操作相同。它**不会**将您的代码、文件或任何个人信息发送到任何地方。 ## 文件结构 ``` sentinel/ ├── SKILL.md ← Instructions for your AI (don't edit) ├── README.md ← This file (for humans) ├── config.json ← Your preferences (created during setup) ├── config.template.json ← Default config template ├── scripts/ │ ├── gate.sh ← Package reputation checker │ ├── gate_check.py ← Gate logic (Python) │ ├── scan.sh ← Code scanner launcher │ ├── scan_engine.py ← Scan logic (43 detection rules) │ └── monitor.sh ← Runtime process watcher └── tests/ ├── run-tests.sh ← Test suite (39 tests) └── fixtures/ ← Test files for validation ``` ## 版本 **Sentinel v3** —— 52 条检测规则，39 项测试，零依赖。 用心构建。注意安全。🛡️

标签：AI助手, AI安全, AMSI绕过, API密钥检测, Chat Copilot, CISA项目, Claude Code, DevSecOps, Homebrew安装, NPM安全, PyPI安全, 上游代理, 云安全监控, 代码安全, 依赖扫描, 加密货币挖矿, 包管理安全, 后门检测, 威胁检测, 提示注入, 模型提供商, 混淆代码, 漏洞枚举, 结构化查询, 自动化安全, 输入验证, 逆向工具, 集群管理, 零依赖, 静态分析