Lona44/find-evil-ir-agent

# find-evil-ir-agent 面向 [SANS FIND EVIL!](https://findevil.devpost.com/) 黑客马拉松（2026年4月15日 – 6月15日）的自主应急响应 agent。本项目通过多 agent 的 LangGraph 架构和内置的偏差评估层，扩展了 Protocol SIFT 的自主应急响应能力，该评估层能够在 agent 自身产生的幻觉传达给分析师之前将其捕获。 ## 存在的意义 自主 IR agent 会在两种不同的情况下失败： 1. 它们会遗漏发现——即漏报，这是一个经典问题。 2. 它们会捏造发现——即误报、伪造的工件引用、以及盲目自信但错误的叙述。 第二种失败模式正是削弱分析师对基于 agent 的 SOC 工具信任的原因。本项目直接解决了这一问题：agent 产生的每一个发现都会由第二个具有基础证据只读权限的 agent 进行独立验证，任何未经验证的声明要么被标记，要么从最终报告中剔除。 ## 架构 ``` ┌─────────────────────────────────────────────────┐ │ Evidence │ │ disk images · memory captures · logs · pcaps │ │ · remote endpoints via MCP │ └────────────────────────┬────────────────────────┘ │ read-only access │ ┌────────────────────────▼────────────────────────┐ │ Investigator Agent │ │ • Plans investigation │ │ • Executes SIFT tools (Volatility, Plaso, │ │ Sleuthkit, …) via tool-use │ │ • Produces candidate findings with citations │ └────────────────────────┬────────────────────────┘ │ candidate findings │ ┌────────────────────────▼────────────────────────┐ │ Validator Agent │ │ • Re-checks each finding against the cited │ │ artefact (offset / line / hash) │ │ • Flags hallucinations and unsupported claims │ │ • Returns confirmed / inferred / rejected │ └────────────────────────┬────────────────────────┘ │ validated findings + flags │ ┌────────────────────────▼────────────────────────┐ │ Reporter Agent │ │ • Composes structured investigative narrative │ │ • Distinguishes confirmed vs inferred │ │ • Cites every claim to a specific artefact │ └────────────────────────┬────────────────────────┘ │ ┌────────────────────────▼────────────────────────┐ │ Audit + Accuracy Report │ │ • Tool execution logs (timestamps, tokens) │ │ • Hallucination rate per case │ │ • Citation coverage │ └─────────────────────────────────────────────────┘ ``` 完整的架构描述：[`docs/architecture.md`](docs/architecture.md)。 ## FIND EVIL! 必备功能 比赛规则要求具备三项功能。每一项都由架构中的特定组件负责： | 要求的功能 | 实现方式 | | --- | --- | | **自我纠正** —— agent 检测并解决其自身输出中的错误或不一致，无需人工干预 | Validator agent 会重新检查 Investigator 的每一个发现；不匹配将触发重新调查循环，直到声明被确认或被标记为拒绝 | | **准确性验证** —— 所有发现均可追溯到特定的工件、文件、偏移量或日志条目 | Investigator 发出的每一个发现都包含一个引用元组 `(artefact_path, offset_or_line, content_hash)`；Validator 会在该确切位置进行独立重新读取 | | **分析推理** —— 输出以结构化的调查叙述呈现，而非原始执行日志 | Reporter agent 编写按阶段（获取 → 分析 → 结论）分组的 Markdown 叙述，并以不同方式渲染已确认的发现和推断出的发现 | ## 与现有工作的关系 本项目处于两项先前工作的交汇点： - **[Unified AI Misalignment Framework](https://github.com/Lona44/unified-ai-misalignment-framework)** —— 这是支持 Validator agent 的评估方法论。该框架的幻觉检测模式在此处被复用，用于在 Investigator 的输出传达给分析师之前对其进行评分。 - **Agent Arena** ([procurement-intelligence](https://github.com/Lona44/procurement-intelligence)) —— 此 IR pipeline 基于多 agent 的 LangGraph + 人在回路 (human-in-the-loop) 投票模式构建。 ## 技术栈 - **Agent 框架：** LangGraph + Claude（通过 Anthropic API）。规则允许使用类似的 agent 架构。 - **Runtime：** Linux 终端，SANS SIFT Workstation 环境。 - **封装的 SIFT 工具：** Volatility 3、Plaso、Sleuthkit、log2timeline、Wireshark/tshark（初始集合；在开发过程中扩展）。 - **远程证据：** 用于 endpoint 查询的 MCP server。 - **审计：** 结构化执行日志 (JSONL)，包含每次调用的时间戳、工具输入和 token 使用情况。 ## 仓库结构 ``` . ├── LICENSE Apache 2.0 ├── README.md this file ├── pyproject.toml Python package config ├── agents/ LangGraph agent definitions │ ├── investigator.py primary IR agent — analyses evidence │ ├── validator.py self-correction agent — verifies findings │ ├── reporter.py structured narrative composer │ └── prompts/ system prompts (auditable, version-controlled) ├── tools/ SIFT tool wrappers + MCP integration │ ├── sift_tools.py wrappers for Volatility, Plaso, Sleuthkit │ ├── mcp_endpoints.py remote-endpoint MCP server endpoints │ └── audit.py audit-trail and token-usage logger ├── evals/ accuracy evaluation │ ├── hallucination_check.py reuses Unified Framework methodology │ ├── citation_check.py verifies every claim has an artefact citation │ └── scenarios/ test cases (synthetic evidence packages) ├── infra/ deployment + execution environment │ ├── Dockerfile SIFT-Workstation-compatible │ ├── compose.yml │ └── requirements.txt ├── docs/ required submission artefacts │ ├── architecture.md full architecture description │ ├── accuracy-report.md self-assessment of false positives / hallucinations │ ├── evidence-dataset.md what the agent was tested against │ └── execution-logs/ sample run logs ├── scripts/ │ ├── run.sh local execution entry point │ └── seed_evidence.sh set up test evidence └── tests/ └── test_agents.py smoke tests ``` ## 设置 ``` git clone https://github.com/Lona44/find-evil-ir-agent.git cd find-evil-ir-agent # Python 3.12+ python -m venv .venv source .venv/bin/activate pip install -e ".[dev]" # 配置 cp .env.example .env # 设置 ANTHROPIC_API_KEY，可选的 MCP endpoints # 植入测试证据（合成数据 — 来源请参阅 docs/evidence-dataset.md） ./scripts/seed_evidence.sh # 针对已植入的案例运行 ./scripts/run.sh --case demo ``` ## 开发计划 提交窗口为 2026 年 5 月 25 日 → 6 月 15 日。大致规划如下： - **阶段 1 —— 脚手架 + Investigator agent**（目标：第 1 周末） 针对单一证据类型（内存捕获）的“计划-执行-观察”循环。Volatility 3 被封装为工具。基本的引用元组。 - **阶段 2 —— Validator + 自我纠正循环**（目标：第 2 周末） Validator 重新检查 Investigator 的发现。不匹配时触发循环。从 Unified AI Misalignment Framework 移植的幻觉检测评估。 - **阶段 3 —— Reporter + 审计跟踪**（目标：第 3 周末） 结构化的 Markdown 叙述。带有时间戳和 token 使用情况的 JSONL 审计日志。将每个报告声明与特定的工具执行关联起来。 - **阶段 4 —— 演示视频、准确性报告、完善**（目标：6 月 15 日） 现场终端执行演示（≤5分钟，根据规则至少包含一次自我纠正序列）。对误报 / 遗漏的工件 / 幻觉的自我评估。 ## 作者 Ma'alona Mafaufau —— 独立 AI 安全研究员（新西兰奥克兰）。 网站：[approxiomresearch.com](https://approxiomresearch.com)。 ## 许可证 Apache License 2.0 —— 见 [LICENSE](LICENSE)。

标签：AI智能体, LLM评估, Ollama, PyRIT, SOC分析, 多智能体系统, 安全运营, 扫描框架, 自动化应急响应, 请求拦截, 逆向工具