TDO 独立提取器

一款功能强大的独立命令行工具，利用具有高级结构化输出能力的大语言模型从文档中提取网络威胁情报（CTI）。

🚀 功能特性

• 多格式文档支持：PDF、DOCX、TXT 和 Markdown 文件
• 高级 LLM 集成：Google Gemini 模型，具备结构化输出和自动回退解析能力
• 全面的 CTI 模式：12 种实体类型和 24 种关系类型，附带丰富属性
• 检测机会生成：创建可操作、有证据支持的网络威胁检测规则
• 攻击流合成：生成基于证据的 MITRE ATT&CK 流程图
• 结构化输出可靠性：Pydantic 模式，100% JSON 解析成功率
• 并行处理：同时处理多个文件，带有进度跟踪
• 便携自包含：依赖最少，基于环境变量配置

📋 快速入门

1. 安装

# 克隆或下载 standalone-tdo 文件夹
cd standalone-tdo

# 创建虚拟环境（推荐）
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上: .venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

2. 配置

本工具使用通过 .env 文件加载的环境变量进行配置：

# 复制示例配置文件
cp env.example .env

# 用您的设置编辑 .env
# 必需变量：
GEMINI_API_KEY=your-google-ai-api-key-here
GEMINI_MODEL=gemini-2.5-flash

获取 Gemini API 密钥：

1. 访问 Google AI Studio
2. 创建一个新的 API 密钥
3. 将密钥复制到您的 .env 文件中

可用模型：

• gemini-2.5-flash-preview-05-20（推荐 - 快速且经济实惠）
• gemini-2.5-pro-preview-06-05（更强大，较慢）

3. 基本用法

# 处理单个文件并启用所有功能
python tdo_bulk.py report.pdf --flow --opps

# 处理多个文件
python tdo_bulk.py file1.pdf file2.docx file3.txt

# 使用并行工作进程处理目录中的所有文件
python tdo_bulk.py reports/ -j 4

# 生成包含评估的综合分析
python tdo_bulk.py report.pdf --flow --opps --eval-opps

🎯 命令行参考

usage: tdo_bulk.py [options] FILE [FILE ...]

位置参数：
  FILE                  一个或多个要处理的文件或目录

核心选项：
  -o, --output DIR      输出目录（默认：./extracted_data）
  --csv FILE            将摘要导出为 CSV 文件
  -j, --jobs N          并行工作进程数（默认：1）
  --retries N           LLM 重试次数（默认：2）
  --backoff SEC         指数退避基数（默认：1.5）

分析功能：
  --flow                生成攻击流 JSON
  --opps                生成威胁检测机会
  --eval-opps           评估检测机会的质量
  --debug-opps          显示机会生成的调试信息

输出控制：
  -q, --quiet           最小化控制台输出
  -v, --verbose         调试级别日志
  -h, --help            显示帮助信息并退出

示例命令

# 基本 CTI 提取
python tdo_bulk.py threat_report.pdf

# 启用所有功能的全面分析
python tdo_bulk.py apt_report.pdf --flow --opps --eval-opps

# 使用并行工作进程进行批处理
python tdo_bulk.py reports_folder/ -j 8 --flow --opps

# 将结果导出到 CSV
python tdo_bulk.py *.pdf --csv results.csv

# 用于自动化的静默模式
python tdo_bulk.py reports/ -q -o /var/soc/cti --opps

📊 输出文件

对于每个处理的文件，工具会生成：

主要输出

• {filename}_extracted.json：包含全面模式的结构化 CTI 数据
• {filename}_{timestamp}.md：包含所有分析的可读 Markdown 报告

可选输出（通过标志启用）

• 攻击流 JSON：基于证据的 MITRE ATT&CK 流程结构（使用 --flow）
• 检测机会：带有证据的可操作检测规则（使用 --opps）

🔍 CTI 模式概览

实体类型（12 种）

关系类型（24 种）

归因与行为体关系：

• USES_TOOL, USES_TECHNIQUE, CONDUCTS, ATTRIBUTED_TO, TARGETS

技术关系：

