ItamarRosen/hunter

# Hunter Hunter 是一个用于评估**自主威胁狩猎代理**的研究框架：在仅提供网络拓扑和一项中立任务（“判断此网络是否被入侵，如果是，是如何被入侵的。开始。”）的情况下，由 LLM 驱动的调查员能否提出正确的问题，找到决定性的证据，得出正确的结论，并且*不会*捏造它实际上无法证实的东西？ 每次实验都会让一个 **Hunter**（受测代理）与一个 **Environment**（环境）进行对抗——该环境由一个网络拓扑加上一个描述真实情况（突发事件、诱饵、竞争性叙述或什么都没有）的隐藏真相组成——并根据评分规则对调查结果进行打分。 ## 狩猎如何运作 1. **Hunter** (`engine/hunter.py`) 会获得一个网络拓扑和一个任务框架。它通过反复调用 `collect_evidence(device_id, request)`——像熟练的分析师那样组织请求——来进行调查，并在最后调用 `submit_report(...)` 提交发现、置信度/严重程度以及待解决问题。 2. **Evidence Collector** (`engine/evidence.py` 中的 `EvidenceCollector` 协议) 会响应每个 `collect_evidence` 调用。目前有两种实现： - **`GenerativeEvidenceCollector`** (`engine/collectors/generative.py`) — 一个植入了拓扑结构和对 Hunter 隐藏的真相的 LLM “匹配器”。它会即时生成看似合理的证据，并在真实系统会暴露它们的地方巧妙地融入真相细节。 - **`FixtureEvidenceCollector`** (`engine/collectors/fixtures.py`) — 一个封闭、确定性、仅检索的证据集合。LLM 路由器（强制工具调用，temperature 设为 0）仅*分类*请求涉及的是哪些预设记录；实际的记录文本已在 `environments/env_005_fixtures.json` 和每个单元格的 `sources.json` 中提前固定。没有任何模型会生成证据内容，从而消除了匹配器侧产生虚构/泄露的一整类失败模式。 3. **Verification** (`engine/verifier.py` + `engine/report_gate.py`) 会将 Hunter 的推理与它实际收集到的证据进行两次比对验证： - **`record_conclusion`** — 当 Hunter 在调查过程中记录下一个阶段性结论时，一个处于全新上下文的验证模型会生成最合理的竞争性解释，并判断证据是否能在两者之间产生*区分度*，从而返回 `SUPPORTED`（已证实）/ `NON_DIAGNOSTIC`（无诊断性）/ `CONTRADICTED`（相矛盾），一个 `reachable` 标志（具有区分度的证据在此处是否甚至可收集？），以及 Hunter 必须遵守的 `binding_directive`。 - **终端报告门控** — 在执行 `submit_report` 时，每一项发现（不仅仅是 Hunter 明确记录过结论的发现）都会以相同的方式进行独立复审。无法站得住脚的发现会被强制转化为待解决的 `coverage_gap`（覆盖盲区）——绝对不会被重写为虚假的“安全”/“未入侵”——并且对于超出证据*类型*所能支持的断言（例如，仅凭流量/容量证据推断出被窃取的*数据内容*），会通过 `scope_flags` 进行机械性限制，将无法证实的那部分移至 `open_questions`（待解决问题）。`submit_report` 会被拒绝——并且 Hunter 必须进行修改——直到每一个结论/发现都处于 `SUPPORTED` 状态，或者已被如实地弱化为一个无法触及的 coverage gap，该过程还受到门控拒绝次数限制，以确保循环总能终止。 4. **Scoring** (`engine/scoring.py`) 会根据环境的 `rubric.json` 重放 `report.json`、`transcript.json` 和 `collection_log.json`。对于评分规则中的每一项，它会推导出以下结果之一： - `not_encountered` — 从未暴露。 - `resolved_with_evidence` — 已暴露，请求并引用了决定性证据，标签正确。 - `unconfirmed_guess` — 在从未请求/引用决定性证据的情况下得出了正确标签（答案正确，但仅基于表面线索）。 - `handled_implicitly_unstated` — 未被直接提及，但通过既定的一般性标准对其进行了正确处理。 - `unresolved` — 已暴露但贴错标签或未予处理。 独立的评分器会检查是否存在**虚构捏造**：`grade_confabulation`（是否将一个干净的环境错误地指控为存在不存在的入侵？）和 `grade_exfil_confabulation`（报告是否断言了超出现有证据——容量/时间/目的地——所能支持的特定*被窃取数据内容*？）。 ## 环境 每个 `environments//` 目录包含： - `topology.json` — Hunter 看到的网络：设备、网段、角色。内容被严格写为中立的——不包含关于事件发生在何处或是否真有事件的任何暗示。 - `ground_truth.md` — 真实的内情（事件时间线、决定性证据标签、诱饵/竞争性叙述、良性基线）。从不直接展示给 Hunter；仅通过证据收集器的响应予以呈现。 - `rubric.json` — 可评分项（核心事件、诱饵、竞争性叙述、证据缺口），包含 `encounter_tags` / `decisive_evidence_tags` 以及每一项的正确标签。 - `coverage.json` (env_003/004) — 将真相标签映射到 FEED（在遥测数据块中始终可见）与 ON-DEMAND（仅可通过 `collect_evidence` 获取），用于被动检测实验。 - `sources.json` (env_005 单元格) — 针对每个单元格的表格，记录存在哪些证据源、它们涵盖的内容以及它们返回的记录；与共享的 `env_005_fixtures.json` 记录库和路由映射配合使用。 ### 实验目录 | 环境 | 测试目的 | |---|---| | `env_000_dummy` | 对 Hunter 端到端循环的最小冒烟测试。 | | `env_001_noisy` | 一起被埋没在日常网络噪音中的真实事件。 | | `env_002_competing_narratives` | 事件加上第二个不相关的可疑活动流 —— Hunter 会不会将它们混淆？ | | `env_003_wrong_story` | 相同的网络，但有一个更显著的“竞争性” EDR 告警和诱饵，旨在引导得出一个看似合理实则错误的结论。这也是第一个配备用于被动检测对比的 `coverage.json`/`rubric.json` 的环境。 | | `env_004_cloud_identity_lotl` | 一起混合身份（本地 AD + Entra ID/M365）的“靠山吃山”（Living-off-the-land）入侵（Storm-0558/Midnight Blizzard 式的 OAuth 滥用），其被蓄意设计为环境中*最微弱*的信号，需要与一次失败的密码爆破和一次授权的渗透测试进行较量。包含一个将事件完全移除的 `_control` 变体。 | | `env_005_favorable_*` / `env_005_hostile_*` | 围绕单次 Northbridge Communications 网络/边界路由器入侵进行的 2x2 测试（有利的 vs. 不利的监控设备 x 被入侵的 vs. 干净的）。用于测试当*同一起*事件通过干净的离设备遥测数据（有利）可以关联时，与仅能通过被篡改/自我报告的设备加上一个带外监听（不利）进行关联时，Hunter 的结论是否会发生变化 —— 以及干净的单元格是否保持干净。使用确定性的 `FixtureEvidenceCollector`。 | | `env_005_hostile_compromised_notap` | `env_005_hostile_compromised` 的消融实验：事件和拓扑完全相同，但那个能使该入侵变得可解析的唯一带外监听点并不存在 —— 按结构设计，决定性证据是无法触及的。用于自我检查 Hunter（以及验证器/报告门控）是否正确地将这种无法证实的嫌疑保持为待查的 coverage gap，而不是得出虚假的“安全解除”结论或触发幽灵般的升级。 | `CHANGES.md` 包含针对每个环境的详细且按时间顺序记录的设计原理，以及针对运行结果所做的每一项修复。 ## 运行操作 设置： ``` poetry install echo "ANTHROPIC_API_KEY=sk-..." > .env ``` 运行单次狩猎（生成式匹配器）并对其进行打分： ``` python run_hunt.py python score_hunt.py ``` 跨 env_003/env_004 运行三组实验（被动检测 vs. Hunter+Monitor vs. 控制组）： ``` python run_experiment.py [--force-regenerate-telemetry] ``` 运行 env_005 有利/不利 2x2 测试（基于固定数据的 Monitor）： ``` python run_experiment_005.py [--seeds N] [--cells GROUP] [--no-verifier] # --seeds N 每个细胞的 seeds 数量（默认 1，pilot） # --cells "all"（默认）、"favorable"、"hostile"、"compromised"、 # "clean" 或 "notap"（env_005_hostile_compromised_notap） # --no-verifier 禁用 competing-hypothesis verifier/report gate ``` 为被动检测组生成遥测数据块： ``` python generate_telemetry.py ``` 所有的运行都会将它们的产物（对话记录、收集日志、调查日志、报告、得分、覆盖矩阵，以及——在启用验证器时生成的——`verifier_log.json`）写入 `runs/_/`，并且实验脚本会生成一个总结该次运行的 `REPORT.md`。 运行测试套件（基于普通 `assert` 的脚本，无 pytest）： ``` .venv/bin/python tests/test_report_gate.py ``` ## 仓库结构 ``` engine/ hunter.py Hunter agent loop (collect_evidence / submit_report) evidence.py EvidenceCollector protocol, shared types verifier.py Competing-hypothesis verifier (record_conclusion review) report_gate.py Terminal report gate: per-finding re-review + scope_flags at submit_report, with bounded forced resolution collectors/ generative.py LLM "Matcher" evidence collector fixtures.py Deterministic fixture evidence collector (env_005) detection.py Passive single-pass detector (no collect_evidence) telemetry.py Telemetry chunk generation for the detection arm rules.py Cheap regex IoC rule-matcher (fairness-gate check) scoring.py Rubric grading + confabulation graders coverage.py FEED/ON-DEMAND tag bookkeeping environment.py Loads topology.json + ground_truth.md runner.py Shared run-artifact writing render.py Investigation-log rendering prompts/ All system prompts (Hunter, Matcher, detector, verifier, graders, router) environments/ One directory per environment (topology, ground truth, rubric, ...) runs/ Timestamped output of every hunt/experiment/scoring run tests/ Plain-assert test scripts (no pytest); run via `.venv/bin/python tests/test_*.py` run_hunt.py, run_experiment*.py, score_hunt.py, generate_telemetry.py Composition roots / CLI entry points CHANGES.md Chronological log of environment design fixes and why ``` ## License MIT — 见 [LICENSE](LICENSE)。

标签：AI智能体, C2, Clair, DLL 劫持, 后端开发, 大语言模型, 安全评估框架, 网络安全, 自动化推理, 逆向工具, 隐私保护