cybergraph

# CyberGraph 代码库的安全审查，由知识图谱提供支持。 CyberGraph 将代码仓库映射到网络安全知识图谱中，以便开发人员可以检查安全层、风险代码路径、扫描器发现和有证据支持的答案，而无需手动阅读整个代码库。 > **🔒 无需 API 密钥。完全离线。您的代码永远不会离开您的机器。** > `pip install cybergraph`，您将获得完整的工具包 — 交互式 HTML 报告、攻击路径图、引用的发现和 SARIF 导出 — **无需任何 API 密钥，无需注册，无需网络调用**。没有运行时依赖。大型语言模型（LLM）是完全可选的，仅重新措辞图谱中已经有证据支持的答案；分析不需要 LLM。 ## 为什么存在 安全扫描器非常有用，但它们的输出通常是平面的：一个文件，一行代码，一个规则和一个警告。开发人员仍然需要回答一些难题： - 这个问题是否可以从生产代码中访问？ - 在此敏感操作之前是否有身份验证？ - 这个拉取请求是否影响了安全边界？ - 哪些扫描器发现最重要？ 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）— 通过共享的分析器合约，对于其他语言则优雅地回退。 - 提取函数、调用、路由入口点、身份验证/授权守卫、验证器、用户输入/数据流边、机密访问/暴露、云资源和敏感汇聚调用。 - **跨文件、过程间攻击路径**（路由 → 服务 → 仓库 → 汇聚）具有置信度、净化器屏障标志、污染/可达性、风险评分和修复指导；`--shallow` 模式再现函数内遍历以进行比较。 - **交互式、离线 HTML 报告**，为首次阅读人员构建：暗黑模式优先的霓虹图浏览器（发光的、具有安全类型的节点，带有灯/暗切换）、节点/边/区域解释卡、引导式第一视图，打开顶部攻击路径，带有纯语言叙述、安全区域视图（攻击面 → 守卫 → 逻辑 → 敏感汇聚）、搜索、层/严重性过滤器、带有源钻取的详细信息面板和入口点 → 汇聚路径高亮（Cytoscape.js，完全内联）。 - **执行优先的报告姿态**：A-F 安全等级，具有一行判决和严重性分布条、最近一次扫描的增量条（新的/回归的/固定的）、分组为可展开的规则卡的发现、诚实的发现能力页脚和用于干净 PDF 导出的打印样式表。 - **有证据支持的答案**（`cybergraph explain`）具有文件/行/规则/路径引用、攻击路径叙述、修复指导和高/中/低/不足置信度级别 — 永远不会在没有支持证据的情况下声称漏洞，并且无需 LLM。 - 可选的、**默认本地**的大型语言模型（LLM）措辞，通过可配置的提供商（Anthropic Claude、OpenAI、Kimi 2.6）约束为检索的证据。 - 映射 npm、Python、Go、Maven/Gradle 和 .NET 生态系统中的依赖关系清单和锁定文件。 - 将 OSV 扫描器、npm 审计、Semgrep JSON、SARIF 和 Gitleaks 报告导入同一图谱；从离线 EPSS/KEV/CVSS/咨询 JSON 中丰富漏洞；将发现导出为 SARIF。 - 将 Terraform 资源与应用程序代码引用相关联，以便可以将公共云暴露与可达路由、汇聚和依赖风险联系起来。 - 为 AI 编码助手公开 MCP 工具。 ## 安装 ```bash # 从 PyPI（发布后）： pipx install cybergraph # 隔离的 CLI 安装 python -m pip install cybergraph # 或安装到当前环境 # 可选额外功能： python -m pip install "cybergraph[mcp]" # AI 助手的 MCP 服务器 python -m pip install "cybergraph[llm]" # Anthropic / OpenAI / Kimi 提供商 python -m pip install "cybergraph[all]" # 所有可选功能 # 从克隆（开发）： python -m pip install -e ".[dev]" ``` 支持的 Python：3.10、3.11、3.12、3.13。 ## 快速入门 ```bash cybergraph quickstart . # 从零到报告：初始化、构建、分析、打开报告 cybergraph init . cybergraph doctor . cybergraph analyze . # 构建 + 运行所有分析，打印顶级风险 cybergraph history . # 自上次扫描以来有什么变化/修复/回归 cybergraph config show . # 检查有效配置 + LLM/图谱状态 cybergraph build path/to/repo cybergraph ask "哪些函数可以执行 SQL？" --repo path/to/repo cybergraph explain "哪些路由可以执行 SQL？" --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 # 轻量级内置分析器，无需图谱 cybergraph triage path/to/repo # 排名发现；--llm 抑制假阳性 cybergraph sca path/to/repo # 按可达性优先的依赖 CVE cybergraph infer-specs path/to/repo # 提出自定义污染源/汇聚 cybergraph iac-paths path/to/repo # 公共暴露 -> 特权 IaC 资源 cybergraph investigate path/to/repo --output investigation.md cybergraph strix-plan path/to/repo --output strix-plan.md cybergraph import-strix strix_runs/<run> --repo path/to/repo cybergraph export-json path/to/repo --output graph.json cybergraph opengraph path/to/repo --output opengraph.json # BloodHound OpenGraph 互操作性 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 ``` 典型的构建输出： ```text 为 examples/vulnerable-fastapi 构建安全图谱 节点：15 | 边：28 | 发现：1 ``` 典型的 PR 评论部分： ```text 风险：中等 更改内容：CyberGraph 检测到 2 个入口点、1 个敏感汇聚边、1 个更改文件中的发现。 下一步检查：确认更改的入口点在需要时是否需要身份验证或授权。 ``` 导入扫描器结果： ```bash 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 "哪些高严重性发现涉及机密？" --repo path/to/repo ``` 使用 AI 渗透测试工具 ([Strix](https://github.com/usestrix/strix)) 验证可达风险： ```bash # 1. 将 CyberGraph 的可达路径转换为专注的 Strix 范围简介 cybergraph strix-plan path/to/repo --output strix-plan.md # 2. 自己运行 Strix 以应对该简介（需要 Docker + LLM 密钥）： # strix -n -t path/to/repo -m quick --instruction-file strix-plan.md # 或者让 CyberGraph 协调整个过程（可选，开启时）： cybergraph strix-run path/to/repo --scan-mode quick # 3. 将 Strix 的 PoC 验证发现导入图谱 cybergraph import-strix strix_runs/<run-name> --repo path/to/repo cybergraph top-risks path/to/repo # 验证后的发现排名靠前 ``` CyberGraph 告诉 Strix **哪里** 进行攻击（可达路由和汇聚），而 Strix 告诉 CyberGraph **什么是实际可利用的**（通过有效的 PoC 验证）。 Strix 永远不是依赖项 — `strix-run` 桥只有在 `strix` 二进制文件和 Docker 都存在时才会激活，因此默认离线工作流程保持不变。 抑制已接受的发现： ```python def test_fixture(): # cybergraph: ignore CG-SINK-CALL 接受测试查询 return db.execute("select 1") ``` 或配置仓库级抑制： ```toml [suppressions] rules = ["CG-SINK-CALL"] paths = ["legacy/**"] ``` 抑制隐藏发现，但图谱仍然保留诸如 `REACHES_SINK` 的边，以便审查者可以检查实际的代码路径。 ## 示例问题 ```text 哪些端点可以执行 SQL 操作？ 本次 PR 中更改了哪些内容影响身份验证？ 哪里加载了机密并传递给网络客户端？ 哪些漏洞依赖于生产代码的可达路径？ 是否有路由处理程序可以访问 shell 或文件写入？ ``` ## 尝试演示 ```bash cybergraph build examples/vulnerable-fastapi cybergraph ask "哪些路由可以执行 SQL 操作？" --repo examples/vulnerable-fastapi cybergraph visualize examples/vulnerable-fastapi --output cybergraph-report.html ``` ## MCP 工具 使用可选的 MCP 额外功能安装并运行服务器： ```bash 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 动作](docs/github-action.md) ## 状态 测试版。CyberGraph 分析五种语言，构建过程间攻击路径，导入和丰富扫描器发现，关联 IaC 与代码，发布交互式 HTML 报告，并为 AI 助手公开 MCP 接口。图谱存储、分析器、证据检索和报告稳定；公共 API 和发现规则在 1.0 之前可能会更改。