Hinotoi-agent/vulnweave

# VulnWeave **VulnWeave** 是一款本地优先的漏洞研究图谱工具，专为那些审查源代码、证明安全发现以及维护长期漏洞库的人员而设计。 它将通常分散在不同地方的两部分安全研究连接了起来： 1. **代码证据** —— 从源仓库中提取的安全相关事实：命令、scope/tenant 意图、直接加载 sink 和不变量违规。 2. **研究记忆** —— Obsidian 漏洞笔记、目标、CWE、标签、PR、CVE 以及重复/变体关系。 其目标并不是取代人工审查。VulnWeave 为审查者提供了一个图谱形工作台：映射仓库，浮现候选不变量，证明或驳回候选对象，然后将发现与先前的工作连接起来，从而使重复检查和变体搜寻随着时间的推移变得更加容易。 ## 为什么会有这个项目 安全发现很少是孤立的事实。一份有价值的报告通常依赖于类似如下的链条： ``` entry point -> trust boundary -> identity/scope assumption -> sensitive sink -> proof -> patch/report history ``` 大多数工具都会丢失这种上下文： - SAST 工具能找到嘈杂的语法模式，但不知道你先前的重复判定。 - 笔记记录了人类的判断，但很难跨仓库、CWE、PR 和变体进行查询。 - PR 和漏洞披露记录了结果，但与源代码级的证据脱节。 VulnWeave 试图让这种链条变得明确且可重用。 ## VulnWeave 目前能做什么 ### 源代码仓库图谱 `vulnweave map` 会遍历源代码树并生成一个小型的安全相关图谱。目前的 MVP 可识别以下模式： - 类似于 `CommandSpec(name="/resume", remote_invocable=True)` 的命令/控制平面注册 - 提及 `sender`、`user` 或 `tenant` 等字段的 actor/scope 构建 - 诸如 `load_by_id`、`get_by_id` 和 `read_by_id` 之类的直接对象/session 加载 sink - provider endpoint 重写、凭据来源、HTTP 请求 sink 和 endpoint 验证守卫 - 文件系统写入/提取 sink 附近的路径验证守卫，用于 symlink/TOCTOU 审查 - 到达 shell/process 执行 sink 的由调用者控制的命令参数 - 在没有 endpoint 守卫的情况下到达出站 HTTP 请求的、由调用者控制的 URL 参数 - 诸如远程控制平面命令 + scoped session 意图 + 全局直接加载 sink 等不变量 ### 候选审查 `vulnweave candidates` 读取源仓库或已持久化的图谱目录，并打印带有支持性证据的审查候选对象。这些**不是自动的漏洞声明**；它们是用于人工证明的结构化提示。 ### 候选到漏洞导出 `vulnweave export-finding` 将源代码候选对象桥接到 Obsidian 漏洞笔记中。它接收一个候选 ID，写入一份包含 frontmatter、证据、证明策略、重复检查清单以及补丁/披露占位符的草稿笔记，然后该笔记可以并入 `vulnweave vault-graph`。 ### 漏洞库图谱 `vulnweave vault-graph` 扫描 Obsidian vault 并生成图谱产物，有助于： - 在开启新 issue 或 PR 之前进行重复检查 - 跨仓库和 bug 类别进行同级/变体搜寻 - 按目标、CWE、CVE、标签或披露状态进行覆盖范围审查 - 保持公开的 PR、笔记和目标页面相互连接 vault 扫描器读取常规 Markdown 以及可选的 YAML frontmatter。它会提取： - 漏洞笔记和目标笔记 - wikilink 和 hashtag - CWE/CVE 提及 - GitHub 仓库和 pull request URL - 诸如 `type`、`target`、`status`、`severity`、`cwe`、`tags`、`pr` 和 `repo` 的 frontmatter 字段 ## 安装 对于本地开发： ``` git clone https://github.com/Hinotoi-agent/vulnweave cd vulnweave python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -e ".[dev]" vulnweave --help ``` 旧的 `security-kg` 命令目前仍作为兼容性别名保留： ``` security-kg --help ``` 如果你只想从检出的代码中运行而不安装它： ``` PYTHONPATH=src python -m security_kg.cli --help ``` ## 快速开始 运行内置的冒烟测试 fixture： ``` vulnweave map examples/remote_resume_drift --out /tmp/vulnweave-smoke vulnweave candidates /tmp/vulnweave-smoke vulnweave vault-graph --vault examples/vault --dry-run vulnweave doctor --repo examples/remote_resume_drift --graph /tmp/vulnweave-smoke --vault examples/vault ``` 你应该会看到一个映射图谱摘要、至少一个来自该 fixture 的由不变量支持的候选对象、一次 vault 图谱试运行摘要，以及通过的 doctor 检查。 ## 源代码仓库工作流 映射一个仓库并打印简短摘要： ``` vulnweave map /path/to/repo ``` 持久化图谱以供日后审查： ``` vulnweave map /path/to/repo --out /path/to/repo/.vulnweave ``` 从实时仓库路径或已持久化的图谱中查找候选对象： ``` vulnweave candidates /path/to/repo vulnweave candidates /path/to/repo/.vulnweave ``` 输出机器可读的格式： ``` vulnweave map /path/to/repo --json vulnweave candidates /path/to/repo/.vulnweave --json ``` 将候选对象导出为 vault 漏洞笔记： ``` vulnweave export-finding /path/to/repo/.vulnweave \ --candidate resume-load_by_id-3 \ --vault /path/to/example-vault \ --target "Target - Example App" \ --repo-url https://github.com/example-org/example-repo ``` 导出的笔记包含 YAML frontmatter、图谱路径、证据、证明策略、CVSS 评估清单、重复检查清单、复现占位符、补丁/PR 笔记以及披露/CVE 笔记。 一个典型的候选审查循环如下所示： ``` map repo -> inspect candidates -> read the exact source paths and functions in the evidence -> reproduce or reject the suspected trust-boundary drift -> search prior findings/PRs/CVEs for duplicates -> write a maintainer-safe patch or report -> add the finding to the vault -> rebuild the vault graph ``` ## Obsidian 漏洞库工作流 在 vault 中构建图谱产物： ``` vulnweave vault-graph \ --vault "/path/to/example-vault" \ --findings-dir "03 - Findings" \ --targets-dir "02 - Targets" \ --output-dir "99 - Graph" ``` 试运行而不写入文件： ``` vulnweave vault-graph --vault /path/to/example-vault --dry-run ``` 打印重复、过期草稿、缺失字段和变体搜寻提示： ``` vulnweave vault-insights --vault /path/to/example-vault ``` 该命令会写入： - `vulnweave-graph.json` —— 用于脚本、仪表板或后续导入程序的机器可读图谱 - `VulnWeave Graph.canvas` —— 展示漏洞、目标、标签、CWE、CVE、repo 和 PR 的 Obsidian Canvas 视图 - `VulnWeave Graph.md` —— 包含摘要计数、链接和 Dataview 助手的仪表板笔记 ## 建议的笔记约定 VulnWeave 可处理普通的 Markdown，但当漏洞使用可预测的 frontmatter 时，它会变得更加有用： ``` --- type: finding target: Target - Example App status: draft severity: High cwe: CWE-94 tags: - prompt-injection - remote-to-local pr: https://github.com/example-org/example-repo/pull/123 repo: https://github.com/example-org/example-repo --- ``` 正文可以使用正常的 Obsidian 链接和标签： ``` Links to [[Target - Example App]] and #remote-to-local. Related class: CWE-94. Possible duplicate: https://github.com/example-org/example-repo/pull/123 ``` 建议的漏洞部分： - **边界** —— 谁控制输入以及跨越了什么信任边界？ - **CVSS 评估** —— 哪些权限、拓扑假设以及已证实的 C/I/A 影响支持该评分？当维护者有理由要求降低评分时，保留一个保守的替代方案。 - **不变量** —— 本应坚持什么安全属性？ - **证据** —— 源代码路径、函数、图谱节点、日志或屏幕截图。 - **证明策略** —— 确认影响所需的最小安全复现步骤。 - **重复检查** —— 相关的 issue、PR、CVE、安全公告和先前的笔记。 - **补丁/报告备注** —— 对维护者安全的框架描述和修复方向。 ## 端到端工作流 ``` source repo -> vulnweave map -> vulnweave candidates -> local proof / duplicate check / patch -> vault finding note -> vulnweave vault-graph -> Obsidian duplicate, coverage, and variant review ``` ## 输出模型 VulnWeave 目前使用简单的 JSON/JSONL 产物，因此数据易于检查和编写脚本： - `meta.json` —— 图谱元数据和源代码根目录，包括 `schema_version: vulnweave.graph.v1` - `nodes.jsonl` —— 每行一个图谱节点 - `edges.jsonl` —— 每行一条图谱边 - `vulnweave-graph.json` —— 合并后的 vault 图谱导出文件，包含 `schema_version: vulnweave.vault_graph.v1` JSON 候选输出使用 `schema_version: vulnweave.candidates.v1`。这使得该工具保持本地优先，并在 schema 仍在演进时避免要求使用数据库。 ## Doctor 检查 使用 `doctor` 检查本地路径和预期的图谱/vault 结构： ``` vulnweave doctor --repo /path/to/repo --graph /path/to/repo/.vulnweave --vault /path/to/example-vault ``` ## 开发 ``` python -m pip install --upgrade pip python -m pip install -e ".[dev]" python -m pytest -q python -m ruff check src tests examples python -m compileall -q src tests examples ``` CI 会在 Python 3.9 和 3.12 上运行相同的核心检查。 ## 设计原则 - **本地优先：** 除非你选择发布结果，否则源代码仓库和 vault 将保留在你的机器上。 - **证据重于声明：** 候选对象应指向具体的路径、符号和关系。 - **人类在环：** 该工具支持证明和报告；它不会替你声明 CVE。 - **图谱形记忆：** 每一个发现都应变得更容易与先前的发现进行比较。 - **普通文件优先：** JSONL 和 Markdown 优先，仅在工作流需要时才使用数据库。 ## 路线图 近期： - 改进过程间可达性和特定于框架的 handler 映射。 - 在 Python 之外添加更多语言前端。 - 添加置信度评分和对已知安全模式的抑制/允许列表支持。 - 添加更丰富的 vault 老化/状态分析以及可选的 GitHub PR 状态同步。 长期： - 交互式图谱仪表板。 - 从候选证据生成证明骨架。 - 跨仓库 bug 类别聚类。 - 用于 SARIF、GitHub issue 和披露跟踪器的导入/导出桥接。 ## 状态 VulnWeave 是一个早期的 MVP。请将其用作研究助手和工作流脚手架，而不是完整的扫描器。

标签：GPT, Homebrew安装, 云安全监控, 时序数据库, 本地优先, 漏洞管理, 逆向工具, 防御加固, 静态分析