Flor1an-B/SentinelOne-ThreatAnalyser

# SentinelOne Threats Analyzer SentinelOne Threats Analyzer 是一个 Python CLI 工具，它连接到您的 SentinelOne 控制台，提取特定威胁的所有可用取证数据（事件、时间线、Agent 信息），对其进行分析，并同时生成四种输出格式： | 格式 | 描述 | |--------|-------------| | **Terminal** | 基于 Rich 的交互式报告，包含颜色编码的表格、进程树和 SOC 建议 | | **HTML** | 自包含的交互式仪表板 —— 深色 SOC 主题、侧边栏导航、搜索、图表、VT/Shodan 链接 | | **Markdown** | 结构化的分析报告，适用于工单系统、Wiki 和文档 | | **CSV** | 原始事件导出，用于 SIEM 摄取或自定义分析 | ## 功能特性 ### 分析引擎 - **智能叙事** — 动态的分阶段事件重建（初始执行 → 进程链 → 文件系统 → 注册表 → 网络/C2 → 凭据 → 持久化 → 勒索软件 → MITRE Kill Chain → 检测与响应），根据可用数据自动调整，无需 LLM - **执行摘要** — 自动生成的通俗英语叙述，回答 *发生了什么、何时、何地以及如何发生* - **攻击类型分类** — 启发式级联：勒索软件 → 进程注入 → 横向移动 → RAT/C2 → 持久化 → 凭据访问 → MITRE 回退 → 通用恶意软件 - **MITRE ATT&CK 映射** — 从 SentinelOne 指标中提取，包含战术/技术/链接 - **进程树重建** — 从 `processUniqueKey` / `parentProcessUniqueKey` 构建完整的父子执行链 - **加密 / 勒索软件检测** — `.locked` 扩展名启发式检测 + 来自威胁进程的高文件修改量 - **IOC 提取** — 网络 IOC（IP、域名、URL），文件哈希 IOC（SHA1、SHA256、MD5），可疑注册表键 - **威胁进程范围** — 严格的基于种子的过滤（`core_process_keys`）防止兄弟进程和良性后代进程（浏览器、AI 工具、git 等）污染 IOC 和叙述证据，即使 SentinelOne 将整个故事线标记为 `relatedToThreat` - **SOC 建议** — 根据发现生成的上下文相关、按优先级排序的行动项（CRITICAL/HIGH/MEDIUM/LOW） ### HTML 报告 - 深色玻璃拟态 SOC 仪表板（零外部依赖 —— 纯 CSS + 原生 JS） - 侧边栏导航，带有每个部分的事件计数徽章 - 动画统计计数器和事件类型分布条形图 - 可排序表格，每个部分都有实时搜索过滤器 - 所有哈希、IP、路径和命令均可点击复制到剪贴板 - 所有 IOC 值上的 **VirusTotal** 和 **Shodan** 外部查询链接 - “All Events”中的 **仅触发器切换** — 即时隔离与检测相关的事件 - **计划任务** 专用标签页 - **登录异常检测** — 高亮显示 FAILED 登录和 SUSPICIOUS 账户（管理员、来自威胁进程的 INTERACTIVE、NETWORK/BATCH/SERVICE） - 键盘快捷键：`1`–`0` 跳转到部分，`Ctrl+F` 聚焦活动搜索，`?` 打开快捷键模态框 - 打印友好的 CSS ### 终端报告 - 基于 Rich，具有颜色编码的严重性、Unicode 树形视图、键/值面板 - 执行摘要，包含 When? / Origin? / Key Indicators 面板 - 触发检测的命令表 - 带有优先级颜色的 SOC 建议 - 带有 FAILED/SUSPICIOUS 标志的登录异常警告 - 按类别筛选出的与威胁相关进程的事件表 ## 环境要求 - Python **3.9+** - 拥有 API token 的 SentinelOne 控制台访问权限 ``` requests>=2.31.0 rich>=13.7.0 python-dateutil>=2.8.2 urllib3>=2.0.0 ``` 安装： ``` pip install -r requirements.txt ``` ## 快速开始 ### 1. 设置您的 API token（推荐） ``` # Linux / macOS export S1_API_KEY="your_api_token_here" # Windows (PowerShell) $env:S1_API_KEY = "your_api_token_here" # Windows (CMD) set S1_API_KEY=your_api_token_here ``` ### 2. 运行分析器 ``` python main.py \ --url https://your-console.sentinelone.net \ --storyline 0000C2E97648XXXX ``` 如果未设置 `S1_API_KEY`，系统将安全地提示您输入（输入是隐藏的，从不存储）。 ### 3. 查找您的报告 所有报告都保存在一个专用的子文件夹中： ``` /YYYY-MM-DD_HH-MM-SS_/ S1_Events__.csv S1_ThreatReport__.md S1_ThreatReport__.html ``` 示例：`./reports/2026-02-25_14-30-00_0000C2E97648XXXX/` ## 用法 ``` usage: sentinelone_threats_analyzer [-h] -u SERVER_URL -s STORYLINE_ID [-o DIR] [--no-csv] [--no-markdown] [--no-html] [--no-terminal] [-v] required arguments: -u, --url SERVER_URL SentinelOne console URL (e.g. https://your-console.sentinelone.net) -s, --storyline STORYLINE_ID Storyline ID of the threat to analyse output options: -o, --output DIR Output directory (default: current directory) --no-csv Skip CSV export --no-markdown Skip Markdown report --no-html Skip HTML report --no-terminal Skip terminal output -v, --verbose Show full API errors and HTTP debug details ``` ### 示例 ``` # 基础分析，所有报告 python main.py -u https://acme.sentinelone.net -s 0000C2E97648XXXX # 将报告保存到指定文件夹，跳过终端输出 python main.py -u https://acme.sentinelone.net -s 0000C2E97648XXXX -o /var/reports --no-terminal # 仅 HTML 及详细 API 日志 python main.py -u https://acme.sentinelone.net -s 0000C2E97648XXXX --no-csv --no-markdown -v # CI / 非交互模式 S1_API_KEY="$TOKEN" python main.py -u "$S1_URL" -s "$STORYLINE" --no-terminal ``` ## API Token 要求 API token 必须具有以下 SentinelOne 权限： | 范围 | 权限 | |-------|-----------| | Threats | View | | Endpoint Forensics | View | | Threat Forensics | View | ## 项目结构 ``` S1_ThreatAnalyser/ ├── main.py # CLI entry point ├── requirements.txt ├── README.md ├── CHANGELOG.md ├── LICENSE │ └── s1_analyser/ ├── __init__.py ├── api_client.py # SentinelOne REST API v2.1 client │ # – pagination, retry, rate-limit handling ├── data_collector.py # Orchestrates API calls → AnalysisBundle ├── analyzer.py # Core analysis engine │ # – event categorisation │ # – IOC extraction │ # – MITRE ATT&CK mapping │ # – ExecutiveSummary generation │ # – SocRecommendation engine │ # – threat process scoping ├── process_tree.py # ProcessNode tree from event keys │ └── reporters/ ├── terminal_reporter.py # Rich-powered console output ├── csv_reporter.py # Raw events CSV export ├── markdown_reporter.py # Structured Markdown analyst report └── html_reporter.py # Self-contained interactive HTML dashboard ``` ## 工作原理 ``` SentinelOne API v2.1 │ ▼ DataCollector ┌─────────────────────────────────────────────┐ │ GET /threats?storyline__contains= │ → threat info, agent info │ GET /threats/{id}/explore/events (paginated)│ → all forensic events │ GET /threats/{id}/timeline │ → activity timeline └─────────────────────────────────────────────┘ │ ▼ AnalysisBundle ThreatAnalyzer ┌─────────────────────────────────────────────┐ │ categorise_events() → by objectType │ │ build_threat_keys() → seed + ancestors │ │ detect_encryption() → ransomware heur. │ │ extract_mitre() → techniques/links │ │ build_iocs() → net + file hashes │ │ build_executive_summary()→ narrative, chain │ │ build_soc_recommendations()→ action items │ └─────────────────────────────────────────────┘ │ ▼ AnalysisResult ┌──────────┬─────────┬─────────────┬──────────┐ │ Terminal │ CSV │ Markdown │ HTML │ └──────────┴─────────┴─────────────┴──────────┘ ``` ## 输出详情 ### HTML 仪表板部分 | 按键 | 部分 | 描述 | |-----|---------|-------------| | `1` | Overview | 执行摘要、SOC 建议、警报、威胁和主机详情、检测触发器 | | `2` | Narrative | 分阶段的智能事件重建，带有严重性徽章和 MITRE 标签 | | `3` | Process Tree | 交互式可折叠树 —— 红色 = 恶意/触发 | | `4` | All Events | 完整时间线，带搜索 + 仅触发器切换 | | `5` | Files | 文件创建/修改/重命名/删除事件 | | `6` | Registry | 注册表操作（高亮显示持久化键） | | `7` | Network | 连接和 DNS 查询 | | `8` | Login | 带有异常检测的账户活动 | | `9` | Sched. Tasks | 计划任务创建/修改事件 | | `0` | IOCs | 网络 IOC（IP、域名）、文件哈希、可疑注册表键 | | — | MITRE ATT&CK | 按战术分组的技术卡片 | ### Markdown 报告部分 1. Executive Summary (narrative + When/Origin/Key Indicators sub-sections) 2. Incident Narrative (phase-by-phase reconstruction) 3. Threat Details 4. Host Information 5. Detection Analysis 6. MITRE ATT&CK Mapping 7. Process Tree (ASCII) 8. File Activity 9. Registry Activity 10. Network Activity 11. Login & Account Activity 12. Scheduled Tasks 13. Ransomware / Encryption Indicators 14. Indicators of Compromise 15. SOC Analyst Recommendations 16. Attack Timeline (first 100 events) 17. Appendix: Statistics ## 故障排除 | 现象 | 可能原因 | 修复方法 | |---------|-------------|-----| | `Connection failed` | URL 错误或 token 过期 | 验证控制台 URL 包含 `https://`；检查 token 有效期 | | `No threat found for storyline` | ID 错误或缺少权限 | 检查 Storyline ID 前后是否有空格；验证 *Threats View* 权限 | | Zero events collected | 缺少取证权限 | 在 API token 中添加 *Endpoint Forensics* + *Threat Forensics View* | | Windows 上终端输出乱码 | 控制台编码问题 | 该工具会将 stdout 补丁为 UTF-8；如果仍有问题，请先运行 `chcp 65001` | | Empty process tree | 事件仍在处理中 | 等待几分钟后重新运行；部分 Agent 会批量上传事件 | ## 安全说明 - API token **绝不**存储到磁盘、记录到日志或作为 CLI 参数传递 - 所有生成的 HTML 报告都是**完全自包含的**（渲染时不调用外部 CDN）—— 适用于物理隔离环境 - HTML 报告中的外部链接仅在用户明确点击时才向外指向—— 无自动出站调用 ## 许可证 MIT — 见 [LICENSE](LICENSE) ## 作者 **Florian Bertaux**

标签：CLI 工具, Cloudflare, CSV 导出, DAST, EDR, HTML 报告, HTTP/HTTPS抓包, IOC 提取, IP 地址批量处理, Markdown, MITRE ATT&CK, PE 加载器, Python, SentinelOne, 仪表盘, 勒索软件检测, 多模态安全, 威胁分析, 安全运营, 态势感知, 恶意软件分析, 扫描框架, 数字取证, 无后门, 杀伤链, 网络威胁情报, 脆弱性评估, 自动化侦查工具, 自动化脚本, 进程树, 逆向工具, 防御加固