vrajbhai/SupplyScan

## title: SupplyScan Backend emoji: 🛡️ colorFrom: green colorTo: green sdk: docker app_port: 7860 pinned: false # 🛡️ SupplyScan SupplyScan 是一个**自主的供应链安全 agent**，旨在保护开发者环境免受恶意软件包的侵害。它会拦截 Python 和 npm 软件包的安装请求，通过多层静态分析 pipeline 对其进行评估，并利用先进的 AI 模型将可疑代码模式转化为通俗易懂的安全威胁说明。

## ✨ 功能 * **⚡ 自动 Shell 拦截：** 无缝接入 `pip` 和 `npm install`，在软件包于你的计算机上运行代码之前进行审查。 * **🔍 多层静态审计：** 使用 AST 解析、自定义 YARA 特征、Semgrep 安全规则和元数据启发式算法来发现恶意模式。 * **🧠 双 AI 威胁解释器：** 使用 Anthropic Claude 或 OpenCode.ai 模型，将令人困惑的编译器信号转化为高优先级的安全警告。 * **📊 集成仪表盘：** 基于本地 Next.js 构建的可视化界面，用于追踪你的项目指标、扫描日志和威胁严重性随时间的变化。 * **📴 离线韧性：** 在未配置 AI 密钥时，可以使用确定性的后备机制完全离线运行。 ## 🏗️ 架构 SupplyScan 采用去中心化、agent 驱动的流程运行，在此流程中，包管理器会在完成执行之前将扫描任务委托给核心引擎。 ``` graph TD A[Package Install Trigger] --> B(SupplyScan Engine) B --> C[Detection Pipeline] subgraph Detection Pipeline C1[Typosquatting Check] C2[AST Code Parsing] C3[YARA Signature Audit] C4[Semgrep Security Rules] end C --> C1 C --> C2 C --> C3 C --> C4 C1 --> D{risky signals found?} C2 --> D C3 --> D C4 --> D D -- No --> E[Mark Clean / Allow Install] D -- Yes --> F[AI Explainer Router] subgraph Explainer Router F1[Claude API] F2[OpenCode.ai API] F3[Deterministic Fallback] end F --> F1 F --> F2 F --> F3 F1 --> H[Aggregate Severity & Context] F2 --> H F3 --> H H --> I[Block Install & Notify OS] H --> J[Persist to SQLite Store] E --> J J --> K[FastAPI + Next.js Dashboard] ``` ## 🚀 快速开始 只需三个步骤即可在本地启动并运行 SupplyScan： ### 1. 安装 设置虚拟环境并安装依赖项： ``` # Clone the repository git clone https://github.com/vrajbhai/SupplyScan.git cd SupplyScan # Set up virtual environment python -m venv .venv source .venv/bin/activate # macOS/Linux .venv\Scripts\Activate.ps1 # Windows # Install packages pip install -r requirements.txt pip install -e . ``` ### 2. 配置你的 AI 密钥 SupplyScan 会按以下顺序检查 API 密钥：`CLAUDE_API_KEY` ➡️ `OPENCODE_API_KEY`。你可以在终端会话中设置它们，或者在项目根目录下创建一个 `config.env` 文件： ``` OPENCODE_API_KEY=sk-dLdOoWWtkXhb50seQs5729EfZ9USMFj3WQ8ubFnqGpA4ZkqsKUHEYzOAVGgdOUSD ``` ### 3. 运行工具 * **初始化 Hook：** 拦截全局安装。 supplyscan init * **运行扫描：** 分析特定的软件包。 supplyscan check requests * **启动仪表盘：** 打开可视化的 Web 控制面板（默认地址为 `http://127.0.0.1:8000`）。 supplyscan dashboard ## 🛠️ CLI 参考 SupplyScan 的命令行界面由 `click` 驱动，并使用 `rich` 进行格式化： | 命令 | 用法 | 描述 | | --- | --- | --- | | `init` | `supplyscan init` | 为 `pip` 和 `npm` 注册环境 hook。 | | `check` | `supplyscan check [--version ]` | 审计特定版本的软件包。如果被阻止拦截，则返回状态码 `1`。 | | `check -r` | `supplyscan check -r requirements.txt` | 批量扫描 Python 依赖文件。 | | `history` | `supplyscan history` | 在终端中直接渲染并展示历史扫描记录表。 | | `dashboard` | `supplyscan dashboard [--port

]` | 启动 FastAPI 后端和 Web 服务器。 | | `remove-hooks`| `supplyscan remove-hooks` | 注销包管理器拦截器。 | ## ⚙️ 环境变量 使用系统变量自定义扫描器的行为： * `OPENCODE_API_KEY`：用于免费层级说明的密钥。 * `CLAUDE_API_KEY`：用于高级 Claude 模型的密钥（如果存在则优先使用）。 * `OPENCODE_MODEL`：覆盖默认的 OpenCode 模型（默认：`north-mini-code-free`）。 * `PYTHONUTF8`：在 Windows 系统上设置为 `1` 以强制控制台输出 UTF-8 编码。 ## 🔒 安全最佳实践 * **人类参与（Human-in-the-Loop）：** SupplyScan 充当了一个高保真过滤器。在覆盖拦截操作之前，请务必在仪表盘中查看原始的发现结果和信号。 * **缓存与版本锁定：** 在 `requirements.txt` 和包锁文件中固定你的依赖版本，以防止生产环境的 pipeline 中出现依赖混淆攻击。 ## 🧪 测试 我们使用位于 `tests/malicious/` 下的人造恶意软件包运行严格的单元测试，以验证扫描器的准确性： ``` pytest -q ``` ## 📄 许可证 本项目采用 MIT 许可证授权。请负责任地使用。

标签：AI大模型, DNS 反向解析, Python, TLS, 域名收集, 无后门, 请求拦截, 软件供应链安全, 远程方法调用, 配置审计, 错误基检测, 防御工具, 静态代码分析