subhsamal/Detection-as-Code-with-AI

# 使用 AI 的 Detection-as-Code **一个生产级、AI 增强的检测与响应平台，基于开源工具构建。** 由 Subhadarshi Samal — 高级检测与响应工程师构建。 ## 项目简介 该平台回答了每一个高级 D&R 面试中都会出现的一个问题：*“你将如何使用开源工具构建世界一流的 SOC 能力？”* 答案不是“安装 Elastic 并写几条规则”。答案是一个闭环系统：遥测数据反馈给检测器，检测器触发 AI agent，agent 产生经过审计的输出，而 agent 本身也成为一个检测面。每个组件都有明确的角色、明确的接口和明确的反馈路径。 这也是一个鲜活的作品集——每个模块都直接映射到 AI 前沿安全组织所看重的技能：检测工程、零信任访问、Agentic AI、LLM 输出审计、REST API 集成以及威胁情报的运营化。 ## 架构概览  ## 仓库结构 ``` Detection-as-Code-with-AI/ │ ├── infra/ # Elastic stack (Docker) │ ├── docker-compose.yml │ ├── .env │ ├── elasticsearch/ │ │ └── elasticsearch.yml │ └── kibana/ │ └── kibana.yml │ ├── telemetry/ # Log sources and simulators │ ├── simulators/ │ │ ├── auth_events.py │ │ └── process_events.py │ └── beyondcorp/ │ └── pomerium.yml │ │ ├── authentik.yml │ │ ├── authentik-db.yml │ ├── detections/ # Detection-as-code │ ├── rules/ │ │ └── *.yml (ES|QL rules with MITRE mapping) │ ├── tests/ │ ├── coverage_map/ │ └── deploy.py │ ├── mcp-server/ # AI tool gateway │ ├── server.py │ ├── tools/ │ │ └── elastic_tools.py │ ├── scope_policy.py │ └── audit_log.py │ ├── agents/ # AI agent roles │ ├── copilot/ │ │ └── rule_copilot.py │ ├── auditor/ │ │ └── rule_auditor.py │ ├── triage_agent/ │ │ └── triage.py │ └── shared/ │ └── redaction.py │ ├── threat-intel/ # CTI pipeline │ ├── stix_ingest.py │ ├── ttp_mapper.py │ ├── gap_finder.py │ ├── draft_rule.py │ └── otx_feed.py │ ├── n8n/ # SOAR-equivalent workflows │ └── workflows/ │ ├── alert_triage.json │ └── alert_enrich.json │ └── .github/ └── workflows/ └── ci.yml # Lint → co-pilot → auditor → deploy ``` ## 组件角色 ### 1. `infra/` — Elastic stack **它是什么：** 数据基础。Elasticsearch 存储所有安全遥测数据、检测规则输出和 AI agent 审计日志。Kibana 提供仪表板、检测规则 UI 以及 ATT&CK 覆盖热力图。 **为什么采用这种方法：** `elastic-start-local` Docker 脚本提供了一个完全可移植、永不过期的 Elastic stack，任何人都可以克隆并通过两条命令运行。没有云试用，也不用在演示到一半时担心许可证过期。整个平台可以在 MacBook 上运行。 **核心接口：** - Elasticsearch REST API (`localhost:9200`) — 被 `detections/deploy.py`、`mcp-server/tools/elastic_tools.py` 和 `mcp-server/audit_log.py` 使用 - Kibana UI (`localhost:5601`) — 用于仪表板和检测规则管理 **在平台中的角色：** 一切都流经 Elasticsearch。遥测数据在此处建立索引。检测规则针对它运行。AI agent 的工具调用被记录回其中。它是整个系统的唯一事实来源。 ### 2. `telemetry/` — 日志源与合成模拟器 **它是什么：** 原始安全信号。包含两个组件：生成真实合成事件的 Python 模拟器（认证失败、进程执行、横向移动模式），以及完整的零信任身份 stack：作为身份提供商 的 Authentik 和作为身份感知代理 的 Pomerium。Authentik 管理用户、组、MFA 并签发 OIDC token。Pomerium 信任这些 token，并在 Kibana、n8n 和 MCP server 管理界面之前强制执行基于路由的访问策略。 **为什么使用模拟器：** 一个没有真实数据的实验室无法产生有意义的检测，也无法产生有意义的 AI 分诊输出。模拟器生成良性的基线流量以及注入的攻击模式（编码的 PowerShell、暴力破解序列、可疑的进程链），以便可以根据看起来真实的遥测数据验证每一条检测规则。 **为什么使用 BeyondCorp/Pomerium：** Pomerium 做出的每一个访问决策——设备状态、身份、上下文——都会成为一条结构化日志，并建立索引到 Elasticsearch 中。这为平台提供了一个零信任日志源，以便针对其编写访问异常检测，同时也让你能够在自己的基础设施上获得相当于 Google BeyondCorp 模型的实操经验。 **核心接口：** - 模拟器通过 REST API 将事件批量索引到 Elasticsearch - Pomerium 将访问日志写入专用的 Elasticsearch 索引中 **在平台中的角色：** 产生供检测器运行测试的遥测数据。BeyondCorp 层增加了一个零信任访问面，该面本身即成为一个检测源。 ### 3. `detections/` — 检测即代码 **它是什么：** 所有检测逻辑都以版本化的 YAML 文件形式存在于此目录中。每条规则都包含 ES|QL 查询、MITRE ATT&CK 映射（战术、技术、子技术）、严重性、响应指南和测试用例。`deploy.py` 通过 REST API 将规则推送到 Elastic 检测引擎。 **为什么使用 YAML + CI/CD：** 检测规则即是代码。它们应归属于版本控制中，并伴随代码审查、自动化测试和部署流水线——这与应用程序代码采用的标准相同。这是“检测即代码”的核心实践，它使得每一次规则更改都是可审计且可回滚的。 **ATT&CK 覆盖图：** 一个 `coverage_map/` 文件夹用于跟踪哪些 MITRE 技术已具备检测覆盖，哪些尚未覆盖。这将直接输入到威胁情报流水线（第 3 阶段）中，并为 Kibana 热力图仪表板提供数据支持。 **核心接口：** - `deploy.py` 调用 Elasticsearch 检测规则 API - CI 流水线 (`ci.yml`) 运行测试，调用 AI 辅助审查 agent 和审计器，然后在合并时执行部署 **在平台中的角色：** 检测层。每一个流入 n8n 和 AI agent 的告警都源于此目录中的某条规则。 ### 4. `mcp-server/` — AI 工具网关 **它是什么：** 一个 Python MCP (Model Context Protocol) server，向 AI agent 公开一组预定义的工具。Agent 与 Elasticsearch、检测规则库或查询性能分析的每一次交互，都必须通过此服务器，绝不直接接触。 **为什么使用 MCP：** MCP 是一项新兴标准，旨在为 AI agent 提供对外部系统的结构化、可审计的访问。构建你自己的 MCP server（而不是使用一次性的 Python 函数）意味着工具集成只需编写一次，任何未来的 agent 都可以复用它们。这也意味着可以在单点进行访问范围的控制、记录和监控。 **暴露的工具：** | 工具 | 作用 | 允许调用者 | |---|---|---| | `search_alerts` | 按严重性、时间、实体查询最近的告警 | 分诊 agent、辅助 agent (只读) | | `run_esql` | 针对 SIEM 执行 ES|QL 查询 | 所有 agent (只读) | | `get_coverage` | 返回 ATT&CK 技术覆盖状态 | 辅助 agent、审计器 | | `list_rules` | 列出已部署的检测规则 | 辅助 agent、审计器 | | `query_profile` | 分析 ES|QL 查询的性能开销 | 仅限审计器 | **`scope_policy.py`：** 为 AI agent 实现最小权限原则。每个 agent 角色都有一个允许其调用的工具白名单。分诊 agent 不能调用 `query_profile`。审计器不能创建或修改规则。这是将针对人类用户的零信任原则同样应用到了 AI agent 身上。 **`audit_log.py`：** Agent 的每一次工具调用都会以结构化的 JSON 日志条目形式，写入到专门的 Elasticsearch 索引 (`mcp-audit-logs`) 中。字段包括：agent 角色、工具名称、参数、响应摘要、时间戳和延迟。这不是可有可无的遥测数据——它是第一级别的安全数据源。 **核心接口：** - 暴露 MCP 协议 endpoint，供 `agents/` 中的 agent 使用 - 通过 REST API 写入 Elasticsearch **在平台中的角色：** AI agent 与平台其余部分之间唯一的受控网关。它强制执行作用域控制，产生审计追踪记录，并使整个 AI 层变得可观测。 ### 5. `agents/` — AI agent 角色 **它是什么：** 三个截然不同的 AI agent，每个都有特定范围的系统 prompt、通过 MCP server 定义的明确工具白名单，以及在 D&R 工作流中的具体职责。 #### 检测规则辅助审查 (`copilot/rule_copilot.py`) 辅助 agent 的工作是协助进行检测工程。当一个新的规则 PR 被打开时，CI 流水线会带着规则内容调用辅助 agent。辅助 agent 会对其进行审查并返回结构化反馈：MITRE ATT&CK 映射的完整性、可能的误报场景、缺失的测试用例、建议的查询改进，以及该规则是否与现有覆盖范围重复。 辅助 agent 不会批准或部署任何东西。它只在 PR 上生成审查评论。由分析师决定如何处理它。 **工具访问权限：** `run_esql`（用于测试查询逻辑）、`list_rules`（用于检查是否存在重复覆盖）、`get_coverage`（用于验证 ATT&CK 映射）。 #### 审计器 (`auditor/rule_auditor.py`) 审计器是双模型批评模式 实际应用的体现。在辅助 agent 产生输出（无论是规则审查、分诊评估还是查询建议）之后，审计器会在其到达分析师或 CI 流水线之前对其进行独立审查。审计器会检查三件事： - **架构完整性：** 提议的规则是否遵循 schema 约定？它是否正确映射到了检测规则数据模型？ - **性能：** 这个 ES|QL 查询是否会非常消耗资源？审计器调用 `query_profile` 获取实际的成本估算，而不是靠猜测。 - **安全风险：** 规则是否产生了盲点？它是否依赖于攻击者可以屏蔽的字段？辅助 agent 的输出中是否包含看起来像 prompt injection 产物的内容？ 审计器的发现将与辅助 agent 的审查一起附加到 PR 评论中。分析师在做决定之前会同时看到两者。 这是 D&R AI 工具中最罕见的能力——大多数团队只使用一个模型并信任其输出。在每一次 AI 输出上运行独立的批评者，并记录两方的发现，是一项具有重大意义的安全控制措施。 **工具访问权限：** `run_esql`、`list_rules`、`get_coverage`、`query_profile`。 #### SOC 分诊 agent (`triage_agent/triage.py`) 分诊 agent 是这三个中最具 Agentic 特性的。当 n8n 将一个复杂的告警路由到 AI 层时，分诊 agent 会接收到（经过脱敏处理的）告警，并运行多步推理循环： 1. 调用 `search_alerts` 提取过去 24 小时内同一实体的相关告警 2. 调用 `run_esql` 检查附加上下文（例如，该用户是否在同一时间窗口内从异常位置进行了认证？） 3. 评估严重性，映射到 ATT&CK 技术，识别出建议的下一步行动 4. 编写结构化的分诊笔记，准确引用哪些工具调用为每个结论提供了依据 5. 将输出返回给 n8n，n8n 会通过 Slack 将结果发送给分析师，或更新 Jira 工单 与 SOAR playbook 的关键区别在于：分诊 agent 会推理要寻找什么，而不仅仅是执行什么。工具调用轨迹是可见的，因此分析师可以看到 agent 的推理过程，而不仅仅是结论。 **`shared/redaction.py`：** 在任何告警数据接触到 AI 模型之前，此模块会剥离或哈希敏感字段（用户名、主机名、IP 地址）。AI 是基于脱敏后的数据进行工作的。脱敏映射保存在内存中，用于在向分析师展示的最终分诊输出中恢复实体名称。这是一种应用于 AI 边界的数据治理控制手段。 **工具访问权限：** `search_alerts`、`run_esql`。 ### 6. `n8n/` — 编排层 **它是什么：** 一个自托管的 n8n 实例，与 Elastic stack 一起在 Docker 中运行。n8n 是 Elastic 触发的告警的第一接收者，并充当轻量级的 SOAR 层。 **为什么要在 MCP server 旁边使用 n8n：** 这两个组件用途不同，不应混为一谈。n8n 处理确定性的、可重复的自动化任务——创建 Jira 工单、向 Slack 发送消息、调用 VirusTotal 进行 IP 富化。这些工作流不需要 AI 推理，也不应消耗 AI API 预算。MCP server 和 AI agent 负责处理非确定性的、需要推理的工作——关联事件、评估意图、编写分诊笔记。 路由决策发生在 n8n 中：如果告警的严重性和类型符合简单的 playbook，n8n 会完全处理它。如果告警需要上下文推理，n8n 会调用 MCP server 的分诊 agent endpoint，并将 agent 的输出反馈给分析师。 **核心工作流：** - `alert_triage.json` — 路由告警，针对复杂情况调用分诊 agent，将分析结果发送到 Slack - `alert_enrich.json` — 在将数据传递给 AI 层之前，使用 VirusTotal、AbuseIPDB 和 Shodan 对告警实体进行富化 **在平台中的角色：** 运维自动化层。让简单的事情保持简单，并将复杂的事情路由到正确的地方。防止 AI 层成为处理日常工作的瓶颈。 ### 7. `threat-intel/` — CTI 流水线 **它是什么：** 一个自动化流水线，用于摄取结构化的威胁情报，将其映射到平台当前的 ATT&CK 检测覆盖范围，识别差距，并使用 AI 辅助审查 agent 为未覆盖的技术起草候选检测规则。 **组件：** - `stix_ingest.py` — 从 TAXII server 拉取 MITRE ATT&CK STIX 数据。解析技术、子技术和相关数据源。 - `otx_feed.py` — 从 AlienVault OTX 拉取最新的威胁报告。提取 pulse 报告中提及的 TTP。 - `ttp_mapper.py` — 将摄取的 TTP 与 Elasticsearch 中的 ATT&CK 覆盖图进行交叉引用。生成未被检测覆盖的技术列表。 - `gap_finder.py` — 根据威胁行为者的相关性（APT 组织当前是否在使用此技术？）、数据源可用性和检测难度，对覆盖差距进行优先级排序。 - `draft_rule.py` — 针对最高优先级的差距，调用辅助 agent 起草候选的 ES|QL 检测规则。草稿在提交到 `detections/rules/` 作为 PR 供分析师审查之前，会经过审计器审核。 **在平台中的角色：** 弥合外部威胁情报与内部检测覆盖之间的闭环。“在对手 TTP 方面保持领先”变成了一个产出可操作检测规则草案的自动化流水线，而不再是一种依赖手动搜索的习惯。 ### 8. `.github/workflows/ci.yml` — CI/CD 流水线 **它是什么：** GitHub Actions 流水线，会在每一个触及 `detections/rules/` 的 PR 上运行。 **流水线阶段：** ``` PR opened │ ▼ 1. Lint validate YAML schema, required fields, MITRE mapping format │ ▼ 2. Co-pilot AI reviews rule quality, flags issues, suggests improvements │ ▼ 3. Auditor AI independently reviews co-pilot output and rule for risk │ ▼ 4. PR comment both reviews posted as a structured comment for analyst │ ▼ 5. Merge (manual approval required) │ ▼ 6. Deploy deploy.py pushes rule to Elastic detection engine ``` **在平台中的角色：** 使检测工程成为一种有纪律、可审计的实践。没有一条规则能在未经 schema 验证、AI 审查、独立审计和人工批准的情况下进入生产环境。 ## 两大标志性能力 ### 双模型批评模式 在这个平台中，每一次 AI 输出在到达人类或生产系统之前，都会经过第二个模型的独立审查。辅助 agent 提议；审计器批评。两个模型都不知道对方会说什么——它们是顺序运行的，不在一个共享的上下文窗口中。审计器的工作是对抗性的：找出辅助 agent 遗漏的内容。 这种模式解决了安全工作流中单模型 AI 的核心故障模式：一个提出了带有细微盲点的检测规则的 AI，自身并没有机制来发现它。而专门针对盲点、查询成本和 schema 完整性进行审查的第二个模型则能做到。 这也是对“你如何审计 AI 生成的输出以确保架构完整性、性能瓶颈和安全风险”的直接回答——这不是事后代码审查，而是 CI 流水线中内置的自动化控制措施。 ### 将 Agent 行为作为检测源 MCP server 的 `audit_log.py` 会将每一次 agent 工具调用以日志形式写入 Elasticsearch 的 `mcp-audit-logs` 中。而 `detections/rules/` 中的检测规则就是针对这个索引编写的。平台时刻监视着它自己的 AI agent。 检测示例： - 分诊 agent 调用 `search_alerts` 时使用的参数看起来像是在进行数据探测（这可能是由于 agent 摄取的恶意日志条目引发的 prompt injection） - 任何 agent 尝试使用超出其作用域白名单的工具（纵深防御——应该被 MCP 层拦截，但这可以检测到是否有漏网之鱼） - 审计器通过率的峰值超过基线两个标准差（可能是系统 prompt 遭到了篡改） - 分诊 agent 产生的结构化输出与其工具调用轨迹存在显著分歧（agent 的推理与证据不一致） 这使得 AI 层本身变成了一个受监控、可检测的攻击面——对于任何处理不受信任数据（安全日志）并产生特权输出（分诊决策、检测规则）的系统来说，这都是一种正确的安全姿态。 ## 实施路线图 ### 第 1 阶段 — 核心平台（第 1-2 周） **目标：** 可运行的端到端演示。告警在 Elastic 中触发 → n8n 路由告警 → 分诊 agent 进行推理 → 分析师看到结构化输出。 | 任务 | 模块 | 交付物 | |---|---|---| | 通过 Docker 部署 Elastic stack | `infra/` | `docker-compose.yml`, `.env`, Kibana 可通过 `localhost:5601` 访问 | | 合成事件模拟器 | `telemetry/simulators/` | `auth_events.py`, `process_events.py` 索引到 Elastic | | 3 个初始检测规则 | `detections/rules/` | 包含 MITRE 映射和测试用例的 ES|QL YAML 规则 | | 规则部署脚本 | `detections/` | `deploy.py` 通过 Elastic REST API 推送规则 | | MCP server — 2 个工具 | `mcp-server/` | `search_alerts` 和 `run_esql` 实现端到端运行 | | MCP 审计日志记录 | `mcp-server/` | `audit_log.py` 将工具调用写入 `mcp-audit-logs` 索引 | | 分诊 agent | `agents/triage_agent/` | 多步循环，脱敏处理，结构化分诊输出 | | 辅助 agent (CI 步骤) | `agents/copilot/` | 审查规则 PR，发布结构化评论 | | 审计器 (CI 步骤) | `agents/auditor/` | 审查辅助 agent 的输出，发布审计结果 | | n8n 告警路由 | `n8n/` | 在 Docker 中运行 n8n，告警 webhook → 路由 → 分诊 agent | | GitHub Actions CI | `.github/workflows/` | Lint → 辅助 agent → 审计器 → 部署流水线 | **第 1 阶段面试故事：** “我基于开源 Elastic 构建了一个检测即代码流水线，其中每一条检测规则在进入生产环境之前，都要经过 AI 辅助 agent 的审查和独立 AI 审计器的审核。AI agent 本身也受到了监控——它们执行的每一次工具调用都会被重新索引到 SIEM 中，并且我编写了针对异常 agent 行为的检测规则。” ### 第 2 阶段 — 零信任访问层（第 3 周） **目标：** 在 Kibana 之前部署 BeyondCorp 风格的 IAP。访问决策成为日志源。 | 任务 | 模块 | 交付物 | |---|---|---| | 在 Docker 中部署 Pomerium IAP | `telemetry/beyondcorp/` | `pomerium.yml │ │ ├── authentik.yml │ │ ├── authentik-db.yml`, Kibana 只能通过 IAP 访问 | | 访问日志摄取 | `telemetry/` | Pomerium 日志被索引到 `beyondcorp-access` Elastic 索引中 | | 访问异常检测规则 | `detections/rules/` | 针对安全工具的异常访问模式触发的 ES|QL 规则 | **第 2 阶段面试故事：** “安全工具本身——Kibana、n8n 仪表板——位于 BeyondCorp 风格的身份感知代理之后。每一个访问决策都会被记录下来，并且我编写了相应的检测规则，如果有人在正常模式之外访问 SOC 工具，就会触发警报。将零信任应用于 SOC 自身的基础设施。” ### 第 3 阶段 — 威胁情报流水线（第 4 周） **目标：** 自动化的 TTP 到覆盖差距流水线，并生成由 AI 起草的检测规则。 | 任务 | 模块 | 交付物 | |---|---|---| | 摄取 MITRE ATT&CK STIX | `threat-intel/` | `stix_ingest.py` 从 TAXII server 拉取数据 | | 摄取 OTX feed | `threat-intel/` | `otx_feed.py` 解析 pulse 报告获取 TTP | | 覆盖差距分析 | `threat-intel/` | `gap_finder.py` 交叉引用覆盖图 | | AI 起草规则流水线 | `threat-intel/` | `draft_rule.py` → 辅助 agent → 审计器 → PR | | ATT&CK 热力图仪表板 | Kibana | 显示已检测和未检测技术的覆盖热力图 | **第 3 阶段面试故事：** “该平台摄取 MITRE ATT&CK STIX 数据和威胁报告，将它们与当前的检测覆盖率进行交叉比对，根据活跃威胁行为者的相关性对缺口进行优先级排序，并使用 AI 为最关键的缺口起草候选规则。分析师看到的是一个 PR，而不是电子表格。” ## 展示的技能 — 映射到面试要求 | 平台能力 | 展示的技能 | |---|---| | Elastic SIEM、ES|QL 规则、通过 REST API 部署 | SIEM 架构，检测工程 | | 结合 GitHub Actions CI 的检测即代码 | DevSecOps，用于安全内容的 CI/CD | | 具有作用域工具访问限制的 MCP server | REST API 集成，AI 工具设计 | | 双模型批评模式（辅助 agent + 审计器） | LLM 输出审计，AI 治理 | | 具有多步推理能力的分诊 agent | Agentic AI，安全工作流中的 LLM 集成 | | 将 Agent 行为索引作为检测源 | 创新的检测工程，AI 安全 | | Kibana 前端的 Pomerium IAP | BeyondCorp / 零信任访问模型 | | 摄取 STIX，TTP 到覆盖差距的流水线 | 威胁情报运营化 | | n8n 编排层 | 相当于 SOAR 的工作流自动化 | | AI 边界之前的脱敏网关 | 数据治理，AI 系统中的 PII 处理 | ## 快速开始（第 1 阶段） 前置条件：在 macOS 上安装至少分配了 8GB 内存的 Docker Desktop，Python 3.11+，以及一个 Claude API key。 ``` # Clone repo git clone https://github.com/subhsamal/Detection-as-Code-with-AI cd Detection-as-Code-with-AI # 启动 Elastic stack cd infra docker compose up -d # 验证 Elasticsearch 是否健康 curl -u elastic:$ES_PASSWORD http://localhost:9200/_cluster/health # 运行 event simulators 以用 synthetic telemetry 填充 Elastic cd ../telemetry/simulators python auth_events.py python process_events.py # Deploy starter detection rules cd ../../detections python deploy.py # 启动 MCP server cd ../mcp-server python server.py # Kibana 现在可通过 http://localhost:5601 访问 ``` *本文档是构建过程中的北极星指标。编写的每一个代码文件、提交的每一个 PR、录制的每一次演示，都可以映射回上述路线图中的某一项任务。*

标签：AI智能体, JSONLines, MIT许可证, 威胁情报, 安全运营, 开发者工具, 扫描框架, 检测与响应, 检测即代码, 请求拦截, 逆向工具, 零信任