grizzly2005/belief

# BELIEF v4       BELIEF v4 是一个用于 AppSec、代码审查和漏洞赏金（bug bounty）筛选的实验性本地可报告性层。 它将扫描器、PDX 和静态分析信号转化为有证据支撑的审计案例、保守的推理摘要、精确案例反馈、可报告性基准测试以及可用于数据集的示例。 BELIEF 不会替代 Semgrep、CodeQL、Burp 或人工验证。它帮助人工审核者判断某个信号是否是一个值得报告的候选者、受保护（guarded）、可能的误报、微弱信号，或者仍然需要人工验证。 ## 什么是 BELIEF / 什么不是 ### BELIEF 是什么 - 一个用于 AppSec 和漏洞赏金筛选的本地可报告性层。 - 一个用于扫描器、PDX 和静态分析信号的桥接/编排层。 - 一个集成了审计案例、推理和精确案例反馈的系统。 - 一个可进行基准测试的筛选引擎。 - 一个安全的离线数据集导出器。 ### BELIEF 不是什么 - 不是漏洞利用生成器。 - 不是自动化漏洞扫描器。 - 不是漏洞赏金自动提交工具。 - 不能替代 Semgrep、CodeQL、Burp 或人工测试。 - 仅仅基于静态证据，无法证明漏洞已被确认。 ## 为什么使用 BELIEF? 安全工具产生信号。渗透测试人员和 AppSec 团队需要可报告的证据。 BELIEF 位于嘈杂的扫描器输出和人工审查之间。它保留来源，将信号映射为审计案例，保守地对可报告性进行评分，附加精确案例反馈，运行确定性的离线推理，并将已审查的案例转换为安全的数据集示例。 该项目刻意保持保守：静态和导入的证据在授权范围内经过人工验证之前，始终被视为候选证据。 ## 快速离线流程 从仓库根目录开始： ``` mkdir -p out/demo python -m belief pdx import tests/fixtures/pdx/pdx_bundle_sample.json \ --normalized-output out/demo/pdx.belief-tools.json python -m belief scan tests/fixtures/sample_app \ --import-tool-results out/demo/pdx.belief-tools.json \ --reportability \ --json-output out/demo/audit.json python -m belief reason \ --audit out/demo/audit.json \ --engine offline \ --output out/demo/reasoned.json python -m belief feedback apply \ --audit out/demo/audit.json \ --store-dir ./belief_feedback \ --output out/demo/audit.feedback.json python -m belief dataset export \ --from-audit out/demo/audit.feedback.json \ --format sft \ --output out/demo/belief.sft.jsonl python -m belief dataset validate \ --input out/demo/belief.sft.jsonl python -m belief benchmark reportability \ --target benchmark_reportability \ --json-output out/demo/benchmark.json ``` 此流程是本地且确定性的。它不会调用 LLM API、模型服务器、浏览器、网络服务或外部扫描器。静态和导入的证据在授权范围内经过人工验证之前，始终被视为候选证据。 ## PDX JSON 适配器 BELIEF 可以被动地将仅包含 JSON 的 PDX 包作为规范化的工具结果进行导入： ``` python -m belief pdx import tests/fixtures/pdx/pdx_bundle_sample.json \ --normalized-output out/pdx.belief-tools.json ``` 然后，这些规范化的结果可以被输入到审计/可报告性模式中： ``` python -m belief scan ./app \ --import-tool-results out/pdx.belief-tools.json \ --reportability \ --json-output out/audit.json ``` 此适配器刻意采用离线和保守模式。它不导入二进制 PDX、HYDRA 运行时代码、UI、浏览器自动化、gcloud 同步、API 引擎、角色、诱饵或真实会话。 离线推理、反馈应用、数据集导出、数据集验证和基准测试已在上述快速离线流程中展示。PDX 适配器本身仅执行被动的 JSON 导入/导出和规范化。 参见 [`docs/PDX_BELIEF_INTEGRATION.md`](docs/PDX_BELIEF_INTEGRATION.md)。 ## 可报告性基准测试 `benchmark_reportability` 是一个用于可报告性筛选的确定性离线基准测试。它包含以下合成本地案例： - IDOR/BOLA； - 批量赋值； - 路径遍历； - 受保护案例； - 可能的误报陷阱。 运行： ``` python -m belief benchmark reportability \ --target benchmark_reportability \ --json-output out/benchmark.json ``` 当前的基准测试模式是 `metadata_ground_truth_mvp`。它以确定性方式评估预期和观察到的可报告性标签。它不运行扫描器，不执行测试夹具（fixture）文件，不调用外部工具，也不证明真实的漏洞发现。 参见 [`benchmark_reportability/README.md`](benchmark_reportability/README.md)。 ## 工具链管理器 / 编排器 v1 BELIEF 可以在执行任何操作之前构建一个安全的本地运行计划： ``` python -m belief scope validate --file tests/fixtures/scope/local_safe_scope.json python -m belief target classify tests/fixtures/sample_app --json-output out/target-profile.json python -m belief tools profile list python -m belief tools profile show local-safe python -m belief tools availability --profile local-safe --json-output out/availability.json python -m belief plan tests/fixtures/sample_app \ --profile local-safe \ --flags auto \ --scope tests/fixtures/scope/local_safe_scope.json \ --output-dir out/run \ --json-output out/run/metadata/run-plan.json python -m belief execute-plan out/run/metadata/run-plan.json ``` 规划器将缺失的工具标记为不可用，而不是直接失败。除非有明确的范围授权，否则网络和动态工具将保持禁用状态。关于仅限被动的 PDX/HYDRA 恢复边界，请参见 [`docs/PDX_HYDRA_RECOVERY_PLAN.md`](docs/PDX_HYDRA_RECOVERY_PLAN.md)。 ## 它能做什么 BELIEF 当前的审查路径是： ``` Scanner / PDX / static signal -> NormalizedToolResult -> Finding / Hypothesis -> Dataflow / Guarantees -> AuditCase -> ReportabilityAssessment -> Offline Reasoning -> Exact-case Feedback -> Dataset / Benchmark Output ``` 目标是帮助审查者了解为什么一个发现可能是： - 一个值得报告的候选者； - 受到本地保证的保护； - 可能的误报上下文； - 微弱信号； - 仍然需要人工验证。 在实际应用中，BELIEF 试图回答以下问题： - 导入或发现了什么信号？ - 它暗示了什么漏洞假设？ - 是否存在从源到接收端（source-to-sink）或访问控制的证据？ - 代码是否包含防御性保证？ - 该案例是受保护的、微弱的、可能的误报，还是值得人工验证？ - 在提交报告之前，还缺少哪些证据？ - 精确案例的人工反馈应如何改变未来的筛选？ ## Pipeline ``` flowchart LR A[Python Codebase / Tool Output / PDX JSON] --> B[Normalized Signals] B --> C[Findings and Hypotheses] C --> D[Dataflow and Guarantees] D --> E[AuditCase] E --> F[ReportabilityAssessment] F --> G[Offline Reasoning] G --> H[Exact-case Feedback] H --> I[JSON / SARIF / Markdown / SFT / Benchmark] ``` ## 架构一览 ``` flowchart TB subgraph Inputs SRC[Python source tree] TOOL[Tool output / SARIF / JSON] PDX[PDX JSON] RULES[Bundled rule assets] end subgraph Normalization BRIDGE[Tool bridges] NTR[NormalizedToolResult] PROV[Signal provenance] end subgraph BELIEF Core FIND[Finding] HYP[Hypothesis] FLOW[Lightweight dataflow] GUAR[Guarantee index] AUDIT[AuditCase] REPORT[ReportabilityAssessment] end subgraph Review Loop REASON[Offline reasoning] FEEDBACK[Exact-case feedback] DATASET[SFT export] QUALITY[Dataset validation] BENCH[Reportability benchmark] end subgraph Outputs JSON[JSON] SARIF[SARIF] MD[Markdown] SFT[JSONL dataset] end SRC --> FIND TOOL --> BRIDGE --> NTR --> FIND PDX --> NTR RULES --> FIND FIND --> HYP --> FLOW --> GUAR --> AUDIT --> REPORT REPORT --> REASON --> FEEDBACK --> AUDIT REPORT --> JSON REPORT --> SARIF REPORT --> MD FEEDBACK --> DATASET --> QUALITY AUDIT --> BENCH DATASET --> SFT ``` ## 核心概念 ### Finding `Finding` 是稳定的低级信号。它可以来自 BELIEF 的本地扫描器、导入的工具结果、SARIF 文件、PDX 包或其他桥接。 ### Hypothesis `Hypothesis` 从安全角度描述一个发现可能意味着什么。BELIEF 将此与证明分开，以便微弱信号、受保护案例和误报上下文能够保持明确。 ### Dataflow BELIEF 包含轻量级的从源到接收端（source-to-sink）的数据流，用于帮助将受请求控制的值连接到潜在敏感操作。它是刻意保守的，不声称具有完整的程序理解能力。 ### Guarantees Guarantees 是从代码中挖掘出的防御性事实，例如所有者检查、租户检查、允许列表、路径包含、验证器或净化器。Guarantees 有助于降级受保护案例并识别缺失的证据。 ### Z3 检查 如果可用，可选的 Z3 检查可以对简单的布尔矛盾进行建模。这对于带有防护（guarded）的案例很有用，但它不能替代人工验证。 ### AuditCase `AuditCase` 是面向审查者的单元。它将发现、假设、证据、缺失的证据、可报告性评估、验证指南、推理摘要、反馈和导出元数据组合在一起。 ## 功能 - 本地 Python 代码扫描； - 被动导入规范化的外部工具结果； - 仅限 JSON 的 PDX 适配器； - 稳定的 `Finding` / `Hypothesis` / `AuditCase` 模型； - 保守的可报告性评估； - 离线确定性推理； - 精确案例反馈应用； - 安全的 SFT 数据集导出； - 数据集质量验证； - 可报告性基准 MVP； - 轻量级的从源到接收端（source-to-sink）数据流； - 保证提取； - 可选的 Z3 布尔矛盾检查； - Flask / FastAPI / Django 路由清单； - 为 `AuditCase` 提供 `route_context` 丰富化； - JSON / SARIF / Markdown 输出； - 漏洞赏金候选者 Markdown 导出； - 审计去重和聚类； - 集中化的安全分类法； - 面向外部工具的桥接导向架构。 ## 工具桥接 BELIEF 为外部工具和被动输出包含了一个安全的桥接架构。桥接可以将结果规范化到 BELIEF 的通用模型中，同时保留来源和保守的可报告性语义。 支持或已记录文档的桥接方向示例包括： - Semgrep JSON 导入； - CodeQL SARIF 导入； - ZAP 被动 JSON 导入； - Arjun JSON 导入； - OpenAPI 观察； - 类似 AuthMatrix 的 JSON 导入/导出； - Autorize 配方导出； - Param Miner 字典导出； - Dradis Markdown 导出； - 类似 Faraday 的 JSON 导出； - Threat Dragon 简单 JSON 导出； - RESTler / Joern / EvoMaster / Schemathesis 占位符或被动导入存根。 除非提供了明确的安全控制和授权范围，否则动态工具默认保持禁用状态。参见 [`docs/TOOL_BRIDGES.md`](docs/TOOL_BRIDGES.md)。 ## 导入的工具结果和可报告性 导入的结果可以转换为 BELIEF 审计案例，并使用保守的可报告性评分进行评估： ``` python -m belief tools import semgrep \ --file out/semgrep.json \ --normalized-output out/semgrep.belief-tools.json python -m belief scan ./app \ --import-tool-results out/semgrep.belief-tools.json \ --reportability \ --json-output out/audit.json ``` 结果可以成为 `reportable_candidate`、`needs_manual_validation`、`weak_signal`、`likely_false_positive` 或 `protected_by_guard`。BELIEF 不会将仅基于静态的证据视为确认。 ## 输出格式 ### JSON 使用 JSON 进行自动化、回归测试、可报告性评分和数据集生成： ``` python -m belief scan ./app --json-output out/audit.json ``` ### SARIF 使用 SARIF 进行代码扫描平台和审查工具集成： ``` python -m belief scan ./app --sarif-output out/belief.sarif ``` ### Markdown 使用 Markdown 生成人类可读的审计笔记或漏洞赏金候选草稿： ``` python -m belief scan ./app --bug-bounty-markdown out/bug-bounty.md ``` Markdown 输出仍然是以候选者为导向的，在提交之前应进行人工验证。 ## 使用示例 以可编辑模式安装： ``` python -m pip install -e ".[dev,z3]" ``` 运行本地扫描： ``` python -m belief scan ./app --reportability --json-output out/audit.json ``` 列出工具桥接： ``` python -m belief tools list python -m belief tools check ``` 运行可报告性基准测试： ``` python -m belief benchmark reportability \ --target benchmark_reportability \ --json-output out/benchmark.json ``` 运行测试套件： ``` python -m pytest -q python -m pytest -q -m security python -m pytest -q -m "not slow and not external and not llm" ``` ## 当前验证 当前本地回归基线： - 完整套件：`403 passed, 30 skipped`； - 安全套件：`44 passed`； - 非慢速/非外部/非 LLM 套件：`403 passed, 30 skipped`。 随着项目的发展，这些数字可能会发生变化。 ## 负责任的使用 BELIEF 适用于本地、授权的代码审查、AppSec 研究，以及防御性或漏洞赏金筛选工作流程。 未经许可，请勿使用 BELIEF 攻击系统。请勿将候选输出视为可利用影响的证明。在没有验证范围、授权、重现步骤、影响和项目规则之前，请勿提交漏洞赏金报告。 BELIEF 旨在减少噪音并改善审查结构，而不是绕过负责任的披露或人工判断。 参见 [`SECURITY.md`](SECURITY.md)。 ## 捆绑资产 BELIEF 可能包含捆绑的兼容性资产、本地辅助资源、安全规则参考以及由测试或桥接适配器使用的清单。 有关当前的资产清单和发布说明，请参见 [`BUNDLED_ASSETS.md`](BUNDLED_ASSETS.md)。 ## 局限性 - BELIEF 是实验性的。 - 静态和导入的证据只能产生候选者，不能保证是真正的漏洞。 - 可报告性基准测试目前为 `metadata_ground_truth_mvp`，不运行扫描器也不证明真实世界的发现。 - 推理引擎是确定性和本地的；它不是 LLM 代理。 - 默认情况下，刻意不启用动态验证。 - 外部工具不作为完整的运行时进行封装。 - 在做出任何真实世界声明之前，仍然需要在授权范围内进行人工验证。 ## 路线图 计划的方向包括： - 扫描驱动的可报告性基准测试评估； - 具备 BELIEF 元数据的生产级 Semgrep 和 CodeQL 包； - 更强的从路由到审计案例的丰富化； - 更好的过程间调用者推理； - 改进的 source/sink/sanitizer 分类法； - 更深入的 SARIF 和外部工具导入覆盖； - 更丰富的公开演示流程； - 更清晰的基准测试报告和比较基线； - 改进的示例和教程。 ## 测试 主要的回归测试命令是： ``` python -m pytest -q python -m pytest -q -m security python -m pytest -q -m "not slow and not external and not llm" ``` 该项目还包括桥接测试、访问模型测试、数据集测试、推理测试、反馈测试和基准测试。 ## 仓库结构 ``` belief/ Core BELIEF package. belief/tools/ Universal external-tool bridge registry, safety gate, runners, and adapters. belief/tool_results/ Normalized external tool result schema, mapping, provenance, and merge helpers. belief/reportability/ Conservative reportability scoring and explanations. belief/pdx/ JSON-only PDX adapter, redaction, import/export helpers, and mapping logic. belief/validation/ Generic validation result models and PDX verdict adaptation. belief/reasoning/ Deterministic offline reasoning models, router, and rule-based engine. belief/feedback/ Append-only feedback store and exact-case feedback application. belief/datasets/ SFT export and dataset quality validation. belief/benchmark/ Offline benchmark loading, metrics, and reportability benchmark runner. belief/tools_bundled/ Optional bundled compatibility assets and local helper resources. belief/security_rules/ Bundled security rule assets and references. tests/ Unit and regression tests. tests_bridges/ Bridge-related tests. benchmark_cve/ Benchmark-style vulnerable samples used for validation. benchmark_reportability/ Synthetic offline reportability benchmark corpus. schemas/ Documentation-only JSON schemas for BELIEF data formats. external_packs/ Documentation-only external pack placeholders and passive mapping notes. docs/ Project documentation and integration notes. BUNDLED_ASSETS.md Inventory and publication notes for bundled assets. SECURITY.md Public security policy and responsible-use guidance. .github/workflows/ci.yml GitHub Actions smoke and regression workflow. README.md Main public project documentation. LICENSE Repository license. pyproject.toml Python packaging and project metadata. ``` ## 文档 - [`docs/PDX_BELIEF_INTEGRATION.md`](docs/PDX_BELIEF_INTEGRATION.md) - [`docs/TOOL_BRIDGES.md`](docs/TOOL_BRIDGES.md) - [`benchmark_reportability/README.md`](benchmark_reportability/README.md) - [`SECURITY.md`](SECURITY.md) - [`BUNDLED_ASSETS.md`](BUNDLED_ASSETS.md) ## 许可证 [MIT](LICENSE) ## 免责声明 BELIEF 是研究软件。它可能会遗漏漏洞、对发现进行错误分类，或产生不完整的审计上下文。仅在授权环境中使用它，并将所有输出视为需要人工审查的候选者。

标签：Homebrew安装, Maven, Z3求解器, 云安全监控, 漏洞验证, 逆向工具, 静态分析