Jaischiefy/threatfox-s1-integration

# ThreatFox 到 SentinelOne 威胁情报集成 一个安全、可用于生产环境的集成方案，用于将来自 ThreatFox 的威胁指标导入 SentinelOne 威胁情报，并带有可选的 STAR 规则生成功能，以检测出站 IOC 匹配。 ## 功能 - ✅ 从 ThreatFox API 拉取当前威胁指标（24小时窗口可配置） - ✅ 规范化并验证指标（IPv4、Domain、URL、SHA-256） - ✅ 导入到 SentinelOne 威胁情报并进行源跟踪 - ✅ 将状态存储在 SQLite 中（避免重复导入活动指标） - ✅ 默认采用 Dry-run 模式（未经明确确认不会进行实时写入） - ✅ 结构化 JSON 日志 - ✅ 针对临时故障的指数退避 + 抖动 - ✅ 遵循 HTTP 429（速率限制）响应 - ✅ 支持账号级别和站点级别的 IOC 范围设定 - ✅ 可按 IOC 类型配置过期时间 - ✅ 包含 inspect、fetch、import、expire、status 命令的 CLI ## 项目结构 ``` threatfox-s1-integration/ ├── main.py # CLI entry point ├── pyproject.toml # Python project metadata ├── .env.example # Environment variable template ├── .gitignore # Git ignore rules ├── README.md # This file ├── threatfox_api.py # ThreatFox API client ├── sentinelone_api.py # SentinelOne API client ├── ioc_validator.py # IOC validation & normalization ├── state.py # SQLite state management ├── logger.py # Structured JSON logging ├── tests/ │ ├── test_validator.py # IOC validator tests │ ├── test_threatfox.py # Mock ThreatFox responses │ └── test_sentinelone.py # Mock S1 responses ├── systemd/ │ ├── threatfox-s1.service # Systemd service unit │ └── threatfox-s1.timer # Systemd timer (4-hour interval) └── docker/ └── Dockerfile # Docker image definition ``` ## 安装说明 ### 前置条件 - Python 3.11+ - pip - SQLite3 ### 设置 ``` git clone cd threatfox-s1-integration # 创建虚拟环境 python3.11 -m venv venv source venv/bin/activate # 安装依赖 pip install -r pyproject.toml # 复制环境模板并配置 cp .env.example .env # 编辑 .env 填入你的 API 凭据 ``` ## 配置 ### 环境变量 **必填项：** ``` THREATFOX_AUTH_KEY=your-threatfox-api-key S1_CONSOLE_URL=https://usea1-020.sentinelone.net S1_API_TOKEN=your-s1-api-token S1_ACCOUNT_ID=your-account-id (optional if using S1_SITE_ID) S1_SITE_ID=your-site-id (optional if using S1_ACCOUNT_ID) ``` **可选项：** ``` MIN_CONFIDENCE=90 # Default: 90 IOC_MAX_AGE_HOURS=24 # Default: 24 IP_EXPIRATION_DAYS=7 # Default: 7 DOMAIN_EXPIRATION_DAYS=14 # Default: 14 URL_EXPIRATION_DAYS=14 # Default: 14 HASH_EXPIRATION_DAYS=30 # Default: 30 MAX_IMPORTS_PER_RUN=250 # Default: 250 (safeguard) BATCH_SIZE=25 # Default: 25 (per POST) LOG_LEVEL=INFO # Default: INFO DRY_RUN=true # Default: true (CRITICAL: set to 'false' to enable writes) STATE_DB=threatfox_s1.db # Default: threatfox_s1.db ``` ## 用法 ### 命令 #### 检查配置 ``` python main.py inspect ``` 显示当前配置、API 连接状态和数据库状态。 #### 获取指标（不导入） ``` python main.py fetch --dry-run ``` 从 ThreatFox 拉取指标、进行验证并去重。输出 JSON 摘要（不写入 S1）。 #### 导入到 SentinelOne（请先进行 Dry-run！） ``` # DRY RUN（请务必先执行此操作！） python main.py import --dry-run # ACTUAL IMPORT（需要明确确认） python main.py import --confirm-write ``` #### 使旧指标过期 ``` # 检查即将过期的内容 python main.py expire --dry-run # 实际移除过期的 IOC python main.py expire --confirm-write ``` #### 状态报告 ``` python main.py status ``` 显示：S1 中的 IOC 总数、活动的 ThreatFox 导入、上次导入时间、状态数据库大小。 #### 测试 SentinelOne 身份验证 ``` python main.py test-s1-auth ``` 验证 API token、账号访问权限和 scope 权限。 #### 测试 IOC 导入（带审查） ``` # 使用 5 个 IOC 进行测试，dry-run 模式 python main.py test-ioc-import --limit 5 # 实际写入测试 IOC（需要明确确认） python main.py test-ioc-import --limit 5 --confirm-write ``` ## Dry-run 模式（默认） **默认情况下禁用所有写入操作。** 要启用写入： 1. 在 `.env` 中设置 `DRY_RUN=false`，或者 2. 在 import/expire/test-ioc-import 命令中传递 `--confirm-write` 标志 Dry-run 模式会记录将要发送的确切 API payload，以便在执行前进行审查。 ## 示例工作流 ``` # 1. 检查配置 python main.py inspect # 2. 测试身份验证 python main.py test-s1-auth # 3. 从 ThreatFox 获取 indicators（不写入） python main.py fetch --dry-run # 4. 审查将要导入的 IOC 样本 python main.py test-ioc-import --limit 5 # 5. 确认无误后，执行正式导入 python main.py import --confirm-write # 6. 检查状态 python main.py status # 7. 安排定期导入（systemd 或 cron） ``` ## Systemd 设置 (Linux) ``` # 复制 service 和 timer sudo cp systemd/threatfox-s1.service /etc/systemd/system/ sudo cp systemd/threatfox-s1.timer /etc/systemd/system/ # 启用并启动 sudo systemctl daemon-reload sudo systemctl enable threatfox-s1.timer sudo systemctl start threatfox-s1.timer # 检查状态 sudo systemctl status threatfox-s1.timer sudo journalctl -u threatfox-s1 -f # Follow logs ``` ## Cron 替代方案 ``` # 每 4 小时 0 */4 * * * cd /opt/threatfox-s1 && python main.py import >> logs/cron.log 2>&1 ``` ## Docker ``` docker build -f docker/Dockerfile -t threatfox-s1:latest . docker run --rm \ -e THREATFOX_AUTH_KEY=$THREATFOX_AUTH_KEY \ -e S1_API_TOKEN=$S1_API_TOKEN \ -e S1_CONSOLE_URL=$S1_CONSOLE_URL \ -e S1_ACCOUNT_ID=$S1_ACCOUNT_ID \ -e DRY_RUN=false \ threatfox-s1:latest import ``` ## 日志记录 日志以 JSON 格式写入 `logs/` 目录，便于解析： ``` { "timestamp": "2026-07-15T16:30:00.123456Z", "level": "INFO", "component": "importer", "message": "Imported 5 new IOCs from ThreatFox", "iocs_imported": 5, "iocs_updated": 2, "iocs_skipped": 3, "duration_seconds": 12.34 } ``` ## 安全限制 ✅ **已执行：** - 默认启用 Dry-run - 不自动创建 STAR 规则 - 无自动响应动作（隔离、终止、修复） - 源代码中没有硬编码的机密 - 所有凭据均来自环境变量或 `.env` - 启用证书验证（不使用 `--insecure`） - SQLite 防止重复导入 - 状态跟踪防止重复导入活动的 IOC ## 已知限制 1. **IOC 创建 API**：在测试期间遇到 S1 POST endpoint 验证错误。可能需要 SentinelOne 支持或租户配置。 - 变通方法：通过控制台 UI 手动上传 - 测试：使用 `test-ioc-import --limit 5` 来验证 payload 2. **STAR 规则生成**：尚未实现。必须在 S1 控制台中手动创建规则。 - 计划中：在 `star-rules/` 目录中提供 STAR 规则模板 3. **Scope**：目前支持账号级别的 scope 设定。即将支持站点级别。 4. **批量大小**：每个 POST 请求限制为 25 个 IOC。大型导入将拆分为多个批次。 ## 故障排除 ### ThreatFox API 错误 - 检查 `THREATFOX_AUTH_KEY` 是否有效 - 验证 API 速率限制（通常为 1000次/天） - 检查 `IOC_MAX_AGE_HOURS` 设置 ### SentinelOne API 错误 - 运行 `python main.py test-s1-auth` 以验证连接 - 检查 `S1_API_TOKEN` 过期时间（8天有效期） - 验证 `.env` 中的账号/站点 ID - 确保账号具有“Threat Intelligence”权限 ### 导入失败 - 检查 `logs/` 目录中的日志 - 使用 `--dry-run` 查看确切的 payload - 首先使用 `test-ioc-import --limit 5` 进行测试 ## 测试 ``` # 运行单元测试 python -m pytest tests/ -v # 使用 mock 数据测试（无实时 API 调用） python -m pytest tests/ --mock ``` ## 未来增强功能 - [ ] STAR 规则自动创建和管理 - [ ] 多源威胁情报（Wiz、Shodan、Censys） - [ ] 基于置信度的严重性评分 - [ ] IOC 过期自动化 - [ ] 用于监控的 Web 仪表板 - [ ] 导入出错时的 Slack/电子邮件警报 - [ ] 站点级别的 scope 支持设定 ## 支持 如有问题、疑问或功能请求： 1. 检查 `logs/` 目录中的日志 2. 运行 `python main.py inspect` 进行诊断 3. 如果 API 错误持续存在，请联系 SentinelOne 支持 ## 许可证 仅供内部使用。请勿分发。 **最后更新：** 2026-07-15 **版本：** 0.1.0 (Beta) **状态：** Dry-run 模式已激活。可安全用于生产环境测试。

标签：API集成, IP 地址批量处理, SentinelOne, SOC运营, ThreatFox, 可观测性, 威胁情报, 开发者工具, 漏洞探测, 网络信息收集, 请求拦截, 逆向工具