• TOOL_IMPLEMENTS_TECHNIQUE, HOSTS_ON, COMMUNICATES_WITH, VARIANT_OF
• DROPS, DOWNLOADS, INDICATES, OBSERVED_ON, EXPLOITS

高级关系：

• MITIGATES, DETECTS, IS_SUBTECHNIQUE_OF, FLOW_CONTAINS_STEP
• FLOW_USED_BY_ACTOR, OBSERVES, SOURCED_FROM

所有关系均支持 confidence、source、first_seen、last_seen 等属性。

💡 检测机会

工具生成基于证据的检测机会，具有以下特点：

核心功能

• 技术映射：链接到具体的 MITRE ATT&CK 技术
• 可观察工件：用于检测的具体指标
• 行为模式：需要监控的序列和模式
• 证据引用：直接引用源报告中的引文
• 置信度分数：可靠性评估（0.0-1.0）
• 质量评估：自动评分，附带标准细分

示例输出

{
  "id": "opp-001",
  "name": "Detect PowerShell Process Injection",
  "technique_id": "T1055",
  "artefacts": ["powershell.exe with WriteProcessMemory calls"],
  "behaviours": ["Process injection into legitimate processes"],
  "rationale": "APT groups commonly use PowerShell for process injection",
  "confidence": 0.8,
  "source": "PowerShell used for process injection (T1055)",
  "evidence": [
    "• PowerShell executes WriteProcessMemory calls (line 45)",
    "• Relationship: ThreatActor USES_TECHNIQUE T1055"
  ]
}

🔗 攻击流合成

增强的攻击流提供了：

• 基于证据的排序：步骤有时间和因果证据支持
• 实体引用：每个步骤引用提取的 CTI 实体
• 显式推理：步骤排序的合理性说明，附带引用
• 全面覆盖：最多 25 个步骤，覆盖完整攻击生命周期

示例攻击流

{
  "flow": {
    "label": "AttackFlow",
    "pk": "attack-flow--uuid",
    "properties": {
      "name": "APT29 Multi-stage Attack",
      "description": "Sophisticated spear-phishing to data exfiltration flow"
    }
  },
  "steps": [
    {
      "order": 1,
      "entity": {"label": "Technique", "pk": "T1566.001"},
      "description": "Spear-phishing attachment delivery",
      "reason": "Initial access method cited in report section 2.1"
    }
  ]
}

🏗️ 架构概览

核心组件

🎯 主 CLI (tdo_bulk.py)

• 带有参数解析和环境验证的入口点
• 使用 python-dotenv 加载 .env 配置
• 协调批量处理，带有进度跟踪

⚙️ 批量运行器 (tdo_bulk_runner.py)

• 使用 ThreadPoolExecutor 管理并行处理
• 协调提取流水线各个阶段
• 处理进度回调和错误恢复

🧠 CTI 提取器 (tdo_core/extractors/report_processor.py)

• 文档解析：多格式支持（PDF、DOCX、TXT、MD）
• LLM 集成：Google Gemini 结构化输出
• 回退解析：结构化输出失败时的手动 JSON 解析
• 令牌管理：大文档自动分块
• 模式验证：Pydantic 模型确保数据一致性

🔍 TDO 生成器 (tdo_core/detection/opportunity_generator.py)

• 基于证据的检测机会创建
• MITRE ATT&CK 技术映射
• 质量评估，附带评分标准
• 调试模式，用于详细分析

🌊 攻击流合成器 (tdo_core/flows/attack_flow_synthesizer.py)

• 由 LLM 驱动的流生成，附带证据支持
• 简单流基于规则的回退
• 步骤排序，显式推理
• 实体关系分析

📝 报告生成器 (tdo_core/report/md_export.py)

• 创建人类可读的 Markdown 报告
• 结构化数据呈现
• 集成所有分析组件

🎨 提示管理 (tdo_core/llm/prompts.py)

• 集中式提示模板
• 结构化输出优化
• LLM 交互最佳实践

数据流

文档输入 → 文本提取 → LLM 处理 → 结构化输出
     ↓         ↓           ↓           ↓
   PDF/DOCX   清洗文本    Gemini API   JSON + 回退
     ↓         ↓           ↓           ↓
 多格式     预处理       Pydantic 模式  验证
     ↓         ↓           ↓           ↓
