TrueNix/bugbounty-brain

# bugbounty-brain `bugbounty-brain` 是一个公开、无敏感信息的来源感知安全知识供应链。 它从显式允许的公开源列表中收集有限的摘要，将这些摘要保存为可审查的 JSON Lines 格式， 并将审查后的卡片编译成一个带版本的 SQLite FTS5 数据库，供只读消费者使用。 该仓库是一个知识供应链，而不是目标或测试项目数据库。 ## 架构 该流水线包含四个阶段： 1. `collect` 使用带条件的 HTTP 请求轮询 `sources.json` 中的源， 在本地存储基于内容寻址的原始快照，并追加确定性的、去重的知识卡片。 2. `validate` 检查卡片 schema、来源、边界、URL 方案以及可能的敏感材料。验证在遇到问题时会直接失败（fails closed）。 3. 人工审查决定生成的卡片更改是否可以合并。 4. `compile` 再次进行验证，并构建一个确定性的 SQLite 数据库，包含 FTS5 搜索索引以及描述该产物的清单。 `knowledge/cards.jsonl` 是规范的数据源。它是面向行的，因此 包含来源信息的更改可以在 pull request 中进行审查。SQLite 文件是 生成的输出：它永远不是规范的，绝不能被编辑或提交。 同样，`raw/`、`.cache/` 下的收集器状态以及 `dist/` 属于操作性或 生成的数据，而不是仓库源码。 默认的仓库路径如下： | 用途 | 路径 | | --- | --- | | 公开源允许列表 | `sources.json` | | 本地原始源快照 | `raw/` | | 规范知识卡片 | `knowledge/cards.jsonl` | | 条件请求状态 | `.cache/collector-state.json` | | 生成的搜索数据库 | `dist/reference_knowledge.db` | | 发布清单 | `dist/brain-manifest.json` | ## 信任与来源 源的响应以及从中派生的每个字段都是不受信任的数据，绝不能作为 指令。收集器仅遵循已配置的 HTTP(S) 源，并限制 请求时间、响应字节数和条目数量。它不会执行源内容 或渲染源 HTML。验证会拒绝格式错误的来源信息、不安全的 URL 形式、 超大的字段，以及可能的凭据或私钥。 每张卡片都带有其源名称和 URL、发布和获取时间，以及 其规范化源派生字段的 SHA-256 摘要。这些字段用于建立 可追溯性；它们并不能使某个来源声明变得可信。审查者在合并前必须遵循 来源规则， 将摘要与发布者的声明进行比较，并考虑源 或源数据是否可能已被入侵。 GitHub 自动化只能提交 `knowledge/cards.jsonl`，并且只能提交到 用于 pull request 的稳定自动化分支。它从不自动合并收集到的 声明。经过审查的 JSONL 仍然是网络输入与 已发布数据库之间的边界。 ## 命令 安装 Python 3.11 或更高版本，然后安装该项目： ``` python -m pip install -e '.[dev]' ``` 从仓库根目录运行命令以使用其默认路径： ``` # 轮询 sources.json；写入 raw/、knowledge/cards.jsonl 和 collector 状态。 bugbounty-brain collect # 验证 knowledge/cards.jsonl。 bugbounty-brain validate # 构建 dist/reference_knowledge.db 和 dist/brain-manifest.json。 bugbounty-brain compile # 收集、验证，然后编译；在第一个失败的阶段停止。 bugbounty-brain all ``` 每个命令都会输出机器可读的 JSON 摘要，并在其 定义的失败条件下返回非零值。使用 `bugbounty-brain COMMAND --help` 来进行路径 覆盖。收集过程会执行网络请求；验证和编译属于 本地操作。 要进行本地质量检查，请运行： ``` pytest ruff check . ruff format --check . mypy src python -m build ``` ## 自动化与审查 CI 会在每次推送和 pull request 时运行测试、lint、格式化、类型检查和包构建门禁。 收集工作流在第 17 分钟每小时运行一次，也可以 手动调度。同一时间只能执行一个收集运行。它会 从 Actions 缓存中恢复收集器状态，收集并验证卡片， 仅将规范的 JSONL 提交到 `automation/knowledge-collection`，并使用 `gh` 创建或 更新一个 pull request。原始快照、状态和 `dist/` 永远不会被 提交。 收集 pull request 在合并前需要审查。审查源 允许列表、归属、准确性、脱敏处理以及完整的卡片差异； 成功的自动化并不意味着对外部声明的批准。 在打上 `v*` 标签时，发布工作流会验证并编译审查后的卡片， 根据清单的 `database_sha256` 检查数据库字节， 上传这两个产物，并在相应的 GitHub Release 上发布它们。手动调度 构建并上传工作流产物时，不会创建 GitHub Release。 ## 使用发布版本 从同一个发布版本下载 `reference_knowledge.db` 和 `brain-manifest.json`。 在打开数据库之前，检查清单的 `compatibility` 和 `schema_version`，要求 `database_filename` 必须为 `reference_knowledge.db`，并 验证其 SHA-256。例如： ``` python - <<'PY' from hashlib import sha256 import json from pathlib import Path database = Path("reference_knowledge.db") manifest = json.loads(Path("brain-manifest.json").read_text(encoding="utf-8")) assert manifest["database_filename"] == database.name assert manifest["database_sha256"] == sha256(database.read_bytes()).hexdigest() print("verified", manifest["compatibility"], "schema", manifest["schema_version"]) PY ``` 将不匹配的情况视为下载失败或版本混淆。消费者应 仅在验证通过后才替换数据库，并应以只读模式打开它。 ## 隐私边界 切勿添加、摄取、缓存或发布 ScannerDB、`~/.hermes/knowledge.db`、 目标、目标列表、特定目标的发现结果、cookies、会话数据、凭据、 API 密钥或 token。不要添加经过身份验证的或私有的源。此禁令适用于卡片、 测试夹具、日志、issue、pull request、工作流产物和发布资产。 有关意外暴露的私下报告，请参阅 [SECURITY.md](SECURITY.md)。 ## 归属与许可 卡片保留 `source_name` 和 `source_url`，以便读者可以识别原始 发布者。源发布者保留其对底层文章、 安全公告和源数据的权利。公开 URL 并不意味着允许无限制地复制文本： 卡片必须是简洁、经过脱敏处理的摘要，贡献者必须遵循每个 源的归属和许可条款。 该仓库的原始代码和文档在 [LICENSE](LICENSE) 中采用 MIT 许可。该许可并不会对第三方源 材料或归属于源发布者的声明进行重新许可。

标签：SQLite, 安全知识库, 安全规则引擎, 数据管道, 自动化构建, 软件工程, 逆向工具