anubhavmohandas/SAGE

# SAGE — 安全分析与 Graph Engine SAGE 是一个自主的安全 pipeline，它可以扫描代码仓库，将其结构映射为交互式的知识图谱，查找影响技术栈的 CVE，通过 AI 确认可利用性，生成补丁，并提交 GitHub PR —— 所有这些只需一条命令即可完成。 ``` python3 main.py --repo /path/to/your/repo ``` ## 🌐 在线演示 [**→ Synapse 可视化**](./Media/Security_graph_diagram_animation_202606060821.mp4) ## SAGE 的独特之处 大多数安全工具的回答是：*"库 X 存在 CVE-Y。"* SAGE 的回答是：*"`cybertrace/modules/base.py` 中的 `fetch_json()` 函数调用了 `aiohttp`，而它存在 18 个 CVE —— 这是其影响范围（blast radius），这是修复补丁。"* 可达性分析会追踪从入口点到易受攻击库的调用路径（目前已支持同文件内的调用链解析；跨文件解析已列入路线图），并将这些路径作为可利用性上下文提供给分析器。 图谱就是代码库。CVE 是图谱中现有节点上的徽章。 ## 流水线 ``` Repo │ ├─ 1. STACK DETECT — reads requirements.txt / package.json / pyproject.toml / Pipfile ├─ 2. CVE FETCH — pulls analysed CVEs from NVD (lastModified window) ├─ 3. CVE FILTER — matches NVD CPE strings against your stack ├─ 4. SYNAPSE PARSE — tree-sitter AST → files + functions + imports graph ├─ 5. CVE OVERLAY — attaches CVE nodes to library nodes in the graph ├─ 6. GRAPH EXPORT — synapse_graph.json + index.html (self-contained viz) ├─ 7. SCANNER — semgrep on blast-radius files only (45 CWEs, 30 library packs) ├─ 8. ANALYZER — LLM confirms exploitability (CRITICAL→Opus, others→Sonnet) ├─ 9. PATCHER — dep bump + code patch generation ├─ 10. TESTS — runs existing test suite, detects pre-existing baseline failures ├─ 11. VERIFIER — final semgrep pass post-patch └─ 12. GITHUB PR — timestamped branch + PR with full CVE table ``` ## Synapse — 知识图谱 图谱从仓库根节点打开，并允许您逐层下钻： ``` repo (purple) └─ file: cybertrace/modules/base.py ├─ function: fetch_json() ──USES──► lib: aiohttp ├─ function: _create_session() └─► CVE-2026-34520 [CRITICAL] └─ lib: aiohttp ──────────────────────► CVE-2025-69223 [HIGH] ► CVE-2025-69224 [MEDIUM] ► ... 16 more ``` **节点类型：** | 颜色 | 类型 | 含义 | |---|---|---| | 🟣 紫色 | REPO | 仓库根节点 —— 入口点 | | 🔵 蓝色 | FILE | 源代码文件 | | 🟢 绿色 | FUNCTION | 函数/方法定义 | | 🟠 橙色 | LIBRARY | 第三方依赖 | | 🔴 红色 | CVE | 漏洞 —— 大小代表严重程度 | **交互方式：** - 点击任意节点进行深入查看 - 悬停在 CVE 上 → 攻击路径会以红色线条回溯到入口点 - 按 `ESC` / `←` 返回，按 `R` 重置，按 `S` 保存 PNG 图片，滚动鼠标滚轮进行缩放 - 支持明亮/暗黑模式切换，悬停时显示边的关系标签 ## 设置 ``` git clone https://github.com/anubhavmohandas/SAGE cd SAGE python3 -m venv venv && source venv/bin/activate pip install -r requirements.txt cp .env.example .env # add your API keys ``` **.env 配置项 (keys)：** ``` NVD_API_KEY= # https://nvd.nist.gov/developers/request-an-api-key ANTHROPIC_API_KEY= # https://console.anthropic.com GEMINI_API_KEY= # optional — used as primary analyzer, Anthropic as fallback GITHUB_TOKEN= # repo:write scope (Contents + Pull requests) GITHUB_REPO= # owner/repo ``` ## 使用方法 运行 SAGE 最简单的方法是使用交互式启动器 —— 它会自动检测您的 GitHub 远程仓库，询问要扫描的仓库，并让您选择 CVE 的时间窗口： ``` bash sage_scan.sh # interactive — asks for repo path bash sage_scan.sh /path/to/repo # skip the path prompt bash sage_scan.sh /path/to/repo --days 30 # pass extra flags to main.py ``` 或者直接调用 `main.py` 进行脚本化执行： ``` # 完整 pipeline python3 main.py --repo /path/to/repo # 更宽的 CVE 窗口（默认为 1 天） python3 main.py --repo /path/to/repo --days 30 # 仅 Knowledge graph — 无 CVE 获取 python3 main.py --synapse /path/to/repo # 查找特定 CVE python3 main.py --cve CVE-2026-34520 # Pipeline 状态 python3 main.py --status ``` 图谱始终会写入到 `demos/_/index.html` 文件中。您可以在任何浏览器中打开它 —— 无需服务器。 ## 分析器 — 双模式 SAGE 支持在提供或不提供 API 密钥的情况下工作。 **API 模式** —— 使用 Gemini 2.0 Flash（免费层级，15 RPM）作为带有指数退避机制的主要分析器。如果 Gemini 配额耗尽，则回退到 Anthropic。 **手动模式** —— 无需 API 密钥，并且该选择适用于**整个流水线**（分析器、补丁生成器和安全测试生成器）。SAGE 会为每个步骤导出提示词文件 —— 分析（`data//prompts/`）、补丁（`data//patches/patch_prompt_*.txt`）和测试（`data//tests/test_prompt_*.txt`）。将每个文件内容粘贴到任何 LLM 中，并将回复保存在该文件旁边，流水线就会继续执行。手动模式永远不会调用 API，因此永远不会消耗额度或触及配额限制。 手动回复 schema： ``` { "vulnerable": true, "confidence": 0.85, "reason": "...", "affected_functions": ["fetch_data", "_create_session"], "attack_vector": "...", "recommendation": "..." } ``` ## 基于严重程度的模型选择 | 严重程度 | 模型 | 理由 | |---|---|---| | 严重 (CRITICAL) | `claude-opus-4-6` | 风险最高 —— 提供最佳分析 | | 高 (HIGH) | `claude-sonnet-4-6` | 能力强劲，成本低 5 倍 | | 中 (MEDIUM) | `claude-sonnet-4-6` | 快速分类筛选 | | 低 (LOW) | `claude-sonnet-4-6` | 最低成本 | ## 补丁策略 | 场景 | 操作 | |---|---| | 存在已知安全版本的 CVE，且无可确认的易受攻击代码 | 仅升级依赖 —— 将 `requirements.txt` 升级为 `>=safe_version` | | 被 LLM 确认可利用的 CVE | 代码补丁（API 模式下使用 Claude Sonnet，或手动模式下使用手动提示词）+ 依赖升级。补丁将写入 `data//patches/CVE-XXXX/` | | requirements 中包含 `pkg[extras]`（例如 `aiohttp[speedups]`） | 保留 extras —— 使用正则表达式分别提取基础名称和 extras | ## 测试、验证与 PR 门禁 应用补丁后，SAGE 会运行仓库现有的测试，并为每个确认的 CVE 生成一个**安全测试**。为了在不同的 Python 版本中保持可靠性，并避免产生幻觉的库 API，生成的安全测试会断言**已安装修补后的依赖版本**，而不是重构漏洞利用过程。（这证明了上游修复已生效 —— 这是针对依赖项 CVE 的恰当检查。它不会重现漏洞利用过程。） 除非*同时*满足以下两个条件，否则 PR 将以**草稿**形式开启：现有测试和安全测试均通过，**并且**每个确认的 CVE 都实际生成了补丁。如果补丁生成失败或测试未通过，SAGE 会强制将其设为草稿，并说明原因 —— 它绝不会将空的或未经验证的补丁作为可直接合并的 PR 提交。 ## ⚠️ 安全提示：SAGE 会执行被扫描仓库的代码 为了验证补丁，SAGE 会安装被扫描仓库的依赖项（`pip` 会运行构建钩子）并在主机上运行其测试。因此，恶意或被篡改的目标仓库可能会在您的机器上执行代码。SAGE 在启动这些子进程时会**从环境变量中清除**其自身的 API 密钥/token，因此被扫描的代码无法读取您的机密信息 —— 但这只是一道防线，而非沙盒。 - **您自己的 / 受信任的仓库** → 可以在您的正常机器上运行。 - **不受信任的 / 第三方仓库** → 请在一次性虚拟机或容器中运行 SAGE。（完整的沙盒隔离已在路线图中。） 请使用范围限定在目标仓库（Contents + Pull requests）的**细粒度** GitHub token，切勿使用经典的具有完整 `repo` 权限的 PAT。 ## 架构 ``` sage/ ├── fetcher/ │ ├── nvd.py NVD API client — paginated, rate-limited, lastModDate window │ ├── filter.py Stack detection + CPE matching + alias table (30+ packages) │ └── store.py SQLite CVE store — dedup, CWE storage, pipeline status ├── synapse/ │ ├── parser.py tree-sitter AST — files, functions, imports, calls + regex fallback │ ├── mapper.py CVE overlay — blast radius trace, AFFECTS edges │ └── export.py Graph serialisation + self-contained index.html generation ├── scanner/ │ └── semgrep.py 45 CWEs mapped, 30 library-specific rule packs ├── analyzer/ │ └── llm.py Exploitability confirmation — dual mode, severity-gated models ├── patcher/ │ └── llm.py Dep bump + code patch + diff + manifest ├── tests/ │ └── runner.py Existing test suite runner — baseline failure detection ├── verifier/ │ └── semgrep.py Post-patch semgrep pass + dep bump validation └── github/ └── pr.py Timestamped branch + PR creation, CVE table in body ``` ## Semgrep 覆盖范围 **涵盖 10 个类别的 45 种 CWE：** | 类别 | CWEs | |---|---| | 注入 | CWE-89, 79, 78, 77, 88, 94, 95, 96, 643 | | 路径 / 文件 | CWE-22, 23, 36, 434, 73 | | 加密 / 机密 | CWE-327, 326, 330, 331, 312, 319, 798, 259 | | 认证 / 访问控制 | CWE-284, 285, 287, 306, 307, 384, 613 | | 反序列化 | CWE-502, 119, 125, 787 | | 网络 / SSRF | CWE-918, 611, 601, 295 | | 拒绝服务 / 资源 | CWE-400, 770, 776, 835 | | 信息泄露 | CWE-200, 209, 532, 779 | | Header / 协议 | CWE-113, 444, 116 | | 输入验证 | CWE-20, 74, 409 | **30 个特定库的规则包**，涵盖：aiohttp、flask、django、fastapi、requests、httpx、sqlalchemy、pymongo、jwt、cryptography、pyyaml、pickle、jinja2、subprocess 等。 ## CVE 匹配 SAGE 使用 NVD 的 `lastModified` 时间窗口（而非 `publishedDate`），因此它能捕获最近被分析过的 CVE —— NVD 只在分析后才会添加 CPE 数据，这可能会在发布几天后才进行。未被分析的 CVE（`Received`、`Awaiting Analysis`）将被跳过。 包名规范化处理了 NVD 不一致的 CPE 命名： ``` "anthropic-sdk" → matches "anthropic" "python-requests" → matches "requests" "aio_libs_aiohttp" → matches "aiohttp" ``` ## 测试基线检测 许多仓库都存在与 SAGE 补丁无关的既有测试失败。天真的门禁机制会永久阻碍安全 PR 的提交。 SAGE 会在打补丁前检测基线失败，并将它们排除在门禁之外。只有*SAGE 引入的*失败才会阻止 PR。 | 场景 | SAGE 的操作 | |---|---| | 49 个通过，1 个既有失败 | 检测到基线 → 覆盖为 PASSED（通过） → 不阻止 PR | | 49 个通过，1 个由补丁引起的新失败 | 出现新失败 → 阻止 PR → 人工审查 | | 无测试套件 | 标记为 PASSED（无测试 ≠ 失败） → 提交 PR | ## 验证 — CyberTrace SAGE 已经扫描过自身以及 [CyberTrace](https://github.com/anubhavmohandas/CyberTrace)。端到端输出示例： ``` Stack detected: aiohttp, click, rich, dnspython, phonenumbers, python-dotenv, python-whois CVEs found: 33 total from NVD, 24 attached to graph CRITICAL×3 HIGH×9 MEDIUM×12 Semgrep: 0 findings (correct — client-only CLI, no server-side exposure) Confirmed: 0/24 exploitable (note: this run predates the reachability engine fix — analysis was based on Semgrep + code context only; re-validation with live reachability paths pending) Dep bump: aiohttp >=3.9.0 → >=3.13.3 (18 CVEs) click >=8.0.0 → >=8.3.3 (1 CVE) Tests: 49 passed, 1 pre-existing failure (baseline detected, PR not blocked) Verifier: PASSED GitHub PR: https://github.com/anubhavmohandas/CyberTrace/pull/1 ``` ## 路线图 **近期** - [ ] **每日早报** —— 定时每日扫描，终端结果摘要，可选的 Slack/电子邮件提醒。每天集中处理一次决策，而非实时的信息轰炸。 - [ ] **吃自己的狗粮** —— SAGE 扫描 SAGE。当依赖过时时会向自己的仓库提交 PR。使用自己开发的产品。 - [ ] **JS/TS 支持** —— `package.json` + `npm audit` CVE 映射。`filter.py` 中已有 `_parse_package_json` 作为存根。 - [ ] **CVE 差异比对** —— 仅对上次扫描以来新出现的 CVE 发出警报。消除重复运行时的重复噪音。 **中期** - [ ] **多仓库** —— 扫描整个 GitHub 组织（org），跨仓库的统一知识图谱，跨仓库的影响范围。 - [ ] **Go + Rust 支持** —— `go.mod` / `Cargo.toml` 技术栈检测，特定语言的 tree-sitter 语法。 - [ ] **仪表板 + 提醒** —— 每个仓库的可视化 CVE 状态，针对 CRITICAL 发现的基于严重程度的 Slack/电子邮件提醒，完整的审计日志。 - [ ] **Synapse 可视化优化** —— 可调的 `max_neighbours`，更深的下钻深度控制，节点固定，时间线视图。 **长期** - [ ] **NYX 集成** —— 在 NYX 的第三阶段将作为 `nyx/tools/osint/sage/` 发布。SAGE 将成为更广泛的自主安全流水线的静态分析和漏洞情报模块。 - [ ] **传递依赖遍历** —— 跟踪间接依赖，而不仅仅是直接需求。展现两层深度的 CVE。 - [ ] **导出 SBOM** —— 从 Synapse 图谱生成 CycloneDX / SPDX 软件物料清单（SBOM）。 - [ ] **IDE 插件** —— VS Code 扩展，可在编辑器中内联渲染 Synapse 图谱并高亮显示易受攻击的调用链。 ## 技术栈 - [tree-sitter](https://tree-sitter.github.io) — 跨语言的 AST 解析 - [NetworkX](https://networkx.org) — 图谱构建与遍历 - [Semgrep](https://semgrep.dev) — 静态分析，映射 CWE 的规则 - [NVD API](https://nvd.nist.gov/developers/vulnerabilities) — CVE 数据 - [Anthropic Claude](https://anthropic.com) — 可利用性分析和补丁生成 - [Google Gemini](https://ai.google.dev) — 主要分析器（免费层级） - Canvas API — Synapse 可视化使用纯原生 JS 实现，零依赖 *SAGE v2.0 — 全部 12 个流水线阶段已完成。首个真实 PR 已提交至 CyberTrace。🛡️*

标签：CISA项目, DLL 劫持, GPT, 后端开发, 大语言模型, 模块化设计, 漏洞管理, 自动化修复, 逆向工具, 错误基检测, 静态代码分析