大規模言語モデル（LLM）と高度な構造化出力機能を用いて、文書からサイバー脅威インテリジェンス（CTI）を抽出するための、強力なスタンドアロン型コマンドラインツールです。
# Clone or download the standalone-tdo folder
cd standalone-tdo
# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
このツールは、.env ファイルから読み込まれる環境変数を設定に使用します：
# Copy the example configuration
cp env.example .env
# Edit .env with your settings
# Required variables:
GEMINI_API_KEY=your-google-ai-api-key-here
GEMINI_MODEL=gemini-2.5-flash
Gemini APIキーの取得：
.env ファイルにコピーします利用可能なモデル：
gemini-2.5-flash-preview-05-20（推奨 - 高速かつ費用対効果が高い）gemini-2.5-pro-preview-06-05（より高性能、低速）# Process a single file with all features
python tdo_bulk.py report.pdf --flow --opps
# Process multiple files
python tdo_bulk.py file1.pdf file2.docx file3.txt
# Process all files in a directory with parallel workers
python tdo_bulk.py reports/ -j 4
# Generate comprehensive analysis with evaluation
python tdo_bulk.py report.pdf --flow --opps --eval-opps
usage: tdo_bulk.py [options] FILE [FILE ...]
Positional Arguments:
FILE One or more files or directories to process
Core Options:
-o, --output DIR Output directory (default: ./extracted_data)
--csv FILE Export summary to CSV file
-j, --jobs N Number of parallel workers (default: 1)
--retries N LLM retry count (default: 2)
--backoff SEC Exponential back-off base (default: 1.5)
Analysis Features:
--flow Generate Attack-Flow JSON
--opps Generate Threat Detection Opportunities
--eval-opps Evaluate detection opportunities quality
--debug-opps Show debug information for opportunity generation
Output Control:
-q, --quiet Minimal console output
-v, --verbose Debug-level logging
-h, --help Show help message and exit
# Basic CTI extraction
python tdo_bulk.py threat_report.pdf
# Full analysis with all features
python tdo_bulk.py apt_report.pdf --flow --opps --eval-opps
# Batch processing with parallel workers
python tdo_bulk.py reports_folder/ -j 8 --flow --opps
# Export results to CSV
python tdo_bulk.py *.pdf --csv results.csv
# Quiet mode for automation
python tdo_bulk.py reports/ -q -o /var/soc/cti --opps
処理された各ファイルについて、このツールは以下を生成します：
{filename}_extracted.json: 包括的なスキーマを持つ構造化CTIデータ{filename}_{timestamp}.md: すべての分析を含む人間が読めるマークダウンレポート--flow 指定時）--opps 指定時）| エンティティタイプ | 説明 | 主要プロパティ |
|---|---|---|
| ThreatActor | サイバー脅威グループ | aliases, primary_motivation, first_seen |
| Tool | 正規のソフトウェア | family, capabilities, kill_chain_phases |
| Malware | 悪意のあるソフトウェア | family, capabilities, first_seen, last_seen |
| Technique | MITRE ATT&CK のテクニック | id (T1234), description, kill_chain_phases |
| Tactic | MITRE ATT&CK のタクティク | id (TA0001), description |
| Infrastructure | IPアドレス、ドメイン、URL | type, tags, first_seen, last_seen |
| Indicator | ファイルハッシュ、パターン | value, pattern, valid_from, valid_until |
| Vulnerability | CVEエントリ | id, cvss_score, affected_software |
| Campaign | 名称付きの攻撃キャンペーン | objective, status, first_seen |
| Identity | 標的となる組織 | type, description |
| CourseOfAction | 緩和策、パッチ | type, description |
| Source | 文書の出典情報 | filename, document_title, file_size_mb |
属性・攻撃者関連のリレーションシップ：
USES_TOOL, USES_TECHNIQUE, CONDUCTS, ATTRIBUTED_TO, TARGETS技術関連のリレーションシップ：
TOOL_IMPLEMENTS_TECHNIQUE, HOSTS_ON, COMMUNICATES_WITH, VARIANT_OFDROPS, DOWNLOADS, INDICATES, OBSERVED_ON, EXPLOITS高度なリレーションシップ：
MITIGATES, DETECTS, IS_SUBTECHNIQUE_OF, FLOW_CONTAINS_STEPFLOW_USED_BY_ACTOR, OBSERVES, SOURCED_FROMすべてのリレーションシップは、confidence、source、first_seen、last_seen などのプロパティをサポートしています。
このツールは、エビデンスに基づく検知機会を以下の機能付きで生成します：
{
"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"
]
}
拡張された攻撃フローは以下を提供します：
{
"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"
}
]
}
tdo_bulk.py）python-dotenv を使用して .env 設定を読み込みtdo_bulk_runner.py）tdo_core/extractors/report_processor.py）tdo_core/detection/opportunity_generator.py）tdo_core/flows/attack_flow_synthesizer.py）tdo_core/report/md_export.py）tdo_core/llm/prompts.py）Document Input → Text Extraction → LLM Processing → Structured Output
↓ ↓ ↓ ↓
PDF/DOCX Clean Text Gemini API JSON + Fallback
↓ ↓ ↓ ↓
Multi-format Preprocessing Pydantic Schema Validation
↓ ↓ ↓ ↓
File Support Text Cleaning Structured Data CTI Graph
↓
Post-Processing
↓ ↓
Attack Flows Detection Opps
↓ ↓
Markdown Report Export
| 変数 | 必須 | 説明 | 例 |
|---|---|---|---|
GEMINI_API_KEY | ✅ | Google AI API キー | AIza... |
GEMINI_MODEL | ✅ | 使用する Gemini モデル | gemini-2.5-flash-preview-05-20 |
| モデル | 速度 | 品質 | コスト | ユースケース |
|---|---|---|---|---|
gemini-2.5-flash-preview-05-20 | ⚡ 高速 | 🎯 良好 | 💰 低 | 本番環境、一括処理 |
gemini-2.5-pro-preview-06-05 | 🐌 低速 | 🏆 優秀 | 💸 高 | 複雑な分析、調査 |
Error: Required environment variables missing: GEMINI_API_KEY, GEMINI_MODEL
解決策： 両方の必須変数を含む .env ファイルを作成します
Skipping unsupported file: document.rtf
解決策： PDF、DOCX、TXT、MD 形式に変換します
Structured Gemini API error: ...
解決策：
--verbose を使用しますこのツールは JSON 解析の問題を以下の方法で自動処理します：
-j フラグを使用します-q を使用します# Enable verbose logging
python tdo_bulk.py report.pdf -v
# Debug detection opportunities
python tdo_bulk.py report.pdf --opps --debug-opps
# Export detailed logs
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: テキスト前処理ユーティリティこのスタンドアロンバージョンには以下がありません：
ただし、ほとんどのユースケースに必要なコアとなるCTI抽出・分析機能はすべて含まれています。
.env ファイル管理に移行.env ファイルをコミットしないでください - .gitignore により除外されていますGEMINI_API_KEY を安全に保管します抽出された JSON および Markdown ファイルには以下が含まれる場合があります：
公開前に必ず出力を確認してください。
セキュリティ脆弱性は責任を持って報告してください。詳細は SECURITY.md を参照してください。
このプロジェクトは MIT ライセンスの下で提供されています。詳細は LICENSE を参照してください。
コントリビューションを歓迎します！ ガイドラインについては CONTRIBUTING.md をお読みください。
ヘルプが必要ですか？ クイックリファレンスとして python tdo_bulk.py --help を実行するか、上記のトラブルシューティングセクションを確認してください。