aiagentmackenzie-lang/ebm

# EBM — Endpoint Behavior Monitor    EBM 是一个单二进制 endpoint agent，负责收集进程、网络、文件、DNS 和注册表遥测数据 —— 将其标准化为 ECS 风格的 schema —— 在设备上评估行为检测规则 —— 并具备离线弹性，将所有内容流式传输至您的 SIEM。它还内置了用于红紫蓝队对抗验证的对手仿真模块。 **专为配合 [SecurityScarletAI](https://github.com/aiagentmackenzie-lang/securityscarletai) 使用而构建**，但也兼容任何通过 HTTP 摄入数据的 SIEM。 ## 为什么开发此工具 SOC 分析师需要理解从收集到检测全过程的 endpoint 遥测数据。大多数 EDR 工具都是黑盒。EBM 展示了端到端的过程： - **跨平台收集** —— 目前使用 gopsutil 回退方案；eBPF (Linux)、Endpoint Security Framework (macOS)、ETW/Sysmon (Windows) 是目标原生数据源 - **数据标准化** —— 原始 OS 事件 → ECS 风格 schema → 扁平化 SIEM 格式 - **Agent 端检测** —— 在事件离开 endpoint 之前，在本地评估 YAML 规则 - **离线弹性** —— 带有指数退避的 SQLite 队列，事件绝不丢失 - **对手仿真** —— 生成真实的恶意行为，实时验证您的检测能力 ## 架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ EBM Agent │ │ │ │ OS Telemetry APIs │ │ (eBPF / ESF / Sysmon) │ │ │ │ │ ▼ │ │ ┌──────────┐ ┌───────────┐ ┌──────────┐ │ │ │ Collector │→ │ Normalizer │→ │ Rule │ │ │ │ (per-OS) │ │ (ECS/OCSF)│ │ Engine │ │ │ └──────────┘ └─────┬─────┘ └────┬─────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────────────────────┐ │ │ │ SQLite Event Queue │ │ │ │ (pending → sent / failed) │ │ │ └──────────────┬──────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────┐ │ │ │ HTTP Batcher + Backoff │ │ │ │ POST /api/v1/ingest │────→ SIEM │ │ └─────────────────────────────┘ │ │ │ │ ┌──────────────┐ │ │ │ Emulator │ (optional, purple-team CLI) │ │ └──────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## 快速开始 ``` # 为所有平台构建 make build # 配置 cp config.yaml.example config.yaml export SCARLET_TOKEN="your-siem-token" # 运行 agent ./dist/ebm-darwin-arm64 -config config.yaml # 列出已加载的 detection rules ./dist/ebm-darwin-arm64 -config config.yaml -list-rules # 运行 adversary emulation ./dist/ebm-darwin-arm64 -config config.yaml -emulate -technique T1566.001 ./dist/ebm-darwin-arm64 -config config.yaml -emulate -scenario ransomware_sim ``` ### 集成测试 ``` ./scripts/integration_test.sh ``` 启动一个模拟 HTTP 服务器，运行 agent，触发仿真，并验证 SIEM 是否收到事件。 ## 检测规则 规则是位于 `rules/` 目录下的 YAML 文件。每个规则将 MITRE 技术映射到行为条件： ``` id: ebm-rule-001 name: "Office Spawning Suspicious Child Process" description: Detects Office applications launching interpreters or suspicious binaries mitre: technique: "T1566.001" tactic: "Initial Access" severity: high condition: event.type: "process_start" process.parent.name: ["winword.exe", "excel.exe", "powerpnt.exe", "outlook.exe"] process.name: ["cmd.exe", "powershell.exe", "pwsh.exe", "wscript.exe", "mshta.exe"] ``` ### 内置规则 | 规则 | MITRE | 检测内容 | |------|-------|-----------------| | Office 繁衍 | T1566.001 | Word/Excel/PowerPoint 启动 cmd/powershell | | LSASS 访问 | T1003.001 | 可疑进程访问 LSASS（凭证转储） | | 网络 Beaconing | T1071 | 来自异常进程的低抖动出站连接 | | 注册表持久化 | T1547.001 | 对 Run/RunOnce 注册表键的修改 | ### 规则条件语法 | 语法 | 含义 | |--------|---------| | `field: "value"` | 不区分大小写的精确匹配 | | `field: ["a", "b"]` | 匹配列表中的任意值（OR） | | `field\|contains: "str"` | 子字符串匹配 | | `field\|startswith: "str"` | 前缀匹配 | | `field\|endswith: "str"` | 后缀匹配 | | `field\|not_in: ["x", "y"]` | 值不在列表中 | | `field\|not_cidr: "10.0.0.0/8"` | IP 不在 CIDR 范围内 | 规则每 60 秒热重载一次（可配置）。 ## 对手仿真 生成真实的恶意事件，以端到端验证您的检测 pipeline： ``` # 单个 techniques ./ebm -config config.yaml -emulate -technique T1059.001 # PowerShell encoded command ./ebm -config config.yaml -emulate -technique T1566.001 # Office → suspicious child ./ebm -config config.yaml -emulate -technique T1003.001 # LSASS credential dumping ./ebm -config config.yaml -emulate -technique T1547.001 # Registry Run key persistence ./ebm -config config.yaml -emulate -technique T1071 # Network beaconing ./ebm -config config.yaml -emulate -technique T1055 # Process injection # 多步骤场景 ./ebm -config config.yaml -emulate -scenario ransomware_sim ``` 仿真事件会被标记为 `event.type: emulation`，因此它们会与真实检测一起出现在 SIEM 中，并带有明确的标签。 ## 事件 Schema ### 内部 EDR 核心 Schema (ECS 风格) | 字段 | 描述 | |-------|-------------| | `@timestamp` | ISO 8601 事件时间 | | `event.type` | `process_start`, `network_connect`, `file_create`, `registry_set` 等 | | `process.name` | 进程二进制文件名 | | `process.command_line` | 完整命令行 | | `process.parent.name` | 父进程 | | `source.ip` / `destination.ip` | 网络 endpoint | | `user.name` | 执行用户 | | `mitre.technique_id` | ATT&CK 技术 | | `severity` | `info`, `low`, `medium`, `high`, `critical` | ### 扁平化的 SecurityScarletAI 格式 事件在发送前会被扁平化为 SIEM 的摄入 schema： ``` { "@timestamp": "2026-04-23T14:30:00Z", "host_name": "devbox-01", "source": "endpoint_behavior_monitor", "event_category": "process", "event_type": "start", "user_name": "raphael", "process_name": "powershell.exe", "severity": "high" } ``` ## 离线弹性 EBM 绝不会丢失事件。SQLite 队列可确保即使在 SIEM 无法访问时也能完成交付： 1. **标准化** → 以 `pending` 状态写入 `event_queue` 2. **批处理** → 选取最多 50 个待处理事件（可配置） 3. **健康检查** → 刷新前执行 `GET /api/v1/health` 4. **发送** → 使用 Bearer auth 执行 `POST /api/v1/ingest` 5. **返回 202** → 从队列中删除（已交付） 6. **失败时** → 递增 `retry_count`，应用带抖动的指数退避 (`min(300s, 2^n * 1s + rand)`) 7. **重试 5 次后** → 标记为 `failed`，停止重试 ## 配置 完整参考请参见 [`config.yaml.example`](config.yaml.example)。 | 部分 | 键 | 默认值 | 描述 | |---------|-----|---------|-------------| | `agent` | `id` | 自动生成 | UUID；持久化至 `agent.id` | | `siem` | `url` | `http://localhost:8000/api/v1/ingest` | SIEM 摄入 endpoint | | `siem` | `bearer_token` | `${SCARLET_TOKEN}` | 认证 token（环境变量或字面量） | | `siem` | `batch_size` | 50 | 每批次最大事件数 | | `siem` | `flush_interval_sec` | 10 | 刷新间隔秒数 | | `collection` | `process_events` | true | 收集进程启动/停止 | | `collection` | `network_events` | true | 收集网络连接 | | `rules` | `rules_dir` | `./rules` | YAML 检测规则路径 | | `rules` | `reload_interval_sec` | 60 | 热重载间隔 | | `storage` | `db_path` | `./ebm_queue.db` | SQLite 队列路径 | | `storage` | `retention_hours` | 72 | 自动清理时长 | ## 平台数据收集 **当前实现：** 每个 OS 都使用基于 `gopsutil` 构建的 `fallback` 收集器，该收集器每 5 秒轮询一次进程和网络连接。原生平台数据源是目标架构，下面列出了它们及其当前状态。 | 遥测数据 | Windows | Linux | macOS | |-----------|---------|-------|-------| | **进程启动/停止** | Sysmon EID 1/5, ETW ⚠️ 桩代码 | eBPF `execve` tracepoint ⚠️ 桩代码 | ESF `AUTH_EXEC` / `NOTIFY_EXIT` ⚠️ 桩代码 | | **网络连接** | Sysmon EID 3, ETW TcpIp ⚠️ 桩代码 | eBPF `tcp_connect` ⚠️ 桩代码 | ESF `NOTIFY_CONNECT` ⚠️ 桩代码 | | **DNS 查询** | Sysmon EID 22 ⚠️ 桩代码 | eBPF `getaddrinfo` ⚠️ 桩代码 | dnssd / BSM 回退 ⚠️ 桩代码 | | **文件创建/修改/删除** | Sysmon EID 11/23/26 ⚠️ 桩代码 | eBPF `security_file_open` ⚠️ 桩代码 | ESF `NOTIFY_CREATE/RENAME/UNLINK` ⚠️ 桩代码 | | **注册表 / Plist** | Sysmon EID 12/13/14 ⚠️ 桩代码 | crontab/systemd 上的 eBPF ⚠️ 桩代码 | LaunchAgents/LaunchDaemons 上的 ESF ⚠️ 桩代码 | | **镜像/DLL 加载** | Sysmon EID 7 ⚠️ 桩代码 | eBPF `mmap PROT_EXEC` ⚠️ 桩代码 | ESF `NOTIFY_MMAP` ⚠️ 桩代码 | | **跨进程访问** | Sysmon EID 8/10 ⚠️ 桩代码 | eBPF `ptrace` ⚠️ 桩代码 | ESF `task_for_pid` / FSEvents 回退 ⚠️ 桩代码 | ⚠️ = 位于 `internal/collector/` 中的代码补全桩代码，尚未接线或进行运行时验证。目前，回退收集器是唯一活跃的遥测数据源。 ## 构建 ``` make build # All platforms (Linux, Windows, macOS ARM64) make build-linux # Linux amd64 make build-darwin # macOS ARM64 make build-windows # Windows amd64 make test # Run tests make clean # Remove dist/ ``` 每个平台生成单个静态二进制文件。无 CGO，无运行时依赖。 ## 项目结构 ``` cmd/ebm/main.go # CLI entry point internal/ agent/agent.go # Agent lifecycle (start/stop/health) collector/ # Platform telemetry collectors collector.go # Interface + fallback (gopsutil) linux.go # eBPF probes (future) fallback.go # gopsutil-based collection config/config.go # YAML config loader engine/ # Detection rule engine engine.go # Rule matching with modifiers engine_test.go # Unit tests emulator/emulator.go # Adversary emulation (6 techniques + scenarios) model/event.go # Event, IngestEvent, Alert data models normalizer/ # Event normalization normalizer.go # Platform → EDR Core Schema ecs_mapper.go # ECS field mapping pipeline.go # Normalize → enrich → flatten pipeline scarlet_flatten.go # EDR Core → SecurityScarletAI IngestEvent storage/ sqlite.go # Persistent event queue retention.go # Auto-cleanup by age transport/ client.go # HTTP batching + Bearer auth backoff.go # Exponential backoff with jitter rules/ # YAML detection rules scripts/ # Install, integration test, demo ``` ## 与 SecurityScarletAI 集成 EBM 将事件发送至 SecurityScarletAI 的摄入 API： | 约定 | 值 | |----------|-------| | **Endpoint** | `POST /api/v1/ingest` | | **Auth** | `Authorization: Bearer ` | | **Content-Type** | `application/json` | | **成功** | `202 Accepted` | | **批次限制** | 每个请求 50 个事件 | | **WebSocket** | `ws://host:8000/api/v1/ws/logs?token=` | | **来源标签** | `endpoint_behavior_monitor` | 兼容任何通过 HTTP 摄入数据的 SIEM —— 只需将 `siem.url` 指向您的 endpoint 即可。 ## License MIT *属于 [GHOSTWIRE](https://github.com/aiagentmackenzie-lang/GHOSTWIRE) → EBM → [SecurityScarletAI](https://github.com/aiagentmackenzie-lang/securityscarletai) 检测 pipeline 的一部分。*

标签：Docker镜像, EDR, EVTX分析, Go, Ruby工具, 日志审计, 端点安全, 紫队, 脆弱性评估, 行为监控, 补丁管理, 遥测采集