文件支持    文本清洗    结构化数据     CTI 图
                                      ↓
                             后处理
                                ↓         ↓
                          攻击流      检测机会
                                ↓         ↓
                           Markdown 报告导出

🛠️ 高级配置

环境变量

模型选择指南

🔧 故障排除

常见问题

缺少环境变量

Error: Required environment variables missing: GEMINI_API_KEY, GEMINI_MODEL

解决方案： 创建包含两个必需变量的 .env 文件

不支持的文件格式

Skipping unsupported file: document.rtf

解决方案： 转换为 PDF、DOCX、TXT 或 MD 格式

LLM 处理错误

Structured Gemini API error: ...

可能的解决方案：

• 检查 API 密钥有效性
• 验证模型名称拼写
• 先尝试较小的文档
• 使用 --verbose 获取详细错误日志

JSON 解析问题

工具通过以下方式自动处理 JSON 解析问题：

• 结构化输出作为主要方法
• 手动解析回退
• 对截断响应进行 JSON 修复
• 优雅的错误恢复

性能优化

• 并行处理：使用 -j 标志处理多个文件
• 模型选择：批量处理时使用较快的模型
• 静默模式：自动化脚本中使用 -q
• 输出管理：使用自定义输出目录进行组织

调试模式

# 启用详细日志记录
python tdo_bulk.py report.pdf -v

# 调试检测机会
python tdo_bulk.py report.pdf --opps --debug-opps

# 导出详细日志
python tdo_bulk.py report.pdf -v > processing.log 2>&1

📦 依赖项

该工具需要 Python 3.9+ 和以下关键包：

• google-generativeai：Google AI (Gemini) API 客户端，支持结构化输出
• PyMuPDF：高性能 PDF 文本提取
• python-docx：Microsoft Word 文档处理
• pandas：数据操作和 CSV 导出
• pydantic：模式验证和结构化输出
• python-dotenv：环境变量管理
• cleantext：文本预处理工具

🚧 局限性

此独立版本：

• 不包含知识图谱或 Neo4j 集成
• 不支持用于相似性搜索的向量数据库功能
• 没有实时检索增强能力
• 比完整 TDO 平台更简化

然而，它包含了大多数用例所需的所有核心 CTI 提取和分析能力。

🔄 近期增强

• 环境配置：迁移到使用 dotenv 的 .env 文件管理
• 结构化输出：100% 可靠的 JSON 解析，配合 Google Gemini 结构化输出
• 增强模式：涵盖 12 种实体类型和 24 种关系类型
• 检测机会：基于证据的检测规则生成，附带评估
• 攻击流改进：增强证据支持和显式推理
• 无硬编码默认值：所有配置来自环境变量
• 健壮的错误处理：自动回退解析和优雅的错误恢复

🔒 安全注意事项

API 密钥保护

• 切勿提交您的 .env 文件 — 它已被 .gitignore 排除
• 使用环境变量安全存储 GEMINI_API_KEY
• 定期轮换 API 密钥
• 查看 SECURITY.md 获取详细安全指南

数据隐私

• 文档文本被发送到 Google 的 Gemini API 进行处理
• 在处理敏感文档之前，请查看 Google 的 AI 数据使用政策
• 提取的数据可能包含敏感信息（IOC、组织名称、文件路径）
• 在组织外共享之前，请审查输出内容

输出数据

提取的 JSON 和 Markdown 文件可能包含：

• IP 地址和域名（基础设施指标）
• 文件哈希和技术指标
• 组织和目标信息
• 详细的威胁行为体和活动数据

在公开共享之前，请务必审查输出内容。

报告安全问题

请负责任地报告安全漏洞。详情请参阅 SECURITY.md。

📄 许可协议

本项目采用 MIT 许可证 — 详情请参阅 LICENSE。

🤝 贡献

欢迎贡献！请阅读 CONTRIBUTING.md 了解指南。

需要帮助？ 运行 python tdo_bulk.py --help 快速参考，或查看上面的故障排除部分。