vicabsilv/S1-to-STIX-CTI

# SentinelOne CTI Reporter 一个全面的网络威胁情报 (CTI) 报告系统，该系统从 SentinelOne 提取数据，将其转换为 STIX 格式，并使用 OASIS CTI 可视化工具生成可视化报告。 ## 功能 - **数据提取**：从 SentinelOne API 获取告警和威胁 - **STIX 转换**：转换为具有适当关系的 STIX 2.1 格式 - **Hash 丰富**：使用 VirusTotal 将 SHA-1 哈希解析为 SHA-256 - **可视化**：与 cti-stix-visualization 工具集成 - **自动化报告**：支持每天 3 次自动化报告 - **多种输出**：生成 HTML 报告、STIX bundle 和原始数据 ## 前置条件 ### 必备软件 - Python 3.7+ - SentinelOne API 访问权限 - VirusTotal API key（可选，用于 hash 丰富） ### Python 依赖 安装所需的包： ``` pip install -r requirements.txt ``` ### API 凭证 设置环境变量或使用配置文件： ``` # 环境变量 export S1_API_TOKEN="your_sentinelone_api_token" export VT_API_KEY="your_virustotal_api_key" # 或使用 config.json 文件 ``` ## 快速开始 ### 项目结构 本项目包含两个版本： - **`enhanced/`** - 增强版（⭐ **推荐** - 积极维护中） - **根目录** - 原始版本（旧版）和共享文件 ### 1. 设置配置 在根目录下编辑 `config.json`，填入您的 API 凭证： ``` { "s1_api_token": "your_sentinelone_api_token", "vt_api_key": "your_virustotal_api_key", "s1_base_url": "https://usea1-300-nfr.sentinelone.net/web/api/v2.1", "time_window_hours": 8, "output_dir": "cti_reports" } ``` ### 2. 运行单个报告 #### 增强版（推荐） ``` cd enhanced python s1_cti_reporter_enhanced.py --mode full --hours 24 ``` #### 原始版本（旧版） ``` python s1_cti_reporter.py --mode full ``` ### 3. 设置自动化报告（每天 3 次） ``` # Windows python scheduler.py --setup --platform windows # Linux python scheduler.py --setup --platform linux ``` ## 工作原理 增强版 SentinelOne CTI Reporter 遵循一个多阶段 pipeline，将原始威胁数据转化为可操作的 STIX 2.1 情报。以下是每个阶段的详细分解： ### 架构概述 系统由四个主要阶段组成： 1. **数据收集** - 从 SentinelOne API 获取威胁 2. **威胁过滤与分类** - 智能过滤和分类 3. **创建 STIX 对象** - 构建结构化的威胁情报对象 4. **报告生成** - 创建人类可读的报告和 STIX bundle ### 阶段 1：数据收集 (`fetch_threats()`) **目的**：从 SentinelOne API 或现有的 CSV 文件中检索威胁数据。 **流程**： 1. **API 身份验证**： - 从环境变量 (`S1_API_TOKEN`) 或 `config.json` 加载 API token - 创建带有 `Authorization: ApiToken {token}` header 的已验证 HTTP 会话 - 配置 base URL（例如：`https://usea1-300-nfr.sentinelone.net/web/api/v2.1`） 2. **时间窗口计算**： - 根据 `--hours` 参数计算开始/结束时间戳（默认：24 小时） - 将时间戳格式化为 ISO 8601 格式以进行 API 查询 3. **API 请求**： - 向 `/threats` endpoint 发送 GET 请求，包含以下参数： - `limit`：1000（每次请求的最大威胁数） - `createdAt__gte`：开始时间戳 - `createdAt__lte`：结束时间戳 4. **回退到 CSV**： - 如果 API 调用失败或未返回数据，则自动回退到处理现有的 CSV 文件 - 在项目目录中搜索最近的 `*threats*.csv` 文件 5. **原始数据存储**： - 将原始 API 响应保存到 `cti_reports/raw/enhanced_threats_{timestamp}.json` - 保留原始数据结构以供审计和调试 **输出**：来自 SentinelOne API 的原始威胁字典列表 ### 阶段 2：威胁过滤与分类 **目的**：过滤掉误报并对威胁进行分类，以便进行情报处理。 #### 2.1 误报检测 (`_is_false_positive()`) **执行的检查**： 1. **分析员裁定**： - 检查 `threatInfo.analystVerdict`（API 格式）或 `Analyst Verdict`（CSV 格式） - 如果裁定包含 "false_positive" 或 "false positive" 则进行过滤 2. **缓解状态**： - 检查 `threatInfo.mitigationStatus` 是否包含 "marked_as_benign" 或 "marked as benign" - 过滤掉已被手动标记为安全的威胁 3. **模式匹配**： - 对威胁名称/详细信息应用 regex 模式以识别已知的误报： - `CagService.exe` (CentraStage 服务) - `putty.exe` (合法的 SSH 客户端) - `explorer.exe` (Windows 资源管理器) - `RuntimeBroker.exe` (Windows 系统进程) - `svchost.exe` (Windows 系统进程) - `WinRAR.exe`, `7zG.exe` (合法的压缩工具) **结果**：只有需要采取行动的威胁才会进入下一阶段 #### 2.2 威胁分类 (`_categorize_threat()`) **分配的类别**： - **`malware`**：分类包含 "malware"、"ransomware"、"trojan" 或 "backdoor" - **`confirmed_threat`**：置信度为 "malicious" - **`suspicious_activity`**：置信度为 "suspicious" - **`unknown`**：不匹配任何类别（仍会处理，但优先级较低） **数据源**： - `threatInfo.classification`（API 格式）或 `Classification`（CSV 格式） - `threatInfo.confidenceLevel`（API 格式）或 `Confidence Level`（CSV 格式） #### 2.3 MITRE ATT&CK 映射 (`_get_mitre_technique()`) **映射流程**： 1. **基于进程的映射**： - 将 `threatInfo.originatorProcess` 与已知的进程模式进行比对检查： - `cmd.exe` → `T1059.003` (Windows 命令行) - `powershell` → `T1059.001` (PowerShell) - `explorer.exe` → `T1055` (进程注入) - `services.exe` → `T1543.003` (Windows 服务) 2. **Indicator 提取**： - 从 API 响应中解析 `indicators` 数组 - 从 indicator 战术链接中提取 MITRE 技巧 ID - 示例：`https://attack.mitre.org/techniques/T1055/012/` → `T1055.012` 3. **默认回退**： - 如果未找到技巧，则默认为 `T1059`（命令和脚本解释器） **输出**：经过过滤和分类的威胁，附带 MITRE ATT&CK 映射 ### 阶段 3：创建 STIX 对象 (`create_enhanced_stix_objects()`) **目的**：将过滤后的威胁转化为具有适当关系且符合 STIX 2.1 标准的对象。 #### 3.1 数据提取 (`_extract_alert_data()`) **提取的字段**： - **Hashes**：`threatInfo.sha1` 或 `threatInfo.sha256`（出于兼容性考虑优先使用 SHA-1） - **IP 地址**：`agentDetectionInfo.externalIp`, `agentDetectionInfo.agentIpV4` - **Endpoints**：`agentRealtimeInfo.agentComputerName` - **恶意软件名称**：`threatInfo.threatName` - **分类**：`threatInfo.classification` - **置信度**：`threatInfo.confidenceLevel` - **时间戳**：`threatInfo.createdAt` 或 `threatInfo.identifiedAt` - **进程**：`threatInfo.originatorProcess` **格式处理**：自动支持嵌套的 API 格式和平坦的 CSV 格式 #### 3.2 基于 Hash 的去重 **流程**： 1. 按 SHA-1 hash 对威胁进行分组以消除重复项 2. 限制为前 50 个唯一的 hash 以保持 bundle 易于管理 3. 对于每个 hash 组，选择最近的威胁（根据 `createdAt` 时间戳） **结果**：每个唯一的恶意软件 hash 对应一个 STIX 对象 #### 3.3 创建 STIX 对象 **创建的对象**（按顺序）： 1. **Identity 对象**： - 代表“SentinelOne CTI Reporter”系统 - 用作所有其他对象的 `created_by_ref` 2. **File 对象**： - 每个唯一的 hash 对应一个 - 包含 SHA-1 hash 和恶意软件名称 - 示例：带有 `hashes: {SHA-1: "5a206f176f8386203e1052ba4d53921893e231d2"}` 的 `File` 3. **IPv4Address 对象**： - 从威胁的网络信息中提取 - 每个威胁限制为 5 个 IP 以防止 bundle 膨胀 - 示例：`IPv4Address(value: "3.22.119.20")` 4. **DomainName 对象**： - 从与 DNS 相关的字段中提取（如果有） - 示例：`DomainName(value: "malicious-domain.com")` 5. **Infrastructure 对象**： - 代表受影响的 endpoint - 类型："endpoint" - 示例：`Infrastructure(name: "SE-4", infrastructure_types: ["endpoint"])` 6. **Malware 对象**： - 代表恶意软件家族 - `is_family: true` 表示它是一个家族，而不是一个特定的实例 - 示例：`Malware(name: "SentinelOne Malware: DiscordSetup.exe", malware_types: ["Malware"])` 7. **ThreatActor 对象**： - 仅为高置信度威胁创建（`confidenceLevel: "malicious"` 或 "high"） - 类型："crime-syndicate" - 示例：`ThreatActor(name: "Threat Actor - DiscordSetup.exe")` 8. **AttackPattern 对象**： - 代表 MITRE ATT&CK 技巧 - 包含指向 MITRE ATT&CK 数据库的外部参考 - 示例：`AttackPattern(name: "MITRE ATT&CK: T1055.012", external_references: [{source_name: "mitre-attack", external_id: "T1055.012"}])` 9. **Indicator 对象**： - 每个唯一的威胁 hash 对应一个 - 包含与文件 hash 匹配的 STIX 模式 - 模式：`[file:hashes.'SHA-1' = '{hash}']` - 标签包含分类、置信度和类别 10. **ObservedData 对象**： - 将 File 对象链接到观察元数据 - 包含 `number_observed` 计数（该威胁被发现的次数） - 通过 `objects` 属性链接到 File 对象 #### 3.4 关系创建 **创建的关系**（根据 STIX 2.1 规范进行验证）： 1. **Indicator → File**：`indicates` 关系 2. **Indicator → Malware**：`indicates` 关系 3. **Indicator → AttackPattern**：`uses` 关系（仅限于前 3 个模式） 4. **Indicator → ThreatActor**：`attributed-to` 关系（仅限于前 2 个 actor） 5. **File → IPv4Address**：`communicates-with` 关系（仅限于前 5 个 IP） 6. **File → DomainName**：`resolves-to` 关系（仅限于前 3 个 domain） 7. **File → Infrastructure**：`targets` 关系（仅限于前 3 个 endpoint） 8. **Malware → ThreatActor**：`attributed-to` 关系 9. **Malware → AttackPattern**：`uses` 关系 **验证**：所有关系都根据 STIX 2.1 规范进行了验证，以确保： - 源对象类型对于该关系类型有效 - 目标对象类型对于该关系类型有效 - 源对象和目标对象都存在于 bundle 中 **输出**：准备好进行打包的 STIX 2.1 对象列表 ### 阶段 4：报告生成 #### 4.1 创建 STIX Bundle **流程**： 1. 将所有 STIX 对象包装在一个 `Bundle` 容器中 2. 通过格式化美化序列化为 JSON 3. 保存到 `cti_reports/stix/enhanced_stix_bundle_{timestamp}.json` **Bundle 结构**： ``` { "type": "bundle", "id": "bundle--{uuid}", "objects": [ // All STIX objects here ] } ``` #### 4.2 生成 HTML 报告 (`generate_enhanced_report()`) **报告部分**： 1. **页眉**： - 报告标题和生成时间戳 - 渐变样式以增加视觉吸引力 2. **统计仪表板**： - 分析的威胁总数（过滤后） - 创建的 STIX 对象计数 - 唯一恶意软件 hash 计数 - MITRE ATT&CK 映计数 3. **按类别进行威胁分析**： - **确认的威胁**：高置信度的恶意活动 - **可疑活动**：需要调查 - **恶意软件检测**：识别出的恶意软件 - 每个类别都显示一个表格，包含： - 威胁名称 - Hash（已截断） - 受影响的 endpoint - MITRE ATT&CK 技巧 - 状态 - 检测时间 4. **威胁模式**： - 前 5 个 MITRE ATT&CK 技巧（按出现次数） - 前 5 个最活跃的 endpoint（按威胁数量） 5. **页脚**： - 指向 STIX bundle 文件的链接 - 指向 STIX 可视化工具的链接（如果已配置） **样式**：现代 CSS，具有响应式设计、颜色编码的类别以及 MITRE 技巧的徽章样式 #### 4.3 威胁分析 (`_analyze_threats()`) **计算的指标**： - 按类别计数（已确认、可疑、恶意软件） - 唯一 hash 计数 - MITRE 技巧频率（使用 Counter） - Endpoint 活动频率 - 分类分布 **输出文件**： - `cti_reports/reports/enhanced_cti_report_{timestamp}.html` - 人类可读报告 - `cti_reports/stix/enhanced_stix_bundle_{timestamp}.json` - STIX 2.1 bundle - `cti_reports/raw/enhanced_threats_{timestamp}.json` - 原始威胁数据 ### 数据流总结 ``` SentinelOne API ↓ [Stage 1: Data Collection] ↓ Raw Threat Data (JSON/CSV) ↓ [Stage 2: Filtering & Categorization] ├─→ False Positive Detection ├─→ Threat Categorization └─→ MITRE ATT&CK Mapping ↓ Filtered & Categorized Threats ↓ [Stage 3: STIX Object Creation] ├─→ Data Extraction ├─→ Hash Deduplication ├─→ STIX Object Creation └─→ Relationship Validation ↓ STIX 2.1 Objects + Relationships ↓ [Stage 4: Report Generation] ├─→ STIX Bundle Serialization ├─→ HTML Report Generation └─→ Threat Analysis ↓ Final Outputs: ├─→ STIX Bundle (JSON) ├─→ HTML Report └─→ Raw Data Archive ``` ### 关键设计决策 1. **双格式支持**：自动处理 API（嵌套）和 CSV（平坦）格式 2. **智能过滤**：多层误报检测以减少噪音 3. **基于 Hash 的去重**：确保每个唯一的恶意软件实例对应一个 STIX 对象 4. **关系验证**：所有关系都根据 STIX 2.1 规范进行了验证 5. **可扩展性**：应用限制（50 个 hash、5 个 IP、3 个 domain）以保持 bundle 易于管理 6. **向后兼容性**：如果 API 不可用，则回退到 CSV 7. **全面的元数据**：在创建丰富的 STIX 对象的同时保留原始数据 ## 用法 ### 命令行选项 #### 增强版（推荐） ``` python s1_cti_reporter_enhanced.py [OPTIONS] Options: --mode {full,fetch,convert} Operation mode (default: full) --config CONFIG Configuration file path (default: config.json) --hours HOURS Time window in hours (default: 24) --use-existing Use existing CSV data instead of API ``` #### 原始版本 ``` python s1_cti_reporter.py [OPTIONS] Options: --mode {fetch,convert,visualize,report,full} Operation mode (default: full) --config CONFIG Configuration file path --time-window HOURS Time window in hours (default: 8) ``` ### 模式（增强版） - **`full`**：完整流程（获取 → 过滤 → 转换 → 报告） - **`fetch`**：仅从 SentinelOne API 获取数据 - **`convert`**：将现有数据转换为 STIX（需要现有的威胁数据） ### 模式（原始版本） - **`fetch`**：仅从 SentinelOne 获取数据 - **`convert`**：将现有数据转换为 STIX - **`visualize`**：打开 STIX 可视化工具 - **`report`**：从现有的 STIX bundle 生成 HTML 报告 - **`full`**：完整流程（获取 → 转换 → 报告 → 可视化） ### 示例 #### 增强版 ``` # 运行完整 pipeline（推荐） python s1_cti_reporter_enhanced.py --mode full --hours 24 # 获取过去 48 小时的数据 python s1_cti_reporter_enhanced.py --mode full --hours 48 # 使用现有 CSV 数据代替 API python s1_cti_reporter_enhanced.py --mode full --use-existing # 仅获取数据而不进行处理 python s1_cti_reporter_enhanced.py --mode fetch --hours 24 # 使用自定义 config 文件 python s1_cti_reporter_enhanced.py --config my_config.json --mode full ``` #### 原始版本 ``` # 运行完整 pipeline python s1_cti_reporter.py --mode full # 获取过去 24 小时的数据 python s1_cti_reporter.py --mode full --time-window 24 # 使用自定义 config 文件 python s1_cti_reporter.py --config my_config.json # 仅获取数据 python s1_cti_reporter.py --mode fetch ``` ## 输出结构 ### 增强版输出 ``` cti_reports/ ├── raw/ │ └── enhanced_threats_YYYYMMDD_HHMMSS.json # Raw threat data from API ├── stix/ │ └── enhanced_stix_bundle_YYYYMMDD_HHMMSS.json # STIX 2.1 bundle └── reports/ └── enhanced_cti_report_YYYYMMDD_HHMMSS.html # HTML report ``` ### 原始版本输出 ``` cti_reports/ ├── raw/ │ ├── alerts_YYYYMMDD_HHMMSS.json │ └── threats_YYYYMMDD_HHMMSS.csv ├── stix/ │ └── stix_bundle_YYYYMMDD_HHMMSS.json └── reports/ └── cti_report_YYYYMMDD_HHMMSS.html ``` **注意**：所有时间戳均采用 UTC 格式 (YYYYMMDD_HHMMSS) ## 配置 ### 环境变量 - `S1_API_TOKEN`：SentinelOne API token - `VT_API_KEY`：VirusTotal API key ### 配置文件选项 - `s1_api_token`：SentinelOne API token - `vt_api_key`：VirusTotal API key - `s1_base_url`：SentinelOne API base URL - `time_window_hours`：数据收集时间窗口 - `vt_daily_limit`：VirusTotal 每日查询限制 - `vt_minute_limit`：VirusTotal 每分钟查询限制 - `output_dir`：输出目录路径 - `visualization_dir`：cti-stix-visualization 工具的路径 ## 自动化调度 ### Windows 任务计划程序 ``` python scheduler.py --setup --platform windows ``` 创建 3 个每日任务： - 上午 8:00 - 晨报 - 下午 2:00 - 下午报告 - 晚上 8:00 - 晚报 ### Linux Cron ``` python scheduler.py --setup --platform linux ``` 为相同的计划添加 cron 条目。 ## STIX 可视化 系统与 [OASIS CTI STIX 可视化](https://github.com/oasis-open/cti-stix-visualization)工具集成： 1. **自动**：脚本自动打开可视化工具 2. **手动**：在浏览器中打开 `../cti-stix-visualization/index.html` 3. **上传**：上传生成的 STIX bundle 文件 ### 可视化功能 - 交互式图形可视化 - 对象关系映射 - 详细的对象检查 - 自定义图标支持 - 导出功能 ## 报告类型 ### HTML 报告 - 汇总统计数据 - 时间窗口信息 - 指向可视化的直接链接 - 嵌入的 STIX 数据 ### STIX Bundle - 符合 STIX 2.1 标准 - Indicator、File、Process、Relationship - 使用 VirusTotal 数据进行丰富 - 正确的对象关系 ### 原始数据 - 原始的 SentinelOne API 响应 - CSV 威胁导出 - 保留以供分析 ## 故障排除 ### 常见问题 **API Token 问题** ``` Error: S1_API_TOKEN environment variable or config required ``` 解决方案：设置环境变量或更新 config.json **VirusTotal 速率限制** ``` 🚫 VirusTotal daily limit reached ``` 解决方案：在配置中增加每日限制或等待重置 **未找到可视化工具** ``` Visualization tool not found at: ../cti-stix-visualization ``` 解决方案：克隆可视化工具或更新配置中的路径 ### 日志 - 检查 `cti_report.log` 以获取计划任务日志 - 查看控制台输出以获取详细的错误消息 - 检查生成的文件以进行数据验证 ## 安全注意事项 - API token 存储在环境变量或配置文件中 - 不会将数据传输到外部服务器（API 调用除外） - STIX 可视化在浏览器中本地运行 - 原始数据存储在本地 ## 性能 - **数据获取**：8 小时窗口约需 30-60 秒 - **Hash 解析**：每个 hash 约 2-5 秒（有速率限制） - **STIX 转换**：约 10-30 秒 - **报告生成**：约 5-10 秒 ## 贡献 1. Fork 该仓库 2. 创建一个功能分支 3. 进行更改 4. 彻底测试 5. 提交 pull request ## 许可证 该项目基于 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。 ## 🙏 鸣谢 - [OASIS CTI TC](https://www.oasis-open.org/committees/cti/) 提供 STIX 标准 - [cti-stix-visualization](https://github.com/oasis-open/cti-stix-visualization) 提供可视化工具 - SentinelOne 提供 API 访问权限 - VirusTotal 提供 hash 丰富功能

标签：API集成, Python, STIX, 可观测性, 威胁情报, 开发者工具, 无后门, 逆向工具