aiagentmackenzie-lang/incident-response-automation

# 🚨 事件响应自动化工具 一个自动化的突发事件响应与分类系统，能够摄取日志、检测威胁并近实时触发响应，设计为适用于现代防御工程的紧凑型 SOAR 风格平台。 本项目是一个轻量级的安全编排、自动化和响应 (SOAR) 引擎，专注于小型环境、实验室和蓝队作品集的**日志驱动事件响应**。它将日志源连接到检测引擎、可选的基于 AI 的分类，以及一个既能**模拟**也能**执行**真实封堵动作的响应层。 该设计强调： - **结构化日志记录与规范化**，使日志机器可读且易于关联。 - **基于规则的检测**，具有清晰、可审计的逻辑，并为后续更高级的分析预留接口。 - **AI 辅助分类**作为丰富层，绝不作为静默决策者。 - **安全自动化模式**，针对高风险操作采用“人在回路” 原则，体现 SOAR 最佳实践。 ## 🔎 执行摘要 此工具展示了 SOC 风格的思维：检测、丰富、封堵和报告。它提供了一个整洁、可扩展的 Node.js 代码库，使用结构化日志和模块化组件，支持批量分析（文件）和近实时流式处理（tail/watch 模式）。 ## 🎯 目标与非目标 ### 目标 - 展示 **SOC 风格思维**：检测、丰富、封堵和报告。 - 提供一个整洁、可扩展的 Node.js 代码库，使用结构化日志和模块化组件。 - 支持**批量分析**（文件）和**近实时流式处理**（tail/watch 模式）。 - 使 AI 分类可插拔（支持 OpenRouter / Claude 或任何 HTTP LLM 后端）。 ### 非目标 - 不是完整的 SIEM 替代品；假设上游已进行日志收集。 - 不是完整的企业级 SOAR；专注于少数高价值剧本（例如，暴力破解、恶意 IP）。 - 不是通用的异常检测引擎；依赖显式规则及可选的 AI 指导。 ## 🧠 功能集 - **日志摄取** - 基于文件（批处理）。 - 流式 / tail 模式用于近实时处理。 - 可插拔解析器（syslog 风格、JSON 日志、自定义文本格式）。 - **检测引擎** - 基于规则的关联和阈值（例如，暴力破解、请求激增）。 - 滑动时间窗口逻辑（例如，T 秒内发生 N 个事件）。 - 按主体（IP、用户、API key）进行有状态跟踪。 - **分类层（AI 辅助，可选）** - 严重性评分和置信度。 - 封堵建议。 - 推理说明以支持分析师审查（无日志不静默自动拦截）。 - **响应引擎** - 模拟或真实 IP 封堵（例如，iptables、云防火墙 API）。 - 本地进程终止和会话标记。 - Webhook 通知（Slack, Teams, 自定义 HTTP endpoint）。 - **报告与可观测性** - 结构化安全事件日志 (JSON)，供下游 SIEM 摄取。 - 每个案件的事件时间线和摘要工件。 - CLI 摘要和机器可读输出。 ## 🔐 检测用例 基线规则具有明确的主观性，直接映射到经典的 SOC 剧本： - **暴力破解认证尝试** - 在滚动时间窗口内来自同一 IP 或用户的多次登录失败。 - 可针对不同环境（实验室 vs 生产）设置可选阈值。 - **可疑 IP 行为** - 访问已知的恶意范围（通过威胁情报源或静态列表）。 - 地理位置异常（例如，不可能的移动模式），当数据可用时。 - **请求 / 事件激增** - 每个 IP、用户或 endpoint 的体量突增——可能是 DoS/撞库攻击。 - **未授权访问模式** - 对敏感 endpoint 的重复 403/401 错误。 - 对已停用 API 或蜜罐路径的访问尝试。 每条规则实现为一个纯函数，消费规范化日志事件并发出 `null` 或 `DetectionEvent` 结构。 ## 🏗️ 高层架构 ``` ┌──────────────────────────┐ │ Log Sources │ │ (files, streams, APIs) │ └────────────┬─────────────┘ │ normalized events ▼ ┌──────────────────────────┐ │ Log Parser │ │ (format → structured) │ └────────────┬─────────────┘ │ events ▼ ┌──────────────────────────┐ │ Detection Engine │ │ (rules, thresholds, etc) │ └────────────┬─────────────┘ │ threats ▼ ┌──────────────────────────┐ │ Classification Layer │ │ (AI optional) │ └────────────┬─────────────┘ │ enriched incidents ▼ ┌──────────────────────────┐ │ Response Engine │ │ (block, kill, notify) │ └────────────┬─────────────┘ │ actions + logs ▼ ┌──────────────────────────┐ │ Reporting & Alerts │ │ (timeline, reports, CLI) │ └──────────────────────────┘ ``` ## 📁 仓库结构 ``` incident-response/ ├── src/ │ ├── parser/ │ │ ├── logParser.js │ │ └── formats/ │ │ ├── textParser.js │ │ └── jsonParser.js │ ├── detection/ │ │ ├── rules.js │ │ └── stateStore.js │ ├── response/ │ │ ├── actions.js │ │ └── integrations/ │ │ └── firewall.js │ ├── ai/ │ │ └── classifier.js │ ├── utils/ │ │ ├── reporter.js │ │ └── logger.js │ ├── config/ │ │ └── default.json │ ├── cli/ │ │ └── index.js │ └── index.js ├── test/ │ └── detection.test.js ├── logs/ │ └── sample-auth.log ├── package.json └── README.md ``` ## 🛠️ 技术栈 - **运行时**: Node.js (LTS) - **日志**: Winston 用于结构化 JSON 安全日志 - **CLI**: Node streams + `readline` 用于高效的文件和 tail 处理 - **测试**: Jest 用于单元测试 - **AI 集成**: 任何 HTTP LLM 提供商（例如，通过 OpenRouter），支持按环境配置 API key ## ⚙️ 安装与设置 ``` # 克隆 repo git clone https://github.com/your-org/incident-response.git cd incident-response # 安装依赖 npm install # 复制并编辑 configuration cp src/config/default.json src/config/local.json ``` 示例 `src/config/default.json`: ``` { "logFormat": "text", "timeWindowSeconds": 60, "bruteForceThreshold": 10, "spikeThreshold": 100, "ai": { "enabled": false, "endpoint": "https://openrouter.ai/api/v1/chat/completions", "model": "your-model-id", "apiKeyEnvVar": "OPENROUTER_API_KEY" }, "response": { "simulate": true, "webhookUrl": null } } ``` 切勿硬编码机密（API key、webhook URL）；通过环境变量或密钥管理器加载它们。 ## 🧪 使用示例 ### 分析日志文件（批量） ``` node src/cli/index.js --file logs/auth.log ``` ### 近实时监控（tail 模式） ``` node src/cli/index.js --file logs/auth.log --watch ``` ### JSON 输出（用于管道传输到其他工具） ``` node src/cli/index.js --file logs/auth.log --json | jq ``` ## 🧱 核心组件 ### 1. 日志解析器 将原始日志行解析为结构化事件： ``` // Text format: "192.168.1.1 - failed login - 2026-03-29T12:34:56Z" const { buildParser } = require('./src/parser/logParser'); const parse = buildParser('text'); const event = parse('192.168.1.1 - failed login - 2026-03-29T12:34:56Z'); // → { ip: '192.168.1.1', event: 'failed login', timestamp: Date, raw: '...' } ``` ### 2. 检测引擎 用于暴力破解检测的滑动窗口计数器： ``` const { detectAll } = require('./src/detection/rules'); // After 10 failed logins from same IP within 60 seconds detectAll({ ip: '10.0.0.1', event: 'failed login', timestamp: new Date() }); // → { type: 'BruteForceLogin', ip: '10.0.0.1', count: 10, ... } ``` ### 3. 响应动作 模拟或真实封堵： ``` const { respondToThreat } = require('./src/response/actions'); // SIMULATE_RESPONSE=true (default) await respondToThreat({ type: 'BruteForceLogin', ip: '10.0.0.1' }); // → [SIMULATE] Would block IP: 10.0.0.1 ``` ### 4. AI 分类（可选） 使用 LLM 分析丰富事件： ``` const { classifyIncident } = require('./src/ai/classifier'); const classification = await classifyIncident(threat); // → { enabled: false, severity: 'MEDIUM', // recommendation: 'Review incident manually; AI not configured.' } ``` ## 📊 示例输出 ``` [INFO] incident_detected {"type":"BruteForceLogin","ip":"192.168.1.10", ...} === INCIDENT DETECTED === Type: BruteForceLogin IP: 192.168.1.10 Count: 25 Severity: MEDIUM Advice: Multiple failed logins from a single IP within 60 seconds. Block IP and investigate associated accounts. [SIMULATE] Would block IP: 192.168.1.10 ``` ## 🔒 安全与隐私考量 - **最小权限**：如果与真实防火墙或基础设施 API 集成，仅使用限定范围的凭证运行此工具。 - **环境隔离**：为实验室、预发布和生产环境维护独立的配置。 - **日志卫生**：避免在事件日志中存储完整的机密、访问令牌或高度敏感的 PII。 - **安全自动化**：首先在**模拟**模式下启动，收集证据，然后有选择地启用真实操作。 - **可审计性**：每个自动操作都记录了时间戳、输入威胁和结果。 ## ✅ 测试策略 ``` # 运行所有测试 npm test # 运行 with coverage npm test -- --coverage ``` 示例测试： ``` const { detectAll } = require('../src/detection/rules'); function buildLog(ip, event, ts) { return { ip, event, timestamp: ts ? new Date(ts) : new Date() }; } test('detects brute force after threshold', () => { const ip = '10.0.0.1'; let threat = null; for (let i = 0; i < 9; i++) { threat = detectAll(buildLog(ip, 'failed login')); expect(threat).toBeNull(); } threat = detectAll(buildLog(ip, 'failed login')); expect(threat).not.toBeNull(); expect(threat.type).toBe('BruteForceLogin'); }); ``` ## 🚀 升级路径 将此转变为旗舰级作品集项目的后续步骤： 1. **实时多源摄取** - 添加 TCP/UDP 监听器用于 syslog。 - 添加 HTTP 摄取 endpoint 用于应用日志。 - 在检测前导入队列（例如，Kafka, Redis streams）。 2. **威胁情报丰富** - 集成免费或付费的 IP/域名信誉源。 3. **仪表盘与案件管理** - 构建一个小型 Web UI 显示活跃事件和时间线。 4. **额外剧本** - 可疑管理员活动。 - API key 滥用检测。 - 来自网络边界日志的 RDP/SSH 暴力破解。 5. **加固与部署** - 使用最小化基础镜像进行容器化。 - 添加 CI 以运行测试、SAST 和依赖检查。 - 提供 Kubernetes manifests 或 Docker Compose。 ## 📄 许可证 MIT ## 参考资料 1. [自动化事件响应：构建有效的 SOAR 剧本](https://johnpemberton.dev/blog/automating-incident-response-soar-playbooks) 2. [什么是 SOAR？4 大核心组件、用例与最佳实践](https://radiantsecurity.ai/learn/what-is-soar-4-core-components-use-cases-and-critical-best-practices/) 3. [关键 SOAR 能力 - Exabeam](https://www.exabeam.com/explainers/siem-security/incident-response-and-automation/) 4. [NodeJS 安全速查表](https://pentest.y-security.de/OWASP%20Cheat%20Sheet%20Series/Nodejs_Security_Cheat_Sheet/) 5. [Nodejs 安全 - OWASP 速查表系列](https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html) 6. [结构化日志记录 - ClickHouse](https://clickhouse.com/resources/engineering/structured-logging) 7. [结构化日志记录：最佳实践与 JSON 示例 - Uptrace](https://uptrace.dev/glossary/structured-logging) 8. [什么是结构化日志记录？ - Nxlog](https://nxlog.co/whitepapers/structured-logging) 9. [日志格式标准：JSON、XML 和键值对解释 - Last9](https://last9.io/blog/log-format/) 10. [安全编排自动化与响应 (SOAR)：完整指南 - Cynet](https://www.cynet.com/incident-response/security-orchestration-automation-and-response-soar-a-quick-guide/) 11. [如何保护 Node.js API 免受常见漏洞影响](https://oneuptime.com/blog/post/2026-01-06-nodejs-api-security-owasp-top-10/view) 12. [工程团队网络安全实践 - LinkedIn](https://www.linkedin.com/top-content/engineering/systems-engineering-cybersecurity-measures/cybersecurity-practices-for-engineering-teams/) 13. [安全软件开发最佳实践 - Hyperproof](https://hyperproof.io/resource/secure-software-development-best-practices/) 14. [OWASP Node.js 最佳实践指南](https://www.nodejs-security.com/blog/owasp-nodejs-best-practices-guide)

标签：AI安全, AMSI绕过, Chat Copilot, GNU通用公共许可证, MITM代理, Node.js, PMD, SOAR, 人工智能辅助分类, 威胁分类, 威胁检测, 安全剧本, 安全运营中心, 实时流处理, 日志规范化, 网络安全, 网络映射, 自动化应急响应, 自定义脚本, 防御工程, 隐私保护