alex-milla/Convert-IOCsToSTIX

# Microsoft Sentinel 的 IOC → STIX 2.1 转换器 将 IOC 列表（IP、域名、URL、哈希、邮箱、注册表键）转换为 **STIX 2.1** 格式，以便导入 **Microsoft Sentinel** 威胁情报。 提供两个版本，功能完全相同： | 版本 | 文件 | 平台 | |---|---|---| | PowerShell | `Convert-IOCsToSTIX.ps1` | Windows / PowerShell 5.1+ | | Bash | `convert-iocs-to-stix.sh` | Linux / macOS / WSL | ## 功能 - **自动检测** IOC 类型 —— 无需手动分类 - **去重** —— 不区分大小写，覆盖所有输入文件 - **支持 TLP** —— 嵌入 OASIS STIX 2.1 标记定义 ID - **灵活输入** —— 单个文件、文件夹或多种混合格式 - **拆分输出** —— 按 IOC 类型拆分为单独的 JSON，或合并为单个文件 - **配置持久化** —— 默认设置保存至 `stix_converter_config.json` - **API 上传** —— 直接推送到 Sentinel TI API（可选） - **非交互模式** —— 适用于 cron 任务和流水线 - **日志记录** —— 可选输出到日志文件 ## 支持的 IOC 类型 | STIX 2.1 类型 | 检测规则 | 输出文件 (拆分模式) | |---|---|---| | `ipv4-addr` | IPv4，支持可选 CIDR | `stix_ipv4.json` | | `ipv6-addr` | IPv6，支持可选 CIDR | `stix_ipv6.json` | | `domain-name` | 有效的主机名/域名 | `stix_domains.json` | | `url` | 以 `http/https/ftp` 开头 | `stix_urls.json` | | `file` | 十六进制哈希 —— MD5 (32), SHA-1 (40), SHA-256 (64), SHA-512 (128) | `stix_hashes.json` | | `email-addr` | 标准邮箱格式 | `stix_emails.json` | | `user-account` | `DOMAIN\user` 或 `user@host` 模式 | `stix_users.json` | | `windows-registry-key` | 以 `HK` 开头 (HKLM, HKCU 等) | `stix_registry.json` | ## 支持的输入格式 | 扩展名 | 描述 | |---|---| | `.txt` `.list` `.dat` `.ioc` | 每行一个值。以 `#`、`//` 或 `;` 开头的行被视为注释。 | | `.csv` | 自动检测值列 (`value`, `indicator`, `ioc`, `ip`, `domain`, `hash`, `url`)。如果存在日期列也会读取 (`date`, `first_seen`, `timestamp`)。 | | `.json` | 对象数组。自动检测值字段。跳过已经是 STIX 指标的对象。 | | 文件夹 | 处理文件夹内所有受支持的文件（非递归）。 | ## 系统要求 ### PowerShell 版本 (`Convert-IOCsToSTIX.ps1`) - **PowerShell 5.1** 或 **PowerShell 7+** - 无需外部模块 - 用于 API 上传：需要访问 `sentinelus.azure-api.net` 的网络权限 - 执行策略必须允许本地脚本： ``` Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` 如果是从互联网下载的，请先解除锁定： ``` Unblock-File .\Convert-IOCsToSTIX.ps1 ``` ### Bash 版本 (`convert-iocs-to-stix.sh`) - **Bash 4.0+** - **Python 3**（仅标准库 —— 无需 pip 包） - **curl**（仅在 API 上传时需要） ``` # Debian / Ubuntu sudo apt install python3 curl # RHEL / CentOS sudo dnf install python3 curl ``` 下载后使其可执行： ``` chmod +x convert-iocs-to-stix.sh ``` ## 使用方法 ### 交互模式（菜单） ``` # PowerShell .\Convert-IOCsToSTIX.ps1 ``` ``` # Bash ./convert-iocs-to-stix.sh ``` 两者都会启动一个包含 4 个选项的交互式菜单： ``` 1. Convert file(s) 2. Upload to Sentinel API 3. Configuration 4. Type detection test (single value) 0. Exit ``` ### 非交互 / 流水线模式 ``` # PowerShell — 转换文件夹，按类型拆分输出 .\Convert-IOCsToSTIX.ps1 -InputPath .\iocs -OutputPath .\output -SplitByType # PowerShell — 单个文件，合并输出 .\Convert-IOCsToSTIX.ps1 -InputPath .\indicators.txt -OutputPath .\output ``` ``` # Bash — 转换文件夹，合并输出 (false = 不拆分) ./convert-iocs-to-stix.sh /path/to/iocs /path/to/output false # Bash — 按类型拆分 ./convert-iocs-to-stix.sh /path/to/iocs /path/to/output true ``` ## 菜单详解 ### 选项 1 —— 转换文件 1. 输入文件路径或文件夹路径 2. 输入输出文件夹 3. 选择：单个合并文件或按 IOC 类型拆分 4. 填写元数据（或按 Enter 使用保存的默认值）： - 源名称（例如 `AlienVault`、`Unit42`） - 威胁行为者（例如 `APT28`） - 标签（以逗号分隔） - 置信度（1–100） - TLP 级别（`white` / `green` / `amber` / `red`） - 指标类型（`malicious-activity`、`anomalous-activity`、`attribution`、`compromised`、`benign`、`unknown`） - 有效期（天数） 5. 转换运行并打印摘要 6. 如果已配置 API，会提示立即上传 **转换摘要示例：** ``` Input values : 26 Generated : 25 Duplicates : 1 Unknown/skip : 0 By type: file 25 Output file(s): → C:\Temp\output\stix_indicators.json ``` ### 选项 2 —— 上传到 Sentinel API 如果尚未配置 API，工具会检测到这一情况并提示在菜单内直接进行配置。系统会要求输入： - **Workspace ID**（Sentinel 工作区的 GUID） - **Batch size**（批次大小，默认：每个请求 100 个指标） - **Bearer token**（在上传时作为安全/隐藏输入输入） Bearer token 必须属于在工作区上拥有 **Microsoft Sentinel Contributor** 角色的账户。 ### 选项 3 —— 配置 将所有元数据字段和 API 配置的默认值保存到脚本同级目录下的 `stix_converter_config.json`。这些默认值将作为选项 1 中的预填值使用。 ### 选项 4 —— 类型检测测试 交互式输入任意值，查看其分类方式以及将生成的 STIX 模式。适用于在完整转换运行之前验证边缘情况。 ``` Value: 192.168.1.1 → Detected: ipv4-addr Pattern: [ipv4-addr:value = '192.168.1.1'] Value: https://evil.com/payload → Detected: url Pattern: [url:value = 'https://evil.com/payload'] ``` ## 输出格式 每个输出文件都是一个 STIX 2.1 指标对象的 JSON 数组，符合 [Microsoft Sentinel Threat Intelligence 导入格式](https://learn.microsoft.com/en-us/azure/sentinel/upload-indicators-api)。 示例对象： ``` { "type": "indicator", "id": "indicator--a1b2c3d4-e5f6-7890-abcd-ef1234567890", "spec_version": "2.1", "pattern": "[ipv4-addr:value = '1.2.3.4']", "pattern_type": "stix", "pattern_version": "2.1", "created": "2026-03-08T12:00:00.000Z", "modified": "2026-03-08T12:00:00.000Z", "valid_from": "2026-03-08T12:00:00.000Z", "valid_until": "2027-03-08T12:00:00.000Z", "name": "MySource - 1.2.3.4", "description": "IOC (ipv4-addr) from MySource", "indicator_types": ["malicious-activity"], "revoked": false, "labels": ["ipv4-addr"], "confidence": 75, "lang": "en", "object_marking_refs": ["marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"], "kill_chain_phases": [], "external_references": [], "granular_markings": [], "extensions": {} } ``` ## TLP 标记定义 ID (OASIS STIX 2.1) | 级别 | 标记定义 ID | |---|---| | TLP:WHITE | `marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9` | | TLP:GREEN | `marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da` | | TLP:AMBER | `marking-definition--f88d31f6-486f-44da-b317-01333bde0b82` | | TLP:RED | `marking-definition--5e57c739-391a-4eb3-b6be-7d15ca92d5ed` | ## 配置文件 两个脚本均将配置持久化到脚本目录下的 `stix_converter_config.json`： ``` { "OutputFolder": "C:\\Temp\\output", "ThreatActor": "APT28", "Source": "AlienVault", "Tags": ["ransomware", "c2"], "Confidence": 80, "TLPLevel": "green", "IndicatorTypes": "malicious-activity", "ValidDays": 365, "LogFile": "", "API": { "Enabled": false, "WorkspaceId": "", "Endpoint": "https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01", "BatchSize": 100 } } ``` ## 导入到 Microsoft Sentinel 1. 转到 **Microsoft Sentinel** → **Threat Intelligence** → **Import** 2. 选择 **STIX** 格式 3. 上传生成的 `.json` 文件 或使用工具内置的 API 上传功能（选项 2），直接调用 [Upload Indicators API](https://learn.microsoft.com/en-us/azure/sentinel/upload-indicators-api)。 ## 已知限制 - `user-account` 检测为基础级别 —— 专为 Windows 环境中常见的 `DOMAIN\user` 模式设计 - Sentinel TI API 端点（`sentinelus`）可能因地区而异；如有需要请更新配置中的 `Endpoint` - API 上传需要具有 **Microsoft Sentinel Contributor** 角色的 Bearer token；工具不管理 token 的生命周期 ## 许可证 本项目基于 **MIT License** 发布 —— 可免费使用、修改和分发，无论是否注明出处。 ## 作者 **Alex Milla** — [alexmilla.dev](https://alexmilla.dev) 如果这个工具节省了您的时间，欢迎请喝杯咖啡 ☕ [](https://www.buymeacoffee.com/alexmilla)

标签：AI合规, API集成, Bash, Conpot, EDR, IOC, IPv6, IP 地址批量处理, JSON处理, Linux工具, Microsoft Sentinel, PB级数据处理, PowerShell, STIX 2.1, TLP标记, Windows安全, 信标转换, 入侵指标, 可观测性, 威胁情报, 安全运维, 应用安全, 开发者工具, 数据转换, 格式标准化, 端口探测, 网络安全, 网络调试, 脆弱性评估, 自动化, 隐私保护