TDO Standalone Extractor

Мощный автономный инструмент командной строки для извлечения данных киберразведки (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=ваш-ключ-api-google-ai-здесь
GEMINI_MODEL=gemini-2.5-flash

Получение ключа API Gemini:

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)

• Точка входа с разбором аргументов и проверкой окружения
• Загрузка конфигурации .env с помощью python-dotenv
• Оркестрация пакетной обработки с отслеживанием прогресса

⚙️ Пакетный исполнитель (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           Чистый текст       API Gemini      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: Клиент API Google AI (Gemini) со структурированным выводом
• PyMuPDF: Высокопроизводительное извлечение текста из PDF
• python-docx: Обработка документов Microsoft Word
• pandas: Манипуляции с данными и экспорт в CSV
• pydantic: Валидация схем и структурированный вывод
• python-dotenv: Управление переменными окружения
• cleantext: Утилиты предобработки текста

🚧 Ограничения

Эта автономная версия:

• Не включает граф знаний или интеграцию Neo4j
• Не поддерживает функции векторной базы данных для поиска по сходству
• Не имеет возможностей дополнения на основе извлечения в реальном времени
• Упрощена по сравнению с полной платформой TDO

Однако она включает все основные возможности извлечения и анализа CTI, необходимые для большинства случаев использования.

🔄 Недавние улучшения

• Конфигурация окружения: Переход на управление файлом .env с помощью dotenv
• Структурированный вывод: 100% надёжный разбор JSON с помощью структурированного вывода Google Gemini
• Расширенные схемы: 12 типов сущностей и 24 типа отношений
• Возможности обнаружения: Генерация правил обнаружения на основе доказательств с оценкой
• Улучшения цепочек атак: Дополнены подтверждением доказательств и явным обоснованием
• Отсутствие жёстко заданных значений по умолчанию: Вся конфигурация берётся из переменных окружения
• Надёжная обработка ошибок: Автоматический резервный разбор и безопасное восстановление после ошибок

🔒 Вопросы безопасности

Защита ключа API

• Никогда не коммитьте ваш файл .env — он исключён с помощью .gitignore
• Храните GEMINI_API_KEY безопасно, используя переменные окружения
• Периодически меняйте ключи API
• Ознакомьтесь с SECURITY.md для получения подробных инструкций по безопасности

Конфиденциальность данных

• Текст документа отправляется для обработки в API Gemini от Google
• Перед обработкой конфиденциальных документов ознакомьтесь с политиками использования данных AI от Google
• Извлечённые данные могут содержать конфиденциальную информацию (IOC, названия организаций, пути к файлам)
• Проверяйте выходные данные перед передачей за пределы вашей организации

Выходные данные

Извлечённые файлы JSON и Markdown могут содержать:

• IP-адреса и доменные имена (индикаторы инфраструктуры)
• Хеши файлов и технические индикаторы
• Информацию об организациях и целях
• Детальные данные об угрозах и кампаниях

Всегда проверяйте выходные данные перед публичным распространением.

Сообщение о проблемах безопасности

Пожалуйста, ответственно сообщайте о проблемах безопасности. Подробности см. в SECURITY.md.

📄 Лицензия

Этот проект лицензирован по лицензии MIT — подробности см. в LICENSE.

🤝 Вклад в развитие

Приветствуются любые вклады! Пожалуйста, прочитайте CONTRIBUTING.md для получения рекомендаций.

Нужна помощь? Выполните python tdo_bulk.py --help для быстрой справки или обратитесь к разделу устранения неполадок выше.