khan-ARK/cybergraph

# CyberGraph 由知识图谱驱动的代码库安全审查工具。 CyberGraph 将代码仓库映射为网络安全知识图谱，开发者无需手动阅读整个代码库，即可检查安全层、高风险代码路径、扫描器发现以及有据可查的回答。 ## 开发初衷 安全扫描器虽然实用，但其输出通常是扁平化的：一个文件、一行代码、一条规则和一个警告。开发者仍需自行解答那些棘手的问题： - 生产环境代码是否可触发此问题？ - 在此敏感操作之前是否设有身份验证？ - 此 Pull Request 是否影响了安全边界？ - 哪些扫描器发现最需优先处理？ CyberGraph 正是为了将这些线索串联起来而设计的。 ## 当前功能 - 在 `.cybergraph/graph.db` 中构建本地 SQLite 图谱。 - 分析**五种语言**：Python (FastAPI/Flask/Django)、JavaScript/TypeScript (Express/Next.js)、Go (net/http, Gin, Echo)、Java (Spring) 和 C# (ASP.NET Core) —— 通过共享的分析器契约实现，对未覆盖的语言提供平滑降级处理。 - 提取函数、调用、路由入口点、认证/授权守卫、验证器、用户输入/数据流边、机密访问/泄露、云资源以及敏感 sink 调用。 - **跨文件、过程间的攻击路径**（路由 → 服务 → 数据层 → sink），包含置信度、净化器拦截标志、污点/数据可达性、风险评分和修复指南；`--shallow` 模式可复现函数内遍历以便进行对比。 - **专为初次使用者构建的交互式离线 HTML 报告**：深色模式优先的霓虹图谱浏览器（发光、安全类型化的节点，支持明暗主题切换）、NODE/EDGE/ZONE 说明卡、首次打开即引导至顶级攻击路径的向导视图（附带通俗易懂的叙述）、安全区域视图（攻击面 → 守卫 → 逻辑 → 敏感 Sinks）、搜索、层级/严重程度过滤器、带源码下钻功能的详情面板，以及入口点→sink 路径高亮（完全内联的 Cytoscape.js）。 - **执行优先的报告布局**：包含 A-F 安全评级及一行结论与严重程度分布条、自上次扫描以来的差异条（新增/倒退/已修复）、按可展开规则卡分组的发现项、如实声明的发现上限页脚，以及适配整洁 PDF 导出的打印样式表。 - **有据可查的回答**（`cybergraph explain`），附带文件/行号/规则/路径引用、攻击路径叙述、修复指南以及高/中/低/证据不足的置信度级别 —— 绝不在缺乏支持证据的情况下断言漏洞，且无需 LLM 即可工作。 - 通过可配置的提供商（Anthropic Claude、OpenAI、Kimi 2.6）提供可选的、**默认完全本地运行**的 LLM 措辞润色，且严格限制在检索到的证据范围内。 - 映射 npm、Python、Go、Maven/Gradle 和 .NET 生态系统中的依赖清单与锁文件。 - 将 OSV Scanner、npm audit、Semgrep JSON、SARIF 和 Gitleaks 报告导入同一图谱；利用离线的 EPSS/KEV/CVSS/公告 JSON 丰富漏洞信息；以 SARIF 格式导出发现结果。 - 将 Terraform 资源与应用程序代码引用相关联，从而将公有云暴露面与可达路由、sink 及依赖风险连接起来。 - 为 AI 编程助手提供 MCP 工具。 ## 安装说明 ``` # 从 PyPI 安装（一旦发布）： pipx install cybergraph # isolated CLI install python -m pip install cybergraph # or into the current environment # 可选 extras： python -m pip install "cybergraph[mcp]" # MCP server for AI assistants python -m pip install "cybergraph[llm]" # Anthropic / OpenAI / Kimi providers python -m pip install "cybergraph[all]" # everything optional # 从 clone 安装（开发）： python -m pip install -e ".[dev]" ``` 支持的 Python 版本：3.10、3.11、3.12、3.13。 ## 快速开始 ``` cybergraph quickstart . # zero-to-report: init, build, analyze, open report cybergraph init . cybergraph doctor . cybergraph analyze . # build + run every analysis, print top risks cybergraph history . # what's new / fixed / regressed since the last scan cybergraph config show . # inspect effective config + LLM/graph state cybergraph build path/to/repo cybergraph ask "Which functions reach SQL execution?" --repo path/to/repo cybergraph explain "Which routes reach SQL execution?" --repo path/to/repo cybergraph paths --repo path/to/repo cybergraph layers --repo path/to/repo cybergraph secrets path/to/repo cybergraph cloud-code path/to/repo cybergraph top-risks path/to/repo cybergraph scan path/to/repo # lightweight built-in analyzers, no graph needed cybergraph triage path/to/repo # rank findings; --llm suppresses false positives cybergraph sca path/to/repo # prioritize dependency CVEs by reachability cybergraph infer-specs path/to/repo # propose custom taint sinks/sources cybergraph iac-paths path/to/repo # public exposure -> privileged IaC resource cybergraph investigate path/to/repo --output investigation.md cybergraph strix-plan path/to/repo --output strix-plan.md cybergraph import-strix strix_runs/ --repo path/to/repo cybergraph export-json path/to/repo --output graph.json cybergraph opengraph path/to/repo --output opengraph.json # BloodHound OpenGraph interop cybergraph review --base main --repo path/to/repo cybergraph pr-comment --base main --repo path/to/repo --output cybergraph-pr-comment.md cybergraph visualize path/to/repo cybergraph sarif --repo path/to/repo --output cybergraph.sarif ``` 典型的构建输出： ``` Built security graph for examples/vulnerable-fastapi Nodes: 15 | Edges: 28 | Findings: 1 ``` 典型的 PR 评论文本： ``` Risk: medium What Changed: CyberGraph detected 2 entrypoints, 1 sensitive sink edge, 1 finding in changed files. What To Check Next: Confirm changed entrypoints require authentication or authorization when needed. ``` 导入扫描器结果： ``` cybergraph import-report semgrep.json --repo path/to/repo cybergraph import-vulns osv-results.json --repo path/to/repo cybergraph enrich-vulns advisory-intel.json --repo path/to/repo cybergraph ask "Which high severity findings involve secrets?" --repo path/to/repo ``` 使用 AI 渗透测试工具 ([Strix](https://github.com/usestrix/strix)) 验证可达风险： ``` # 1. 将 CyberGraph 的可达路径转化为聚焦的 Strix scope brief cybergraph strix-plan path/to/repo --output strix-plan.md # 2. 自己针对该 brief 运行 Strix（需要 Docker + 一个 LLM key）： # strix -n -t path/to/repo -m quick --instruction-file strix-plan.md # ...或者让 CyberGraph 进行 end-to-end 编排（可选，opt-in）： cybergraph strix-run path/to/repo --scan-mode quick # 3. 将 Strix 经 PoC 验证的 findings 导回 graph cybergraph import-strix strix_runs/ --repo path/to/repo cybergraph top-risks path/to/repo # validated findings rank at the top ``` CyberGraph 告诉 Strix *从哪里*发起攻击（可达路由与 sink），而 Strix 告诉 CyberGraph *什么是真正可利用的漏洞*（通过有效的 PoC 进行验证）。 Strix 绝不是必需的依赖项 —— `strix-run` 桥接器只会在 同时存在 `strix` 二进制文件和 Docker 时激活，因此默认离线的工作流程 保持不变。 隐藏已接受的发现项： ``` def test_fixture(): # cybergraph: ignore CG-SINK-CALL accepted test-only query return db.execute("select 1") ``` 或配置仓库级别的隐藏规则： ``` [suppressions] rules = ["CG-SINK-CALL"] paths = ["legacy/**"] ``` 隐藏功能会从视图中移除发现项，但图谱中仍会保留如 `REACHES_SINK` 等边，以便审查者检查真实的代码路径。 ## 示例问题 ``` Which endpoints can reach SQL execution? What changed in this PR that affects authentication? Where are secrets loaded and passed into network clients? Which vulnerable dependency is reachable from production code? Are there route handlers that reach shell or file writes? ``` ## 体验演示 ``` cybergraph build examples/vulnerable-fastapi cybergraph ask "Which routes reach SQL execution?" --repo examples/vulnerable-fastapi cybergraph visualize examples/vulnerable-fastapi --output cybergraph-report.html ``` ## MCP 工具 安装可选的 MCP 扩展并运行服务器： ``` python -m pip install -e ".[mcp]" cybergraph-mcp ``` 可用工具： - `build_security_graph_tool` - `query_security_graph_tool` - `explain_attack_path_tool` - `grounded_security_answer_tool`（带引用、置信度评分、仅限本地） - `analyze_repo_tool`（通过一次调用完成构建与全面分析） - `top_risks_tool` - `secret_exposures_tool` - `prioritize_dependencies_tool`（基于可达性排序的 SCA） - `iac_attack_paths_tool` - `import_scanner_report_tool` - `import_vulnerabilities_tool` ## 项目方向 CyberGraph 刻意采用安全优先的设计策略。它并非试图成为一个在表面堆砌安全关键字的一般性代码图谱，而是致力于将控制措施、攻击路径、信任边界、扫描器发现和代码证据建模为统一的图谱结构。 参见： - [架构](docs/architecture.md) - [入门指南](docs/getting-started.md) - [五分钟教程](docs/tutorial.md) - [安全本体论](docs/security-ontology.md) - [产品规划](docs/product-plan.md) - [GitHub Action](docs/github-action.md) ## 状态 Beta 阶段。CyberGraph 支持分析五种语言，构建过程间攻击路径，导入并丰富扫描器发现，将 IaC 与代码关联，提供交互式 HTML 报告，并为 AI 助手开放 MCP 接口。图存储、分析器、证据检索和报告功能现已稳定；但在 1.0 版本发布之前，公开 API 和发现规则可能仍会发生变动。

标签：逆向工具