monpinero/MagiSentry

# 🛡️ MagiSentry **面向 AI 编程智能体的供应链安全扫描工具。** 在安装或构建任何内容*之前*，通过一个 10 步扫描器自动扫描 Python (pip)、JavaScript (npm/yarn)、VS Code 扩展和 Dockerfile —— 这样您的 AI 智能体就不会被诱骗运行恶意代码。 [](https://www.python.org/) [](https://github.com/monpinero/MagiSentry/blob/main/LICENSE) [](https://github.com/monpinero/MagiSentry) [](https://github.com/monpinero/MagiSentry) [](https://github.com/monpinero/magisentry/actions/workflows/ci.yml) [](https://pypi.org/project/magisentry/) [🇸🇰 Slovenská verzia](README.SK.md) ## 关于 我不是开发者。我不懂 Python、JavaScript 或任何编程语言。我是一个 AI 爱好者，对一个问题感到好奇：当 AI 编程智能体运行 `pip install` 时，真的有人检查过安装了什么吗？ 我开始深挖。我发现的结果令人不安——针对开源包的供应链攻击是真实、频繁且快速增长的。而 AI 智能体是完美的目标：它们会自动、快速地安装包，且不加任何询问。 所以我构建了 MagiSentry——在 AI 的协助下，从零开始，没有任何编程经验。代码是可用的。它经过了测试。它在本地运行。现在它就在这里，提供给任何需要的人。 ## 为什么选择 MagiSentry？ ### 威胁不再是假设——它正在加速 针对开源仓库（PyPI、npm、Docker Hub）的供应链攻击已经从孤立事件转变为一场**持续的、工业化的运动**，同时针对各大主要包仓库和 IDE 扩展市场的软件开发者。 以下数据证实了这一点： - 2025 年，攻击者发布了 **454,648 个恶意 npm 包**——仅在一年内就达到了近五十万（Sonatype，2026） - 在 npm、PyPI 和 Maven Central 中，新增恶意包同比增长了 **188%**，总数超过 845,000 个（Sonatype，2026） - 一个普通的 npm 项目平均会引入 **79 个传递依赖**——一个受损的包可以在几小时内波及整个生态系统 这种模式是一致的：攻击者获取受信任的维护者账户的访问权限，将恶意代码注入到官方发布版中，并通过开发团队每天信任的相同仓库和 CI/CD 流水线进行分发。恶意版本看起来很真实，因为它通过的是真实可靠的渠道。 ### 真实事件时间线 **2025 年 9 月 8 日 — `debug` 和 `chalk` (npm)** 两个下载量最高的 Node.js 库的维护者遭到了逼真的伪造 2FA 重置电子邮件的网络钓鱼攻击。攻击者发布了 `debug`、`chalk` 及其相关 16 个包的恶意版本。这些库每周的下载量高达**数十亿次**。受损版本仅在线存在了约 2 小时——但这已经足以让许多生产构建自动将它们拉取下来。 **2026 年 3 月 24 日 — LiteLLM (PyPI) — TeamPCP 活动** 日下载量达数百万的 Python LLM 代理库 `litellm` 的恶意版本 1.82.7 和 1.182.8 被直接发布到了 PyPI，绕过了该项目正常的基于 GitHub 的发布流程。其有效载荷会窃取云凭证、API 密钥和 CI/CD 密钥。同一 TeamPCP 威胁组织还入侵了 **Checkmarx** 和 **Trivy**——一个专门在 CI 流水线中运行以查找漏洞的安全扫描器——随后它被用作向数千个工作流传递窃取凭证恶意软件的传输机制。 **2026 年 1 月至 3 月 — Glassworm 活动 一项协同恶意软件活动同时瞄准了 **OpenVSX、VS Code Marketplace、npm 和 PyPI**。受损的 React Native npm 包被武器化，利用 Solana 区块链作为命令与控制通道来提供多阶段恶意软件，旨在窃取开发者凭证和加密货币钱包数据。 **2026 年 4 月 21 日至 23 日 — 48 小时内的三次攻击 三个截然不同的供应链攻击活动在单个 48 小时内冲击了 npm、PyPI 和 Docker Hub。`CanisterSprawl` npm 蠕虫通过在受感染机器上搜索 npm 发布令牌并重新发布自身来实现自我传播；如果同时发现了 PyPI 令牌，它甚至会跨越整个生态系统进行跳跃。所有三个活动都有一个共同目标：从开发者环境中窃取 API 密钥、云凭证、SSH 密钥和 CI/CD 令牌。 ### 为什么 AI 编程智能体会让情况变得更糟 AI 智能体（`pip install`、`npm install`）会根据指令执行操作，而不会手动审查它们安装的内容。它们在 CI 环境中高速运行，涉及众多包，且通常拥有访问机密的广泛权限。它们是供应链攻击的理想载体——高吞吐量、低人工监督、拥有凭证访问权限。 ### 为什么防病毒软件是不够的 防病毒软件是事后扫描文件。而 MagiSentry 会在执行前进行拦截。 ## 工作原理 ### 流水线 —— 在每次 `pip install` / `npm install` 时自动运行 每个包都会按顺序通过全部 8 个步骤。任何步骤中的技术故障默认都是非阻塞的（故障安全模式）。一旦检测到**威胁**，则会阻止安装并等待您的确认。 | 步骤 | 名称 | 工具 | |---|---|---| | 1 | 仓库元数据检查 | urllib (stdlib) | | 2 | 已知漏洞检查 | OSV / osv.dev | | 3 | 递归依赖审计 | pip-audit | | 4 | 隔离下载 | pip download / npm pack | | 5 | 哈希信誉检查 | VirusTotal API | | 6 | 文件类型验证 | Magika (Google, 本地) | | 7 | 静态代码分析 | Semgrep (本地, 可选) | | 8 | 模式匹配 | YARA (本地, 可选) | ### 独立扫描器 —— 通过钩子自动触发 | 扫描器 | 工具 | |---|---| | VS Code 扩展扫描 | Open VSX + Marketplace + VT | | Dockerfile 分析 | 本地 | | 完整性检查 | 本地 | 有关命令，请参见[用法](#usage)。 这些扫描器会在您的 AI 智能体运行 `code --install-extension` 或 `docker build` 时自动激活——无需任何手动操作。 ## 支持的 AI 编程工具 MagiSentry 包装了包管理器命令，以便您的 AI 智能体的安装请求会被自动拦截——无需对智能体进行任何更改。 | 工具 | 集成类型 | 开箱即用 | |---|---|---| | **Claude Code** | CLI 包装器 | ✅ | | **Cursor** | 终端命令覆盖 | ✅ | | **Windsurf** | 终端命令覆盖 | ✅ | | **Aider** | 前置命令钩子 | ✅ | | **GitHub Copilot** | 终端命令覆盖 | ✅ | | **Continue.dev** | 终端命令覆盖 | ✅ | | **Cline** | 前置命令钩子 | ✅ | | **Codex CLI** | CLI 包装器 | ✅ | | **Gemini CLI** | CLI 包装器 | ✅ | ### 附加保护 —— 危险命令阻止 MagiSentry 会拦截那些试图在包管理器之外下载并执行有效载荷的 shell 命令。 ### 在所有 AI 工具中可见的警告 MagiSentry 会将结构化的警告输出到 **stderr**，这意味着威胁警报会直接显示在每个受支持的 AI 编程工具的界面中——而不仅仅是在终端里。Claude Code、Cursor、Windsurf、Aider、Continue.dev、Cline 及其他工具都会内联显示 stderr 输出。您的智能体会与您同时看到警告。 ## 安装 **前置条件：** Python 3.8+，Git，Windows / Linux / macOS **快速开始 (PyPI)：** ``` pip install magisentry magisentry-install-hooks ``` ``` # 1. Clone 仓库 git clone https://github.com/monpinero/magisentry.git cd magisentry ``` **Windows** ``` setup_windows.bat setx VT_API_KEY "your_api_key_here" ``` **Linux / WSL** ``` chmod +x setup_linux.sh && ./setup_linux.sh echo 'export VT_API_KEY="your_api_key_here"' >> ~/.bashrc && source ~/.bashrc ``` **macOS** ``` chmod +x setup_mac.sh && ./setup_mac.sh echo 'export VT_API_KEY="your_api_key_here"' >> ~/.zshrc && source ~/.zshrc ``` 安装脚本会安装核心依赖项（`magika`、`pip-audit`），并在您的 PATH 中注册 `magisentry` 命令。 ### 可选附加组件 只需安装您需要的： ``` pip install magisentry[semgrep] # Step 7 — static code analysis (Python 3.10+) pip install magisentry[yara] # Step 8 — pattern matching pip install magisentry[all] # everything ``` ## 用法 ### 包 — pip ``` magisentry pip install requests magisentry pip install "numpy==1.26.4" magisentry pip install -r requirements.txt ``` ### 包 — npm / yarn ``` magisentry npm install lodash magisentry yarn add axios magisentry npm install # scans full package.json ``` ### 本地归档文件 — pip ``` magisentry pip install ./package.whl magisentry pip install ./package.tar.gz ``` 本地归档文件（`.whl`、`.tar.gz`、`.zip`）将通过步骤 3、5、6、7 和 8 进行扫描。本地目录将被跳过。 ### VS Code 扩展 ``` magisentry vscode install publisher.extension-name ``` ### Dockerfile ``` magisentry docker build . ``` ### 一次性审计整个项目 ``` magisentry audit ``` 一次性扫描当前目录中在 `pyproject.toml`、`requirements.txt` 和 `package.json` 中找到的所有依赖项。在提交或部署之前非常有用。 ### 更新 MagiSentry 每次运行时都会检查新版本。当有可用更新时，它会提供一个交互式菜单： ``` [1] Update with full scan (recommended) [2] Update without scan [3] Skip this version [4] Remind me later ``` 选项 [1] 会在安装新版本之前通过完整的流水线对其进行扫描——MagiSentry 在自我更新前会先进行自我检查。 ### 白名单管理 ``` magisentry whitelist list magisentry whitelist add pip:requests magisentry whitelist add npm:lodash magisentry whitelist remove pip:requests ``` ### 完整性检查 ``` magisentry integrity update ``` 在安装后运行此命令一次以初始化完整性清单，并在修改 MagiSentry 自身的源代码后再次运行。该清单按机器存储在本地。 ### 卸载 **选项 1 — 命令行（所有平台）：** ``` magisentry uninstall ``` **选项 2 — 通过安装脚本（所有平台）：** ``` # Windows setup_windows.bat # choose [2] Uninstall # Linux ./setup_linux.sh # choose [2] Uninstall # macOS ./setup_mac.sh # choose [2] Uninstall ``` 这两个选项都会移除 `~/.magisentry/` 配置目录，清理 PATH，并运行 `pip uninstall magisentry`。 ### 可选依赖项 MagiSentry 的可选扫描组件不会被自动移除。要手动卸载它们： ``` pip uninstall semgrep # Step 7 — static code analysis pip uninstall yara-python # Step 8 — pattern matching ``` 核心依赖（magika、pip-audit）是共享组件，会被故意保留。只有在您确定系统上没有其他程序依赖它们时，才手动移除它们： ``` pip uninstall magika pip-audit winotify ``` 当检测到威胁时，终端会显示清晰的报告，并在继续之前等待您的确认： ``` when retry is possible (fail_safe) → [R] Retry [S] Skip [A] Abort when retry is not possible (fail_secure) → [S] Skip [A] Abort ``` 您还可以将包加入白名单以禁止未来的警告： ``` magisentry whitelist add pip:package-name ``` ## 配置与数据 ### 本地数据目录 MagiSentry 将其所有数据存储在一个目录中： ``` ~/.magisentry/ ├── config.json # scanner configuration ├── counters.json # scan statistics └── bin/ # shell wrappers that intercept pip/npm commands ``` 在所有平台上运行 `magisentry uninstall` 会自动移除此目录。 ### 故障安全与故障防御 MagiSentry 默认以**故障安全**模式运行。您可以在 `config.json` 中更改此项： | 模式 | 工具错误时的行为 | |---|---| | `fail_safe`（默认） | 如果扫描步骤崩溃或超时，安装继续进行 | | `fail_secure` | 如果任何扫描步骤因任何原因失败，则阻止安装 | ``` { "mode": "fail_safe", "steps": { "registry_check": true, "osv_check": true, "pip_audit": true, "isolated_download": true, "virustotal": true, "magika": true, "semgrep": false, "yara": false, "vscode_scan": true, "dockerfile_scan": true } } ``` 将任何步骤设置为 `false` 以完全跳过它。步骤 7 和 8 默认禁用——请在安装相应的附加组件后启用它们。 ## MagiSentry 检测内容 ## 隐私 MagiSentry 旨在最大程度减少云数据暴露： - **VirusTotal（步骤 5，VS Code 扫描）：** 仅发送 **64 位 SHA-256 哈希**——从不发送文件本身。 - **OSV（步骤 2）：** 仅发送包名和版本号。 - **PyPI / npm / VS Code Marketplace（步骤 1，VS Code 扫描）：** 仅查询包或扩展名——与正常安装相同。 - **步骤 4、6、7、8**（Magika、Semgrep、YARA）：完全在**您的机器上离线运行**。无任何数据流出。 ## 工具成本摘要 | 工具 | 免费？ | 需要 API 密钥？ | 离线？ | |---|---|---|---| | PyPI / npm API | 始终免费 | 否 | 否 | | OSV (Google) | 始终免费 | 否 | 否 | | pip-audit | 始终免费 | 否 | 否 | | pip download / npm pack | 始终免费 | 否 | 否 | | VirusTotal | 免费（500次/天） | 是 — 免费注册 | | | Magika (Google) | 始终免费 | 否 | **是** | | Semgrep | 免费（基础版） | 否 | **是** | | YARA | 始终免费 | 否 | **是** | | VS Code Marketplace API | 始终免费 | 否 | 否 | | Dockerfile 分析 | 始终免费 | 否 | **是** | ## 许可证 MIT — 详见[许可证](https://github.com/monpinero/MagiSentry/blob/main/LICENSE)。 ## 支持本项目 如果 MagiSentry 在恶意内容造成破坏之前帮您拦截了它，请考虑支持本项目： [](https://ko-fi.com/monpinero) XMR: `48W5FXBSBecjG6ApZH5KEtYMKZxiGVkJhdbCjXWGj9Ahe6R58LpZvhqSWHoftZCAgWKDez3HQ3teAD8mEUEPHYhnHT6SusB` *MagiSentry —— 因为您的 AI 智能体值得配备一名安全卫士。*

标签：AI安全, AI编程助手, Chat Copilot, CISA项目, DevSecOps, Dockerfile扫描, npm安全, pip安全, VS Code扩展安全, 上游代理, 云安全监控, 加密, 包管理器安全, 命令与控制防御, 安全专业人员, 安全防护工具, 漏洞扫描器, 逆向工具, 静态代码扫描, 静态分析