TDO 독립형 추출기

대규모 언어 모델(LLM)과 고급 구조화 출력 기능을 사용하여 문서에서 사이버 위협 인텔리전스(CTI)를 추출하는 강력한 독립형 명령줄 도구입니다.

🚀 주요 기능

• 다중 형식 문서 지원: PDF, DOCX, TXT 및 Markdown 파일
• 고급 LLM 통합: 구조화 출력 및 자동 폴백 파싱을 지원하는 Google Gemini 모델
• 포괄적인 CTI 스키마: 풍부한 속성을 갖춘 12개 엔티티 유형 및 24개 관계 유형
• 탐지 기회 생성: 증거로 뒷받침되는 실행 가능한 위협 탐지 규칙 생성
• 공격 흐름 합성: 증거 기반 MITRE ATT&CK 흐름 다이어그램 생성
• 구조화 출력 신뢰성: 100% JSON 파싱 성공률을 갖춘 Pydantic 스키마
• 병렬 처리: 진행 상황 추적과 함께 여러 파일을 동시에 처리
• 휴대성 및 자족성: 환경 기반 구성과 최소한의 종속성

📋 빠른 시작

1. 설치

# 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

2. 구성

이 도구는 .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 키 받기:

1. Google AI Studio를 방문하세요
2. 새 API 키를 생성하세요
3. 키를 .env 파일에 복사하세요

사용 가능한 모델:

• gemini-2.5-flash-preview-05-20 (권장 - 빠르고 비용 효율적)
• gemini-2.5-pro-preview-06-05 (더 강력하지만 느림)

3. 기본 사용법

# 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: 모든 분석이 포함된 사람이 읽을 수 있는 마크다운 보고서

선택적 출력 (플래그 사용 시)

• Attack Flow JSON: 증거 기반 MITRE ATT&CK 흐름 구조 (--flow 사용 시)
• 탐지 기회: 증거가 포함된 실행 가능한 탐지 규칙 (--opps 사용 시)

🔍 CTI 스키마 개요

엔티티 유형 (12개 유형)

엔티티 유형	설명	주요 속성
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

관계 유형 (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)

• 사람이 읽을 수 있는 마크다운 보고서 생성
• 구조화된 데이터 표현
• 모든 분석 구성 요소 통합

🎨 프롬프트 관리 (tdo_core/llm/prompts.py)

• 중앙 집중식 프롬프트 템플릿
• 구조화 출력 최적화
• LLM 상호 작용을 위한 모범 사례

데이터 흐름

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