kappa9999/white-hat-agent

# White Hat Agent Core **一个模型中立的网络安全能力大脑，面向 AI agent 和人类研究者。** White Hat Agent Core 将社区知识、精确的程序范围、适配器能力、证据和 agent 集群转化为一个可组合的应用层。其设计使得研究者可以用任何语言描述一项技术，而 AI 原生团队可以通过 MCP、JSON Schema、Python 或 `wha` CLI 使用同一语料库。 长期目标是建立一个开放的网络安全语料库，其经过验证的小型方法会随着模型的改进而变得更有价值：模型可以通过声明的适配器进行搜索、组合、执行，保留负面结果，验证因果关系，并返回新的学习内容供审查。 ## 系统架构 ``` flowchart LR S[Plain text in any language] --> I[Lossless intake] R[Reports, standards, field notes] --> I I --> D[Reviewable playbook draft] D --> C[Versioned cyber corpus] C --> P[Semantic composer] O[Programs and open targets] --> Q[Scope and opportunity plane] Q --> P K[Capability catalog] --> P P --> F[Leased agent fleet] F --> A[Explicit adapters] A --> E[Immutable evidence and findings] E --> V[Causal and differential verification] V --> L[Reusable learning queue] L --> I ``` ### 核心组成要素 - **知识：** 严格的、带版本控制的 YAML 剧本，包含原始语言、出处、权限、前置条件、类型化工件、能力、证据要求、失败模式、清理和验证记录。 - **组合：** 通过语义 `consumes`/`provides` 契约、目标契合度、目标类型、平台、执行上限、能力清单、冲突和显式兼容性进行确定性链接。 - **能力：** 供应商中立的适配器契约。内置目录目前定义了 18 项能力，供最初的跨领域、Web、移动端和二进制剧本使用。 - **机会：** 规范化的公开项目、开源工作、实验室和私人参与，按范围置信度、新鲜度、语料库覆盖率、能力契合度和操作者优先级进行排名。 - **活动和集群：** 确定性的多目标规划、精确范围和剧本契约快照、预算、原子级任务去重、兼容 agent 匹配、过期的哈希租约、有界重试和显式的生命周期状态。 - **证据：** 有界的本地导入、SHA-256 内容寻址、出处、敏感度/脱敏状态、活动/任务绑定，以及没有注册证据就无法宣称已验证状态的发现结果。 - **发现：** 可恢复的证据图、多样化的假设组合、对进度敏感的重新规划、精确的负面结果记忆、相邻发现保留以及因果关系证明层级。 - **接口：** 命名空间化的 FastMCP 3 工具/资源/提示词、JSON Schema、Python 以及嵌套的 CLI。 ## 五分钟本地启动 要求：Python 3.12+ 和 [uv](https://docs.astral.sh/uv/)。 ``` git clone https://github.com/kappa9999/white-hat-agent.git cd white-hat-agent uv sync --locked --extra dev uv run wha init . uv run wha doctor --workspace . uv run wha corpus search "http differential" --workspace . uv run wha capability gaps \ --workspace . \ --playbook http-response-surface-map \ --available http.request \ --available http.capture ``` 新安装会将自带的入门语料库和能力目录复制到一个普通的工作区中；两者均可编辑和审查。 ## 无需学习 schema 即可贡献知识 按照你所了解的方式编写方法： ``` uv run wha knowledge ingest \ --workspace . \ --file examples/submissions/spanish-mobile-technique.md \ --language es \ --rights original-contribution \ --playbook-yaml /tmp/mobile-draft.yaml ``` 编译器会保留确切的源代码，对可能的步骤进行分段，添加原始语言字段，并列出未解决的问题。它**不会**将翻译或草稿伪装成已验证的状态。宿主模型可以使用 MCP 的 `knowledge_compile_submission` 提示词，根据公开的 Playbook schema 对同一源码进行优化。 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [剧本编写](docs/playbook-authoring.md)。 ## 组合工作流 ``` uv run wha playbook compose \ --workspace . \ --request examples/composition/web-to-verified.yaml ``` 该示例仅在所有语义输入和适配器能力都存在时，才会将 HTTP 差异映射链接到因果验证。如果无法达到预期的工件，结果会指出缺失的边界，而不是凭空捏造一个步骤。 将精确的范围、目标、预期工件和已安装的适配器能力转化为分阶段的活动蓝图： ``` uv run wha campaign plan \ --workspace . \ --request examples/campaigns/planning-request.yaml ``` 每个生成的阶段都包含具体的剧本版本、语义输入/输出、依赖关系、类型化的探测意图，以及绑定到确切范围和意图摘要的决策。不完整或超出范围的计划会将阻碍作为数据返回；绝不会被静默设为可执行状态。 ## 运行范围内的集群测试夹具 ``` uv run wha scope check \ --scope examples/campaigns/lab-scope.yaml \ --intent examples/campaigns/http-intent.yaml uv run wha campaign create \ --workspace . \ --manifest examples/campaigns/lab-campaign.yaml uv run wha campaign enqueue \ --workspace . \ example-lab-campaign \ --intent examples/campaigns/http-intent.yaml uv run wha fleet register \ --workspace . \ --registration examples/agents/http-agent.yaml uv run wha campaign state --workspace . example-lab-campaign ready uv run wha campaign state --workspace . example-lab-campaign running uv run wha fleet claim --workspace . example-http-agent ``` 该示例使用保留的 `.test` 目标，并且不执行任何网络操作。声明的任务是对外部适配器/agent 的指令，而不是隐式的扫描器调用。 ## 从任何 MCP 客户端使用它 启动 stdio： ``` uv run wha serve --workspace . --transport stdio ``` 或无状态的 Streamable HTTP： ``` uv run wha serve --workspace . --transport http --host 127.0.0.1 --port 8000 # endpoint: http://127.0.0.1:8000/mcp ``` 服务器挂载了有界的命名空间： | 命名空间 | 示例 | |---|---| | `knowledge_*` | 搜索、验证、录入、组合、学习候选 | | `capability_*` | 搜索契约、检查定义、计算差距 | | `opportunity_*` | 添加、排名、分类、追踪 | | `campaign_*` | 计划、范围检查、创建、转换、入队 | | `fleet_*` | 注册、认领、心跳、报告、统计 | | `evidence_*` | 导入、注册、列出、绑定发现 | | `discovery_*` | 计划、观察、因果验证 | 请参阅 [MCP 集成](docs/mcp.md) 和 [架构设计](docs/architecture.md)。 ## 语料库信任模型 语料库可以表示任何网络技术。信任是按版本获取的： `draft → proposed → reviewed → validated → deprecated` 原始文本、技术有效性、作者身份、权限、目标授权、执行副作用和披露状态是相互独立的事实。不受信任的提交是数据，绝不是隐藏的 shell 指令。提升需要严格的 schema 验证和与声明相符的证据。Draft/proposed 阶段的材料仍然可以搜索和审查，但默认的组合和每个持久化的活动都需要 reviewed 或 validated 状态的剧本版本。 ## 开发 ``` uv run ruff format --check . uv run ruff check . uv run pytest uv run wha corpus validate --workspace . uv run wha capability validate --workspace . uv run python scripts/check_builtin_assets.py uv run python scripts/export_schemas.py uv build ``` ## 项目与安全 - [路线图](ROADMAP.md) - [威胁模型](THREAT_MODEL.md) - [治理](GOVERNANCE.md) - [安全报告](SECURITY.md) - [贡献](CONTRIBUTING.md) **名称说明：** “White Hat Agent Core”是一个暂定的项目名称。已经存在一个名称相似但无关的 agent 沙箱项目；在发布公告之前，请完成[发布检查清单](docs/publication-checklist.md)中的名称和商标检查。 采用 [Apache-2.0](LICENSE) 许可协议。唯一的维护者基础模型在 [MAINTAINERS.md](MAINTAINERS.md) 中进行了说明。

标签：MCP, Web报告查看器, XXE攻击, 安全工作流, 安全运营, 扫描框架, 网络安全知识库, 自动化编排, 逆向工具