jussiroine/incident-responder
GitHub: jussiroine/incident-responder
一个基于 Microsoft Agent Framework 构建的 AI 安全事件响应演示项目，通过人机协同审批和只读调查与写入响应分离的设计，展示了如何安全地辅助处置安全告警。
Stars: 0 | Forks: 0
# Incident Responder
一个基于 **Microsoft Agent Framework** 1.0 构建的 AI 驱动的安全事件响应演示。它从 Defender XDR 或本地样本文件中提取事件，使用由 LLM 支持的 agent 对其进行调查，提出排序后的响应操作，并通过人机协同 (human-in-the-loop) 审批门对其进行模拟执行。完全通过 CLI 运行。
## 存在的原因
大多数 Agentic AI 演示要么 完全跳过治理，要么 将其过度工程化以至于在台上无法展示。这是一条中间路线：一个可工作的 agent，用于对真实形态的事件进行分类，具备简洁的 HITL（人机协同）审批门、仅追加的审计日志以及只读调查与写入响应之间的清晰分离。您可以将其用作会议演示材料、播客内容，或在关于 AI 护栏的客户交谈中留下的参考架构。
有关设计原理，请参见 [`governance.md`](./governance.md)。
## 快速开始
```
git clone
cd incident-responder
# 推荐：uv 或 virtualenv
python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env
# 编辑 .env：设置 MODEL_PROVIDER 及匹配的 credentials。
# 如果使用无 API key 的 Azure OpenAI：
az login
# 使用 agent 运行单个样本 incident：
incident-responder run --source local --incident impossible_travel
# 或者按顺序运行全部四个样本：
incident-responder run --source local
# 列出可用内容：
incident-responder list-samples
# 查看最新 audit log：
incident-responder show-audit
```
## CLI
```
incident-responder run Triage incidents and propose responses
incident-responder list-samples List bundled sample incidents
incident-responder reset-mocks Reset in-memory tenant state to seed
incident-responder show-state Dump current mock tenant as JSON
incident-responder show-audit Print the latest audit log
```
`run` 接受以下参数：
- `--source local|defender` — 事件来源 (默认为 `local`)
- `--incident NAME` — 仅限 `local` 使用，样本名称 (省略此项则运行全部)
- `--since 1h|24h|7d` — 仅限 `defender` 使用，时间回溯范围
## 模型提供商
在 `.env` 中将 `MODEL_PROVIDER` 设置为以下之一：
| 提供商 | 适用场景 | 必需的环境变量 |
| --- | --- | --- |
| `azure` | 与 Microsoft 相关的演示 | `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`。通过 `AZURE_OPENAI_API_KEY` *或* `az login` 进行身份验证。 |
| `openai` | 快速验证 | `OPENAI_API_KEY` |
| `ollama` | 离线 / 现场演示 | `pip install agent-framework-ollama`，设置 `OLLAMA_HOST` 和 `OLLAMA_MODEL_ID` |
在 WiFi 不稳定的场馆进行演示时，Ollama 选项与 Qwen 2.5 14B 或 Llama 3.1 8B 搭配使用效果极佳。
## 内置样本事件
| 名称 | 场景 | 预期响应形态 |
| --- | --- | --- |
| `impossible_travel` | 异地登录 (13 分钟内从 FI 到 RU，匿名 IP，无 MFA) | 撤销会话 + 强制重置密码 + (考虑封禁) |
| `oauth_consent_grant` | 向未验证的应用授予包含 `Mail.Read` + `Files.Read.All` 的同意 | 撤销 OAuth 授权 + 撤销会话 |
| `mass_sharepoint_download` | 从机密网站下载量达到基准的 22 倍 | 通知管理员 + 撤销会话；如升级则完全封禁 |
| `malware_endpoint` | Defender 检测到具有 lsass 注入的凭证窃取程序 | 隔离设备 + 撤销已登录用户的会话 + 强制重置密码 |
模拟租户预置了三个用户 和两台设备。Charlie 是高风险角色 (无 MFA，曾有风险登录记录)。请参见 `src/incident_responder/mocks/entra_state.py`。
## Defender XDR 模式
`--source defender` 会在 Microsoft Graph 上调用 `GET /security/incidents`。
您需要进行 Entra 应用注册，并具备应用程序权限 `SecurityIncident.Read.All` (已由管理员同意)。在 `.env` 中通过 `DEFENDER_TENANT_ID`、`DEFENDER_CLIENT_ID` 和 `DEFENDER_CLIENT_SECRET` 提供凭据。
此路径是**只读的**。响应操作仍然经过模拟层——有意将它们连接到真实的 Graph 变更排除在此演示的范围之外。
## 审计日志
每次运行都会在 `./audit/run-.jsonl` 中写入一个 JSONL 文件，包含：
- `incident_loaded` — 已分类的内容
- `tool_call` — 每次调查工具的调用及其参数和结果
- `action_proposed` — agent 提出的响应及理由
- `approval_decision` — 分析师的批准/拒绝决定
- `mock_executed` — 生成的状态变更 *以及* 在生产环境中本会触发的等效 Graph API 调用
在与 CISO 讨论治理时，此文件就是交付物。
## 项目布局
```
src/incident_responder/
cli.py Typer + Rich CLI
agent.py ChatAgent factory + system prompt
config.py Env-driven config
sources/ Incident sources (local, Defender XDR)
tools/
investigate.py Read-only tools (free for the agent to call)
respond.py Mock response tools (HITL-gated)
audit.py Append-only JSONL writer
mocks/
entra_state.py In-memory tenant state
samples/ Sample incident JSON files
audit/ Generated at runtime
```
## DevUI
MAF 附带了一个基于浏览器的调试器。要在迭代期间检查 agent 跟踪记录：
```
agent-framework devui
```
然后根据 MAF 文档将其指向 agent 模块。
## 演示流程 (建议)
1. 展示警报量问题——快速展示这四个样本事件。
2. 运行 `--incident impossible_travel`。让观众观看 agent 的调查过程，然后大声读出它的推理。
3. **故意拒绝**第一个提议的操作。展示 agent 是如何确认的，审计日志记录了拒绝过程，并且 agent 会转向下一个提案。
4. 批准其余的操作。展示审计日志文件。
5. 运行 `--incident malware_endpoint` 以展示上下文推理——agent 在这里选择了 `isolate_device`，而在之前的事件中并没有。
6. 以治理框架作为总结：HITL 审批门、审计日志、模型可替换性、模拟层。
## 许可证
MIT。
标签：AI安全护栏, AI风险缓解, AI驱动, Defender XDR, Microsoft Agent Framework, Python, 不可能旅行(Impossible Travel), 事件分级, 人机协同(Human-in-the-loop), 参考架构, 合规与治理, 命令行工具(CLI), 大语言模型(LLM), 威胁调查, 安全事件响应, 安全演练与演示, 安全编排自动化与响应(SOAR), 安全运营(SecOps), 审计日志, 无后门, 自动化响应, 逆向工具