kogunlowo123/ai-agent-soc-triage
GitHub: kogunlowo123/ai-agent-soc-triage
一个基于 Python 和 LLM 的 SOC 告警分诊 Agent，支持主流 SIEM 平台的告警接入、智能分类、威胁情报关联和自动化响应剧本执行。
Stars: 0 | Forks: 0
# AI Agent SOC Triage
一个基于 Python 的安全运营中心 (SOC) 分诊 Agent，利用 LLM 分析安全告警、提取失陷指标、关联事件、查询威胁情报并执行自动化响应剧本。支持 Splunk、Microsoft Sentinel 和 Elastic SIEM，具备云无关性。
## 架构
```
graph TB
subgraph Ingestion["Alert Ingestion"]
style Ingestion fill:#1a1a2e,stroke:#16213e,color:#fff
Splunk["Splunk
Connector"] style Splunk fill:#e94560,stroke:#0f3460,color:#fff Sentinel["Microsoft Sentinel
Connector"] style Sentinel fill:#1982c4,stroke:#0f3460,color:#fff Elastic["Elastic SIEM
Connector"] style Elastic fill:#2b9348,stroke:#0f3460,color:#fff Webhook["Webhook
Receiver"] style Webhook fill:#e36414,stroke:#0f3460,color:#fff end subgraph Engine["Triage Engine"] style Engine fill:#0f3460,stroke:#16213e,color:#fff IOCExtract["IOC Extractor
IPs, Domains, Hashes"] style IOCExtract fill:#533483,stroke:#0f3460,color:#fff Classifier["Alert Classifier
LLM-Powered"] style Classifier fill:#e94560,stroke:#0f3460,color:#fff ThreatIntel["Threat Intel
VT / AbuseIPDB / OTX"] style ThreatIntel fill:#e36414,stroke:#0f3460,color:#fff Correlator["Event Correlator
Temporal + IOC"] style Correlator fill:#1982c4,stroke:#0f3460,color:#fff end subgraph Response["Automated Response"] style Response fill:#1a1a2e,stroke:#16213e,color:#fff Playbook["Playbook Runner
YAML Playbooks"] style Playbook fill:#2b9348,stroke:#0f3460,color:#fff Ticket["Ticket Creator
Jira / ServiceNow"] style Ticket fill:#533483,stroke:#0f3460,color:#fff Notify["Notifier
Slack / Teams / PD"] style Notify fill:#e36414,stroke:#0f3460,color:#fff end Splunk --> IOCExtract Sentinel --> IOCExtract Elastic --> IOCExtract Webhook --> IOCExtract IOCExtract --> Classifier IOCExtract --> ThreatIntel Classifier --> Correlator ThreatIntel --> Correlator Correlator --> Playbook Correlator --> Ticket Correlator --> Notify TriageResult([Triage Result]) style TriageResult fill:#e94560,stroke:#0f3460,color:#fff Playbook --> TriageResult Ticket --> TriageResult Notify --> TriageResult ``` ## 前置条件 | 要求 | 版本 | 说明 | |---|---|---| | Python | >= 3.11 | 现代类型提示语法所需 | | pip | >= 23.0 | 用于依赖安装 | | OpenAI API key | - | 用于基于 LLM 的告警分类 | | SIEM access | - | Splunk、Sentinel 或 Elastic 凭证 | | Threat intel keys | - | 可选：VirusTotal、AbuseIPDB、OTX | ## 安装 ``` # 克隆仓库 git clone https://github.com/your-org/ai-agent-soc-triage.git cd ai-agent-soc-triage # 创建并激活虚拟环境 python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # 安装依赖 pip install -e ".[webhook,dev]" # 配置环境变量 cp .env.example .env # 编辑 .env 填入 API keys 和 SIEM 凭据 ``` ## 配置 ### 环境变量 | 变量 | 必需 | 默认值 | 描述 | |---|---|---|---| | `OPENAI_API_KEY` | 是 | - | 用于告警分类的 OpenAI API key | | `SIEM_PROVIDER` | 否 | `splunk` | SIEM 平台：`splunk`、`sentinel`、`elastic` | | `SPLUNK_HOST` | 否 | `localhost` | Splunk 实例主机名 | | `SPLUNK_USERNAME` | 否 | - | Splunk 用户名 | | `SPLUNK_PASSWORD` | 否 | - | Splunk 密码 | | `VIRUSTOTAL_API_KEY` | 否 | - | 用于 IOC 查询的 VirusTotal API key | | `ABUSEIPDB_API_KEY` | 否 | - | 用于 IP 信誉查询的 AbuseIPDB API key | | `OTX_API_KEY` | 否 | - | AlienVault OTX API key | | `TICKET_BASE_URL` | 否 | - | Jira/ServiceNow 基础 URL | | `TICKET_API_KEY` | 否 | - | 工单系统 API key | | `TICKET_USERNAME` | 否 | - | 工单系统用户名 | | `SLACK_WEBHOOK_URL` | 否 | - | 用于通知的 Slack 入站 webhook | | `TEAMS_WEBHOOK_URL` | 否 | - | Teams 入站 webhook | | `PAGERDUTY_API_KEY` | 否 | - | PagerDuty Events API 路由 key | ### TriageConfig 选项 | 参数 | 类型 | 默认值 | 描述 | |---|---|---|---| | `llm` | `LLMConfig` | OpenAI GPT-4o | 用于分类的 LLM 提供商 | | `siem` | `SIEMConfig` | Splunk | SIEM 连接设置 | | `threat_intel` | `ThreatIntelConfig` | - | 威胁情报 API keys | | `ticket` | `TicketConfig` | Jira | 工单系统设置 | | `notification` | `NotificationConfig` | Slack | 通知渠道配置 | | `playbook_directory` | `str` | `./playbooks` | YAML 剧本文件路径 | | `auto_respond_threshold` | `str` | `high` | 触发自动响应的最低严重级别 | | `enable_auto_response` | `bool` | `False` | 启用自动剧本执行 | | `max_correlation_window_minutes` | `int` | `60` | 告警关联的时间窗口 | ## 用法示例 ``` from datetime import datetime, timezone from src.analyzers.correlation import SecurityAlert from src.config import TriageConfig from src.triage_engine import TriageEngine # 初始化 Triage 引擎 config = TriageConfig.from_env() engine = TriageEngine(config) # 创建告警 (或从 SIEM 接入) alert = SecurityAlert( alert_id="ALERT-001", source="splunk", title="Multiple Failed Login Attempts from External IP", description="47 failed SSH login attempts from 203.0.113.42 in 5 minutes", timestamp=datetime.now(timezone.utc), severity="high", raw_data={"src_ip": "203.0.113.42", "dest_port": 22}, ) # 运行 Triage 流水线 result = engine.triage(alert) print(f"Severity: {result.classification.severity.value}") print(f"Category: {result.classification.category.value}") print(f"Actionable: {result.is_actionable}") for action in result.classification.recommended_actions: print(f" - {action}") ``` ### 运行示例 ``` # 单条告警分析 python -m examples.analyze_alert # 多条告警批量 Triage python -m examples.batch_triage ``` ## 分步实施指南 1. **安装依赖** -- 按照安装部分设置 Python 环境并安装所有包。 2. **配置 SIEM 连接** -- 为您的平台（Splunk、Sentinel 或 Elastic）设置 SIEM 环境变量。确保网络可以访问 SIEM API endpoints。 3. **设置 LLM 访问权限** -- 配置 `OPENAI_API_KEY`（或其他 LLM 提供商）。告警分类器使用 LLM 确定严重性、类别和建议操作。 4. **配置威胁情报源（可选）** -- 添加 VirusTotal、AbuseIPDB 和/或 AlienVault OTX 的 API keys。这些将用信誉数据丰富从告警中提取的 IOC。 5. **自定义剧本** -- 编辑 `playbooks/` 目录中的 YAML 文件，以匹配您组织的响应流程。在 `PlaybookRunner` 中为您的剧本引用的每种操作类型注册操作处理器。 6. **设置通知** -- 配置 Slack/Teams webhooks 或 PagerDuty 路由 keys。高严重和危急严重级别的告警会自动发送通知。 7. **连接工单系统** -- 配置 Jira 或 ServiceNow 凭证。对于具有完整上下文、IOC 和 MITRE ATT&CK 映射的可操作告警，系统会自动创建工单。 8. **部署** -- 将分诊引擎作为服务运行。使用 webhook 接收器进行实时告警摄取，或按计划轮询您的 SIEM connector。在剧本处理器完全测试后启用 `auto_respond`。 ## 剧本格式 剧本使用 YAML 定义，包含条件步骤： ``` name: Brute Force Response category: brute_force severity_threshold: medium steps: - name: Block Source IP action: block_ip parameters: duration_hours: 24 condition: "confidence > 0.7" on_failure: continue ``` ## 文档链接 - [LangChain Extraction](https://python.langchain.com/docs/use_cases/extraction/) -- 用于告警分类的结构化数据提取模式。 - [Splunk REST API](https://docs.splunk.com/Documentation/Splunk/latest/RESTREF/RESTsearch) -- Splunk connector 的 Splunk 搜索作业 API 参考。 - [Microsoft Sentinel Data Sources](https://learn.microsoft.com/en-us/azure/sentinel/connect-data-sources) -- Sentinel 事件和告警 API。 - [Elasticsearch REST APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html) -- Elastic 搜索和检测信号 API。 ## 项目结构 ``` ai-agent-soc-triage/ ├── src/ │ ├── triage_engine.py # Main triage pipeline orchestrator │ ├── config.py # Configuration management │ ├── analyzers/ │ │ ├── alert_classifier.py # LLM-powered severity/category classification │ │ ├── ioc_extractor.py # Regex-based IOC extraction │ │ ├── threat_intel.py # VirusTotal/AbuseIPDB/OTX lookups │ │ └── correlation.py # Temporal and IOC-based event correlation │ ├── connectors/ │ │ ├── splunk.py # Splunk REST API connector │ │ ├── sentinel.py # Microsoft Sentinel connector │ │ ├── elastic.py # Elastic Security connector │ │ └── webhook.py # Generic webhook receiver │ └── responders/ │ ├── playbook_runner.py # YAML playbook execution engine │ ├── ticket_creator.py # Jira/ServiceNow ticket creation │ └── notifier.py # Slack/Teams/PagerDuty/Email notifications ├── playbooks/ │ ├── phishing.yaml # Phishing response playbook │ ├── malware.yaml # Malware containment playbook │ └── brute_force.yaml # Brute force response playbook ├── examples/ │ ├── analyze_alert.py # Single alert triage example │ └── batch_triage.py # Batch processing example ├── requirements.txt ├── pyproject.toml ├── LICENSE └── CHANGELOG.md ``` ## 许可证 本项目采用 MIT License 授权。详情请参见 [LICENSE](LICENSE)。
Connector"] style Splunk fill:#e94560,stroke:#0f3460,color:#fff Sentinel["Microsoft Sentinel
Connector"] style Sentinel fill:#1982c4,stroke:#0f3460,color:#fff Elastic["Elastic SIEM
Connector"] style Elastic fill:#2b9348,stroke:#0f3460,color:#fff Webhook["Webhook
Receiver"] style Webhook fill:#e36414,stroke:#0f3460,color:#fff end subgraph Engine["Triage Engine"] style Engine fill:#0f3460,stroke:#16213e,color:#fff IOCExtract["IOC Extractor
IPs, Domains, Hashes"] style IOCExtract fill:#533483,stroke:#0f3460,color:#fff Classifier["Alert Classifier
LLM-Powered"] style Classifier fill:#e94560,stroke:#0f3460,color:#fff ThreatIntel["Threat Intel
VT / AbuseIPDB / OTX"] style ThreatIntel fill:#e36414,stroke:#0f3460,color:#fff Correlator["Event Correlator
Temporal + IOC"] style Correlator fill:#1982c4,stroke:#0f3460,color:#fff end subgraph Response["Automated Response"] style Response fill:#1a1a2e,stroke:#16213e,color:#fff Playbook["Playbook Runner
YAML Playbooks"] style Playbook fill:#2b9348,stroke:#0f3460,color:#fff Ticket["Ticket Creator
Jira / ServiceNow"] style Ticket fill:#533483,stroke:#0f3460,color:#fff Notify["Notifier
Slack / Teams / PD"] style Notify fill:#e36414,stroke:#0f3460,color:#fff end Splunk --> IOCExtract Sentinel --> IOCExtract Elastic --> IOCExtract Webhook --> IOCExtract IOCExtract --> Classifier IOCExtract --> ThreatIntel Classifier --> Correlator ThreatIntel --> Correlator Correlator --> Playbook Correlator --> Ticket Correlator --> Notify TriageResult([Triage Result]) style TriageResult fill:#e94560,stroke:#0f3460,color:#fff Playbook --> TriageResult Ticket --> TriageResult Notify --> TriageResult ``` ## 前置条件 | 要求 | 版本 | 说明 | |---|---|---| | Python | >= 3.11 | 现代类型提示语法所需 | | pip | >= 23.0 | 用于依赖安装 | | OpenAI API key | - | 用于基于 LLM 的告警分类 | | SIEM access | - | Splunk、Sentinel 或 Elastic 凭证 | | Threat intel keys | - | 可选：VirusTotal、AbuseIPDB、OTX | ## 安装 ``` # 克隆仓库 git clone https://github.com/your-org/ai-agent-soc-triage.git cd ai-agent-soc-triage # 创建并激活虚拟环境 python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # 安装依赖 pip install -e ".[webhook,dev]" # 配置环境变量 cp .env.example .env # 编辑 .env 填入 API keys 和 SIEM 凭据 ``` ## 配置 ### 环境变量 | 变量 | 必需 | 默认值 | 描述 | |---|---|---|---| | `OPENAI_API_KEY` | 是 | - | 用于告警分类的 OpenAI API key | | `SIEM_PROVIDER` | 否 | `splunk` | SIEM 平台：`splunk`、`sentinel`、`elastic` | | `SPLUNK_HOST` | 否 | `localhost` | Splunk 实例主机名 | | `SPLUNK_USERNAME` | 否 | - | Splunk 用户名 | | `SPLUNK_PASSWORD` | 否 | - | Splunk 密码 | | `VIRUSTOTAL_API_KEY` | 否 | - | 用于 IOC 查询的 VirusTotal API key | | `ABUSEIPDB_API_KEY` | 否 | - | 用于 IP 信誉查询的 AbuseIPDB API key | | `OTX_API_KEY` | 否 | - | AlienVault OTX API key | | `TICKET_BASE_URL` | 否 | - | Jira/ServiceNow 基础 URL | | `TICKET_API_KEY` | 否 | - | 工单系统 API key | | `TICKET_USERNAME` | 否 | - | 工单系统用户名 | | `SLACK_WEBHOOK_URL` | 否 | - | 用于通知的 Slack 入站 webhook | | `TEAMS_WEBHOOK_URL` | 否 | - | Teams 入站 webhook | | `PAGERDUTY_API_KEY` | 否 | - | PagerDuty Events API 路由 key | ### TriageConfig 选项 | 参数 | 类型 | 默认值 | 描述 | |---|---|---|---| | `llm` | `LLMConfig` | OpenAI GPT-4o | 用于分类的 LLM 提供商 | | `siem` | `SIEMConfig` | Splunk | SIEM 连接设置 | | `threat_intel` | `ThreatIntelConfig` | - | 威胁情报 API keys | | `ticket` | `TicketConfig` | Jira | 工单系统设置 | | `notification` | `NotificationConfig` | Slack | 通知渠道配置 | | `playbook_directory` | `str` | `./playbooks` | YAML 剧本文件路径 | | `auto_respond_threshold` | `str` | `high` | 触发自动响应的最低严重级别 | | `enable_auto_response` | `bool` | `False` | 启用自动剧本执行 | | `max_correlation_window_minutes` | `int` | `60` | 告警关联的时间窗口 | ## 用法示例 ``` from datetime import datetime, timezone from src.analyzers.correlation import SecurityAlert from src.config import TriageConfig from src.triage_engine import TriageEngine # 初始化 Triage 引擎 config = TriageConfig.from_env() engine = TriageEngine(config) # 创建告警 (或从 SIEM 接入) alert = SecurityAlert( alert_id="ALERT-001", source="splunk", title="Multiple Failed Login Attempts from External IP", description="47 failed SSH login attempts from 203.0.113.42 in 5 minutes", timestamp=datetime.now(timezone.utc), severity="high", raw_data={"src_ip": "203.0.113.42", "dest_port": 22}, ) # 运行 Triage 流水线 result = engine.triage(alert) print(f"Severity: {result.classification.severity.value}") print(f"Category: {result.classification.category.value}") print(f"Actionable: {result.is_actionable}") for action in result.classification.recommended_actions: print(f" - {action}") ``` ### 运行示例 ``` # 单条告警分析 python -m examples.analyze_alert # 多条告警批量 Triage python -m examples.batch_triage ``` ## 分步实施指南 1. **安装依赖** -- 按照安装部分设置 Python 环境并安装所有包。 2. **配置 SIEM 连接** -- 为您的平台（Splunk、Sentinel 或 Elastic）设置 SIEM 环境变量。确保网络可以访问 SIEM API endpoints。 3. **设置 LLM 访问权限** -- 配置 `OPENAI_API_KEY`（或其他 LLM 提供商）。告警分类器使用 LLM 确定严重性、类别和建议操作。 4. **配置威胁情报源（可选）** -- 添加 VirusTotal、AbuseIPDB 和/或 AlienVault OTX 的 API keys。这些将用信誉数据丰富从告警中提取的 IOC。 5. **自定义剧本** -- 编辑 `playbooks/` 目录中的 YAML 文件，以匹配您组织的响应流程。在 `PlaybookRunner` 中为您的剧本引用的每种操作类型注册操作处理器。 6. **设置通知** -- 配置 Slack/Teams webhooks 或 PagerDuty 路由 keys。高严重和危急严重级别的告警会自动发送通知。 7. **连接工单系统** -- 配置 Jira 或 ServiceNow 凭证。对于具有完整上下文、IOC 和 MITRE ATT&CK 映射的可操作告警，系统会自动创建工单。 8. **部署** -- 将分诊引擎作为服务运行。使用 webhook 接收器进行实时告警摄取，或按计划轮询您的 SIEM connector。在剧本处理器完全测试后启用 `auto_respond`。 ## 剧本格式 剧本使用 YAML 定义，包含条件步骤： ``` name: Brute Force Response category: brute_force severity_threshold: medium steps: - name: Block Source IP action: block_ip parameters: duration_hours: 24 condition: "confidence > 0.7" on_failure: continue ``` ## 文档链接 - [LangChain Extraction](https://python.langchain.com/docs/use_cases/extraction/) -- 用于告警分类的结构化数据提取模式。 - [Splunk REST API](https://docs.splunk.com/Documentation/Splunk/latest/RESTREF/RESTsearch) -- Splunk connector 的 Splunk 搜索作业 API 参考。 - [Microsoft Sentinel Data Sources](https://learn.microsoft.com/en-us/azure/sentinel/connect-data-sources) -- Sentinel 事件和告警 API。 - [Elasticsearch REST APIs](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html) -- Elastic 搜索和检测信号 API。 ## 项目结构 ``` ai-agent-soc-triage/ ├── src/ │ ├── triage_engine.py # Main triage pipeline orchestrator │ ├── config.py # Configuration management │ ├── analyzers/ │ │ ├── alert_classifier.py # LLM-powered severity/category classification │ │ ├── ioc_extractor.py # Regex-based IOC extraction │ │ ├── threat_intel.py # VirusTotal/AbuseIPDB/OTX lookups │ │ └── correlation.py # Temporal and IOC-based event correlation │ ├── connectors/ │ │ ├── splunk.py # Splunk REST API connector │ │ ├── sentinel.py # Microsoft Sentinel connector │ │ ├── elastic.py # Elastic Security connector │ │ └── webhook.py # Generic webhook receiver │ └── responders/ │ ├── playbook_runner.py # YAML playbook execution engine │ ├── ticket_creator.py # Jira/ServiceNow ticket creation │ └── notifier.py # Slack/Teams/PagerDuty/Email notifications ├── playbooks/ │ ├── phishing.yaml # Phishing response playbook │ ├── malware.yaml # Malware containment playbook │ └── brute_force.yaml # Brute force response playbook ├── examples/ │ ├── analyze_alert.py # Single alert triage example │ └── batch_triage.py # Batch processing example ├── requirements.txt ├── pyproject.toml ├── LICENSE └── CHANGELOG.md ``` ## 许可证 本项目采用 MIT License 授权。详情请参见 [LICENSE](LICENSE)。
标签：DevSecOps, DLL 劫持, Elastic SIEM, FOFA, GPT, IT运维, Microsoft Sentinel, Petitpotam, PFX证书, Python安全工具, SIEM集成, Socks5代理, SOC自动化, 上游代理, 事件关联分析, 人工智能, 入侵指标, 大语言模型, 威胁情报, 安全运营, 安全运营中心, 开发者工具, 扫描框架, 攻击检测, 数字取证, 智能分诊, 构建工具, 漏洞管理, 用户模式Hook绕过, 网络安全, 网络映射, 自动化剧本, 自动化脚本, 逆向工具, 隐私保护