### Настройка окружения

**ВАЖНО:** Перед запуском приложения необходимо настроить переменные окружения. Приложению требуется установить `NEO4J_PASSWORD`.

Создайте файл `.env` в корне проекта:```bash
# Copy the sample file
cp infra/env.sample .env

# Edit .env and set your actual passwords
nano .env

**Примечание:** Приложение не запустится, если не задан `NEO4J_PASSWORD`. Подробнее см. [Исправление переменных окружения](https://github.com/blevene/bandjacks/blob/HEAD/ENV_VARIABLES_FIX.md).

### Запуск сервисов```bash
# Start the FastAPI backend server
uv run uvicorn bandjacks.services.api.main:app --reload --port 8000

# In another terminal, start the Next.js frontend
cd ui && npm run dev

# Access the applications
open http://localhost:8000/docs    # API documentation
open http://localhost:3000         # Frontend UI

> **Примечание:** CLI требует установки переменных окружения (NEO4J_PASSWORD и т.д.). Запускайте из корня проекта, где находится `.env`.

### Команды запросов```bash
# Search for threat intelligence
uv run python -m bandjacks.cli.main query search "ransomware encryption techniques" --top-k 10

# Explore graph relationships
uv run python -m bandjacks.cli.main query graph "attack-pattern--abc123" --depth 2

### Извлечение документов```bash
# Extract CTI from a document
uv run python -m bandjacks.cli.main extract document ./report.pdf --confidence-threshold 80 --show-evidence

### Команды рабочего процесса```bash
# Process a directory of reports with analytics
uv run python -m bandjacks.cli.main workflow process-reports ./reports/ --workers 3 --analyze --export-dir ./results/

# Bulk export all analytics data
uv run python -m bandjacks.cli.main workflow bulk-export --export-dir ./analytics_export/

## Интерфейс фронтенда

Фронтенд на Next.js предоставляет современный интерфейс для работы с системой.

### Управление отчетами (`/reports`)
- **Список отчетов**: Просмотр всех загруженных отчетов с указанием статуса и количества техник
- **Новый отчет** (`/reports/new`): Загрузка PDF/TXT файлов или вставка содержимого отчета
- **Детали отчета** (`/reports/[id]`): Просмотр извлеченных техник, сущностей и доказательств
- **Интерфейс рецензирования** (`/reports/[id]/review`): Рабочий процесс проверки с участием человека (Human-in-the-loop)

### Аналитика совместной встречаемости (`/analytics/cooccurrence`)

> **Примечание:** Для этих страниц требуются данные `AttackEpisode` в Neo4j. Сначала обработайте отчеты через конвейер извлечения или используйте `POST /v1/flows/build` для генерации эпизодов на основе данных о наборах вторжений.

- **Главная страница**: Обзор с количеством эпизодов/техник/субъектов
- **Лучшие пары** (`/pairs`): Пары совместно встречающихся техник с метриками NPMI/Lift
- **Условное** (`/conditional`): Условные вероятности P(B|A)
- **Пакеты** (`/bundles`): Часто совместно встречающиеся пакеты техник
- **Субъекты** (`/actors`): Характерные для субъекта шаблоны техник
- **Связи** (`/bridging`): Техники, используемые несколькими субъектами

### Состояние системы (`/health`)
- Состояние в реальном времени всех компонентов (Neo4j, OpenSearch, Redis)
- Статистика кэша и использование памяти
- Эндпоинты состояния, совместимые с Kubernetes

### Запуск фронтенда```bash
cd ui
npm run dev     # Development mode with hot reload
npm run build   # Production build
npm run start   # Start production server

# Ensure backend is running
# API_URL defaults to http://localhost:8000/v1

### 2. Извлечение техник из отчетов

Извлечение техник MITRE ATT&CK из отчетов по разведке угроз:```python
import httpx
import time

# For small reports (<5KB) - synchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest",
    json={
        "content": "APT29 used spearphishing emails with malicious attachments...",
        "title": "APT29 Campaign Analysis",
        "config": {
            "use_optimized_extractor": True,
            "span_score_threshold": 0.7,
            "top_k": 5
        }
    }
)

result = response.json()
print(f"Extracted {len(result['extraction']['techniques'])} techniques")

# For large reports (>5KB) - asynchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest_async",
    json={
        "content": large_report_text,
        "title": "Large Report Analysis"
    }
)

job_id = response.json()["job_id"]

# Check job status
status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")
while status.json()["status"] == "processing":
    time.sleep(2)
    status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")

# Get results from completed job
result = status.json()["result"]
print(f"Extracted {result['techniques_count']} techniques in {result['elapsed_time']} seconds")

## Архитектура конвейера извлечения

Конвейер извлечения Bandjacks использует мультиагентную архитектуру для извлечения структурированных угроз:

### Компоненты конвейера

Конвейер извлечения использует 9 специализированных агентов в последовательности:

#### 1. **EntityExtractionAgent** — Распознавание сущностей
- Извлекает субъекты угроз, вредоносное ПО, инструменты и кампании
- Запускается первым для обеспечения контекста извлечения техник
- Использует few-shot-подсказки с валидацией JSON-схемы
- Обрабатывает фрагментированные документы с прогрессивным оконным извлечением

#### 2. **SpanFinderAgent** — Обнаружение поведенческого текста
- Обнаруживает текстовые промежутки, содержащие угрожающее поведение, используя 14 тактико-специфичных regex-шаблонов
- Выявляет явные идентификаторы техник (T1566.001) и поведенческие паттерны
- Оценивает промежутки по уверенности с повышающим индексом ключевых слов
- Не использует LLM — чистое сопоставление шаблонов для скорости

#### 3. **BatchRetrieverAgent** — Извлечение кандидатов
- Использует векторный поиск OpenSearch KNN для поиска техник-кандидатов для каждого промежутка
- Дедуплицирует одинаковые тексты промежутков перед кодированием для избежания избыточных эмбеддингов
- Возвращает top-k кандидатов с оценками схожести для каждого промежутка

#### 4. **Pre-filter** — Сокращение промежутков
- Ограничивает промежутки значением `max_spans_per_technique` (по умолчанию 2) на каждую технику-кандидат
- Сохраняет промежутки с наибольшим рейтингом для каждого кандидата для поддержания качества доказательств
- Сокращает вызовы LLM сопоставления примерно на 46% при минимальной потере техник

#### 5. **DiscoveryAgent** — Обнаружение с помощью LLM (условное)
- Запускается, когда уверенность извлекателя низкая (<0,7 в среднем)
- Использует LLM для обнаружения техник, пропущенных векторным поиском
- Одиночный пакетный вызов для всех промежутков с низкой уверенностью

#### 6. **BatchMapperAgent** — Сопоставление техник (LLM)
- Пакетная обработка промежутков группами до 10 (`MAX_MAPPER_BATCH_SIZE`, по умолчанию снижено с 25 в мае 2026 כדי ограничить усечение облачных LLM)
- Извлекает ВСЕ релевантные техники для каждого промежутка с оценками уверенности
- Использует валидацию JSON-схемы для структурированного вывода

#### 7. **EvidenceVerifierAgent** — Проверка доказательств
- Основанная на шаблонах проверка цитат и ссылок на строки
- Оценивает качество доказательств по шкале от 40 до 100 баллов
- Не использует LLM — regex и сопоставление текста

#### 8. **ConsolidatorAgent** — Сведение доказательств
- Объединяет дублирующиеся техники, найденные в нескольких промежутках
- Агрегирует доказательства с использованием сходства Жаккара (порог >85%)
- Выдает финальный список техник со сводными оценками уверенности

#### 9. **AttackFlowSynthesizer** — Генерация последовательности (LLM)
- Анализирует временные маркеры ("сначала", "затем", "после")
- Выводит причинно-следственные связи из повествования
- Создает объекты STIX Attack Flow с вероятностными ребрами
- Использует моделирование совместной встречаемости, когда последовательность неясна

### Оптимизация производительности

- **Умное фрагментирование**: документы разделяются на фрагменты по 2 КБ с перекрытием
- **Пакетная обработка**: маппер обрабатывает до 25 промежутков за один вызов LLM
- **Параллельная обработка**: фрагменты обрабатываются одновременно в рабочих потоках
- **Кэширование ответов**: ответы LLM кэшируются для избежания повторных вызовов
- **Досрочное завершение**: извлечения с высокой степенью уверенности пропускают проверку
- **TechniqueCache**: все техники ATT&CK загружаются при запуске для O(1)-поиска
- **Pre-filter**: ограничивает количество промежутков на одну технику-кандидат перед LLM-маппером (на 46% меньше вызовов)
- **Пакетные эмбеддинги**: эмбеддинги техник генерируются пакетами (в 2-5 раз быстрее)
- **Пул соединений**: общие соединения Neo4j/OpenSearch между запросами
- **Пакеты UNWIND**: записи в Neo4j отправляются пакетами через UNWIND (30-40 запросов → 6-7)
- **Прогрев модели**: модель эмбеддингов загружается при запуске, чтобы избежать задержки холодного старта

### Время обработки

| Размер документа | Время обработки | Извлечено техник |
|-----------------|-----------------|------------------|
| Маленький (<5 КБ) | 10-20 секунд | 5-10 техник |
| Средний (5-15 КБ) | 20-40 секунд | 10-15 техник |
| Большой (>15 КБ) | 30-60 секунд | 15-25 техник |

## Аналитика совместной встречаемости

Bandjacks предоставляет аналитику для понимания взаимосвязей между техниками. 

> **Примечание:** Для аналитики требуются данные `AttackEpisode` и `AttackAction` в Neo4j. Они создаются, когда:
> - Отчеты обрабатываются через конвейер извлечения
> - Потоки атак строятся через `/v1/flows/build`
> - Пакеты STIX с эпизодами атак импортируются
>
> Если эпизоды отсутствуют, аналитика вернет пустые результаты.

### Глобальная совместная встречаемость

Вычисление техник, которые часто появляются вместе во всех эпизодах атак:```python
# Via API
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/global",
    json={"min_support": 2, "min_episodes_per_pair": 2, "limit": 50}
)

for pair in response.json()["pairs"]:
    print(f"{pair['name_a']} + {pair['name_b']}: NPMI={pair['npmi']:.3f}")

### Связки техник

Определите часто совместно встречающиеся связки техник (3-5 техник):```python
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/bundles",
    json={"min_support": 3, "min_size": 3, "max_size": 5}
)

## Система проверки с участием человека

Bandjacks включает комплексную систему проверки для валидации извлеченных разведывательных данных:

### Единый интерфейс проверки

Система проверки представляет все извлеченные элементы в едином интерфейсе:```typescript
// Review workflow
1. Upload/ingest report → Extraction pipeline runs
2. Navigate to /reports/{id}/review
3. Review extracted items across three tabs:
   - Entities (threat actors, malware, tools)
   - Techniques (ATT&CK mappings with evidence)
   - Attack Flow (sequenced steps)
4. Take actions on each item:
   - Approve: Accept as correct
   - Reject: Mark as incorrect
   - Edit: Modify details (name, confidence, etc.)
5. Submit all decisions atomically

### 4. Поиск техник

Поиск техник ATT&CK с использованием естественного языка:```python
# Vector search for similar techniques
response = httpx.post(
    "http://localhost:8000/v1/search/ttx",
    json={
        "query": "ransomware that encrypts files and demands payment",
        "top_k": 5
    }
)

techniques = response.json()["results"]
for tech in techniques:
    print(f"{tech['external_id']}: {tech['name']} (score: {tech['score']:.2f})")

### 6. Создание моделей AttackFlow

Создайте модели совместной встречаемости, которые показывают, как субъекты угроз используют техники вместе:```python
# Generate flow for a specific intrusion set (e.g., APT29)
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "intrusion_set_id": "intrusion-set--899ce53f-13a0-479b-a0e4-67d46e241542"
    }
)

flow = response.json()
print(f"Generated flow '{flow['name']}' with {len(flow['steps'])} techniques")
print(f"Co-occurrence edges: {len(flow['edges'])}")

Модели AttackFlow используют **ко-встречаемость**, а не последовательное упорядочивание, поскольку наборы вторжений не содержат информации о последовательности. Техники соединяются с помощью:
- **Внутритактические ребра**: Между техниками в одной тактике цепочки уничтожения
- **Межтактические ребра**: Между техниками из смежных тактик
- **Шаблоны «хаб-спица»**: Для больших наборов техник, чтобы избежать взрыва ребер

Подробное использование см. в [Руководстве по генерации AttackFlow](https://github.com/blevene/bandjacks/blob/HEAD/docs/ATTACKFLOW_GENERATION.md).

## Поддерживаемые форматы ввода

Конвейер извлечения поддерживает несколько форматов ввода:

- **Обычный текст** — Прямое текстовое содержимое
- **Markdown** — Форматированные документы Markdown
- **PDF** — Извлечение через pdfplumber
- **HTML** — Парсинг через BeautifulSoup
- **JSON** — Извлечение структурированных данных

### Извлечение из обычного текста```python
# Direct text extraction
plaintext_report = """
The threat actors used spearphishing emails with malicious attachments.
After gaining access, they deployed Mimikatz to harvest credentials and
used RDP for lateral movement across the network.
"""

result = asyncio.run(run_agentic_v2_async(plaintext_report, {
    "cache_llm_responses": True,
    "single_pass_threshold": 500
}))

### Извлечение из PDF```python
import pdfplumber
from bandjacks.llm.extraction_pipeline import run_extraction_pipeline

# Read PDF with pdfplumber (recommended)
with pdfplumber.open("threat_report.pdf") as pdf:
    text = ""
    for page in pdf.pages:
        page_text = page.extract_text()
        if page_text:
            text += page_text + "\n"

# Extract techniques using extraction pipeline
result = run_extraction_pipeline(text, {
    "use_optimized_extractor": True,
    "span_score_threshold": 0.7,
    "chunk_size": 2000
}, source_id="threat_report")

print(f"Found {len(result['techniques'])} techniques")

results.append({
    "file": pdf_file.name,
    "techniques": list(result["techniques"].keys()),
    "count": len(result["techniques"])
})

### Построение потоков атак```python
# Generate attack flow from extracted techniques
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "source_id": "report-123",
        "technique_ids": ["T1566.001", "T1059.001", "T1003.001"]
    }
)

flow = response.json()
print(f"Generated flow with {len(flow['steps'])} steps")

## API Эндпоинты

### Основные эндпоинты

- `POST /v1/stix/load/attack` - Загрузить данные MITRE ATT&CK
- `POST /v1/reports/ingest` - Синхронная загрузка отчётов (<5KB)
- `POST /v1/reports/ingest_async` - Асинхронная загрузка отчётов (>5KB)
- `POST /v1/reports/ingest/upload` - Загрузить PDF/TXT файлы
- `GET /v1/reports/jobs/{id}/status` - Проверить статус задачи
- `POST /v1/reports/{id}/unified-review` - Отправить решения по рецензированию
- `POST /v1/search/ttx` - Поиск техник
- `GET /v1/graph/technique/{id}` - Получить детали техники

### Потоки атак

- `POST /v1/flows/build` - Создать модели совместной встречаемости AttackFlow
- `GET /v1/flows/{flow_id}` - Получить детали конкретного AttackFlow
- `POST /v1/flows/search` - Поиск похожих потоков атак
- `GET /v1/flows/dump` - Массовый экспорт потоков с пагинацией и фильтрацией

### Аналитика

- `GET /v1/analytics/cooccurrence/global` - Глобальные метрики совместной встречаемости
- `GET /v1/analytics/cooccurrence/conditional` - Условные вероятности
- `GET /v1/analytics/cooccurrence/bundles` - Пакеты техник
- `GET /v1/analytics/cooccurrence/actor` - Паттерны для конкретного актора
- `GET /v1/coverage/gaps` - Пробелы в покрытии техник

### Защита и обнаружение

- `GET /v1/defense/technique/{id}` - Получить рекомендации по защите
- `GET /v1/detections/technique/{id}` - Стратегии обнаружения
- `POST /v1/sigma/validate` - Валидировать правила Sigma

### Мониторинг

- `GET /health` - Базовая проверка работоспособности
- `GET /health/live` - Проверка liveness для Kubernetes
- `GET /health/ready` - Проверка readiness для Kubernetes
- `GET /health/components/{component}` - Работоспособность отдельного компонента
- `GET /v1/costs/stats` - Отслеживание затрат LLM (ежедневная сводка по моделям)
- `GET /v1/cache/stats` - Получить статистику кэша LLM
- `POST /v1/cache/clear` - Очистить кэш LLM
- `GET /v1/compliance/report` - Метрики соответствия
- `GET /v1/drift/status` - Статус обнаружения дрейфа
- `GET /v1/ml-metrics/performance` - Метрики модели ML

### Акторы и происхождение

- `GET /v1/actors` - Список угрозных акторов
- `GET /v1/actors/{id}` - Получить детали актора
- `GET /v1/provenance/{object_id}` - Происхождение объекта
- `GET /v1/provenance/{object_id}/lineage` - Полная цепочка происхождения
- `GET /v1/provenance/{object_id}/evidence` - Фрагменты доказательств

### Функции только через API (нет UI/CLI)

Эти эндпоинты полностью функциональны, но доступны только через REST API (нет страниц интерфейса или команд CLI):

#### Симуляция путей атак
- `POST /v1/simulation/paths` - Симулировать пути атак от начальной техники/группы
- `POST /v1/simulation/predict` - Предсказать следующие вероятные техники на основе текущего состояния
- `POST /v1/simulation/whatif` - Анализ «что если» для сценариев защиты
- `POST /v1/simulation/scenario` - Симулировать на основе наборов групп/программного обеспечения/техник
- `GET /v1/simulation/statistics/{technique_id}` - Статистика использования техники
- `GET /v1/simulation/groups/{group_id}/patterns` - Паттерны атак группы
- `POST /v1/simulation/compare` - Сравнить несколько путей атак

#### Политика MDP и развертывание
- `POST /v1/simulate/rollout` - Симуляция развертывания PTG
- `POST /v1/simulate/mdp` - Вычислить оптимальную политику защиты MDP
- `GET /v1/simulate/models` - Список доступных моделей PTG

#### Обнаружение дрейфа и мониторинг
- `GET /v1/drift/status` - Текущий статус дрейфа по всем метрикам
- `POST /v1/drift/analyze` - Запустить анализ дрейфа с настраиваемыми порогами
- `GET /v1/drift/alerts` - Получить активные оповещения о дрейфе
- `POST /v1/drift/alerts/{alert_id}/acknowledge` - Подтвердить оповещение
- `GET /v1/drift/metrics/{metric_name}` - Получить конкретную метрику дрейфа

#### Отслеживание метрик ML
- `POST /v1/ml-metrics/prediction` - Записать предсказание модели для отслеживания
- `POST /v1/ml-metrics/review` - Записать метрики решения по рецензированию
- `POST /v1/ml-metrics/coverage-gap` - Записать пробел в покрытии
- `GET /v1/ml-metrics/performance` - Получить метрики производительности модели
- `GET /v1/ml-metrics/dashboard` - Экспортировать метрики панели управления

#### Уведомления
- `GET /v1/notifications/history` - Получить историю уведомлений
- `POST /v1/notifications/clear-history` - Очистить историю уведомлений
- `GET /v1/notifications/config` - Получить конфигурацию уведомлений
- `POST /v1/notifications/test` - Отправить тестовое уведомление

#### Управление обновлением векторов
- `GET /v1/vectors/status` - Статус системы обновления векторов
- `GET /v1/vectors/metrics` - Детальные метрики обновления векторов
- `POST /v1/vectors/update` - Вручную запустить обновление векторов
- `POST /v1/vectors/process-batch` - Принудительно обработать пакет
- `DELETE /v1/vectors/queue` - Очистить очередь ожидающих обновлений
- `GET /v1/vectors/health` - Проверка работоспособности векторной системы

#### Список игнорируемых сущностей
- `GET /v1/ignorelist` - Получить текущее состояние списка игнорирования
- `POST /v1/ignorelist/add` - Добавить сущность в список игнорирования
- `DELETE /v1/ignorelist/remove` - Удалить сущность из списка игнорирования
- `POST /v1/ignorelist/reload` - Перезагрузить список игнорирования с диска

#### Проверка кандидатных паттернов
- `GET /v1/review/candidates` - Список кандидатных паттернов атак
- `POST /v1/review/candidates` - Создать кандидатный паттерн
- `GET /v1/review/candidates/{id}` - Получить детали кандидата
- `POST /v1/review/candidates/{id}/approve` - Одобрить кандидата
- `POST /v1/review/candidates/{id}/reject` - Отклонить кандидата
- `GET /v1/review/candidates/{id}/similar` - Найти похожие паттерны
- `GET /v1/review/candidates/stats/summary` - Статистика кандидатов

### Полная документация API

Полная документация API доступна по адресам:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json

## Архитектура

### Структура проекта```
bandjacks/
├── bandjacks/
│   ├── analysis/         # Graph analysis & interdiction
│   │   ├── graph_analyzer.py
│   │   └── interdiction.py
│   ├── analytics/        # Co-occurrence & clustering
│   │   ├── clustering.py
│   │   ├── cooccurrence.py
│   │   └── detection_bundles.py
│   ├── cli/              # Command-line interface
│   │   ├── main.py       # CLI entry point
│   │   ├── batch_extract.py
│   │   ├── formatters.py
│   │   └── workflows.py
│   ├── config/           # Configuration files
│   │   └── entity_ignorelist.yaml
│   ├── core/             # Core utilities
│   │   ├── cache.py      # Redis caching
│   │   ├── connection_pool.py
│   │   └── query_optimizer.py
│   ├── llm/              # Extraction pipeline
│   │   ├── extraction_pipeline.py
│   │   ├── agents_v2.py  # Core extraction agents
│   │   ├── chunked_extractor.py
│   │   ├── optimized_chunked_extractor.py
│   │   ├── entity_extractor.py
│   │   ├── flow_builder.py
│   │   ├── cache.py      # LLM response caching
│   │   └── experimental/ # Experimental features
│   ├── loaders/          # Data loading & indexing
│   │   ├── attack_catalog.py
│   │   ├── attack_upsert.py
│   │   ├── opensearch_index.py
│   │   ├── hybrid_search.py
│   │   └── sigma_loader.py
│   ├── monitoring/       # Metrics & monitoring
│   │   ├── compliance_metrics.py
│   │   ├── defense_metrics.py
│   │   ├── drift_detector.py
│   │   └── ml_metrics.py
│   ├── services/         # API & services
│   │   ├── api/          # FastAPI application
│   │   │   ├── main.py
│   │   │   ├── routes/   # API route handlers
│   │   │   └── middleware/
│   │   ├── technique_cache.py
│   │   └── actor_cache.py
│   ├── simulation/       # Attack simulation
│   │   ├── attack_simulator.py
│   │   ├── mdp_solver.py
│   │   └── ptg_rollout.py
│   └── store/            # Data stores
│       ├── report_store.py
│       ├── candidate_store.py
│       └── review_store.py
├── ui/                   # Next.js frontend
│   ├── app/              # App Router pages
│   │   ├── reports/      # Report management
│   │   ├── analytics/    # Analytics dashboards
│   │   └── health/       # Health monitoring
│   ├── components/       # React components
│   └── hooks/            # Custom React hooks
├── tests/                # Test suite
├── samples/              # Sample reports
├── scripts/              # Utility scripts
└── docs/                 # Documentation

**Приоритет провайдера:** Local API > Gemini > OpenAI > LiteLLM proxy.
Когда настроен локальный сервер, облачные провайдеры автоматически добавляются в качестве запасных вариантов.

#### Примеры распространенных локальных серверов

| Сервер | `LOCAL_LLM_API_BASE` | `LOCAL_LLM_MODEL` |
|--------|---------------------|-------------------|
| vLLM | `http://host:8000/v1` | `mistralai/Mistral-Nemo-Instruct-2407` |
| llama.cpp | `http://host:8080/v1` | `mistral-nemo` |
| Ollama | `http://host:11434/v1` | `mistral-nemo` |
| LM Studio | `http://host:1234/v1` | `mistral-nemo` |
| LocalAI | `http://host:8080/v1` | `mistral-nemo` |

### Конфигурация извлечения

Система использует единый высокопроизводительный асинхронный конвейер с настраиваемыми опциями:```python
{
    "cache_llm_responses": True,         # Enable LLM caching (default: True)
    "single_pass_threshold": 500,        # Max words for single-pass (default: 500)
    "early_termination_confidence": 90,  # Skip verification above this (default: 90)
    "disable_discovery": False,          # Disable LLM discovery agent
    "max_spans": 20,                     # Maximum spans to process
    "span_score_threshold": 0.7,         # Minimum span quality
    "top_k": 5,                          # Candidates per span

    # Cost optimization options
    "max_spans_per_technique": 2,        # Pre-filter: max spans per candidate technique (0=disable, default=2)
    "enable_span_dedup": False,          # Text-based span dedup before mapping (default=False)
}

### Пороги уверенности

Управляйте качеством извлечения:```python
{
    "confidence_threshold": 50.0,  # Minimum confidence (0-100)
    "auto_ingest": True            # Auto-add high-confidence results
}

### Пример ответа о состоянии здоровья```json
{
  "status": "healthy",
  "timestamp": "2025-01-28T17:43:30.184036Z",
  "version": "1.0.0",
  "components": {
    "neo4j": {
      "status": "healthy",
      "latency_ms": 5
    },
    "opensearch": {
      "status": "degraded",
      "cluster_status": "yellow",
      "indices": {
        "attack_nodes": false,
        "bandjacks_reports": true
      }
    },
    "redis": {
      "status": "healthy",
      "latency_ms": 2,
      "memory_mb": 1.69
    },
    "caches": {
      "status": "healthy",
      "technique_cache": {
        "count": 993,
        "loaded": true
      },
      "actor_cache": {
        "count": 145,
        "loaded": true
      }
    },
    "system": {
      "status": "healthy",
      "memory": {
        "available_gb": 8.84,
        "percent_used": 72.4
      },
      "disk": {
        "available_gb": 353.11,
        "percent_used": 2.9
      },
      "cpu": {
        "percent_used": 7.7
      }
    }
  }
}

## Оптимизация производительности

### Кэширование

Система включает автоматическое кэширование ответов LLM для повышения производительности:```python
# Check cache statistics
response = httpx.get("http://localhost:8000/v1/cache/stats")
stats = response.json()
print(f"Cache hit rate: {stats['hit_rate']}")

# Clear cache if needed
httpx.post("http://localhost:8000/v1/cache/clear")

## Безопасность

### Проверка входных данных

- **Предотвращение внедрения Cypher**: Все конечные точки запросов к графу проверяют предоставляемые пользователем параметры `relationship_types` по белому списку известных типов связей (USES, MITIGATES, HAS_TACTIC и т.д.) и строгому регулярному выражению (`^[A-Z][A-Z0-9_]*$`). Неверный ввод возвращает 400 до построения запроса.
- **Проверка JSON-схем**: Ответы LLM проверяются на соответствие JSON-схемам, чтобы предотвратить попадание некорректных данных в конвейер.
- **Проверка ADM**: Все STIX-содержимое должно пройти проверку модели данных ATT&CK (ADM) перед загрузкой.

### Аутентификация и авторизация

- **JWT-аутентификация**: Необязательное промежуточное ПО для аутентификации API (`JWTAuthMiddleware`)
- **Ограничение скорости**: Лимитирование запросов на каждую конечную точку с настраиваемыми порогами
- **CORS**: Настраиваемый обмен ресурсами между источниками

## Расширенные возможности

### Отслеживание происхождения

Каждая извлеченная сущность содержит полное происхождение:```python
# Get provenance for an object
response = httpx.get(
    "http://localhost:8000/v1/provenance/attack-pattern--abc123"
)

### Coverage Analytics

Analyze your threat intelligence coverage:```python
# Get coverage analysis
response = httpx.get("http://localhost:8000/v1/analytics/coverage")
coverage = response.json()

print(f"Summary: {coverage['summary']}")
for tactic in coverage['tactics']:
    print(f"  {tactic['tactic']}: {tactic['coverage_percentage']}%")

## Статус функций

В этом разделе представлена информация о статусе реализации различных функций:

### Полностью функционально ✅
- **Конвейер извлечения отчетов** - Извлечение техник на основе LLM работает от начала до конца
- **Загрузка MITRE ATT&CK** - Загрузка данных ATT&CK для enterprise/mobile/ICS в Neo4j
- **Векторный поиск** - Семантический поиск техник на основе OpenSearch
- **Система рецензирования** - Рабочий процесс рецензирования с участием человека через API и UI
- **Мониторинг состояния** - Проверки состояния компонентов и пробы Kubernetes
- **Команды CLI для запросов/администрирования** - Поиск, обход графа, управление кэшем
- **Генерация потоков атак** - Построение потоков на основе совместной встречаемости для наборов вторжений
- **Симуляция атак** - Симуляция путей на основе MDP через `/simulation/*` и `/simulate/*`
- **Отчеты о покрытии** - Отчеты в формате JSON для руководителей, технических специалистов, тактического и оперативного уровней

### Функционально с зависимостями от данных ⚠️
- **Анализ совместной встречаемости** - Требует узлов `AttackEpisode` из обработки отчетов
- **Анализ субъектов** - Требует эпизодов, приписанных наборам вторжений
- **Пакеты техник** - Требует достаточного количества данных эпизодов для поиска закономерностей
- **Команды CLI для аналитики** - Работают, но возвращают пустой результат, если эпизоды отсутствуют

### Только API (без UI/CLI) 🔌
Это полностью реализованные функции, доступные только через REST API:
- **Симуляция путей атак** - Маршруты `/simulation/*` для прогнозирования путей и анализа «что если»
- **Решатель политик MDP** - `/simulate/mdp` для вычисления оптимальной политики защиты
- **Обнаружение дрейфа** - Маршруты `/drift/*` для мониторинга дрейфа качества данных
- **Метрики ML** - `/ml-metrics/*` для отслеживания производительности модели с течением времени
- **Управление векторами** - `/vectors/*` для управления векторными представлениями
- **Список игнорирования сущностей** - `/ignorelist/*` для фильтрации ложноположительных сущностей
- **Кандидаты закономерностей** - `/review/candidates/*` для кандидатов новых техник
- **Уведомления** - `/notifications/*` для настройки и истории оповещений
- **Происхождение** - `/provenance/*` для отслеживания цепочки извлечения
- **Соответствие требованиям** - `/compliance/*` для отчетности по метрикам соответствия

### Экспериментальное (в `llm/experimental/`) 🧪
- **PTG (Probabilistic Threat Graph)** - Базовая логика реализована, ограниченное тестирование
- **Интеграция Judge** - Валидация последовательностей на основе LLM
- **Симулятор потоков атак** - Движок симуляции на основе потоков
- **Извлекатель последовательностей** - Извлечение последовательностей из потоков

### Удалено/Очищено 🗑️
Следующие заглушки функций были удалены из API:
- ~~Анализ покрытия платформ~~ - Возвращал жестко закодированные данные-заглушки
- ~~Анализ трендов~~ - Возвращал случайные синтетические данные
- ~~Экспорт отчетов в CSV/PDF~~ - Возвращал 501; теперь только JSON
- ~~Вывод последовательностей Gemini~~ - Был заглушкой 501; используйте `/sequence/propose` вместо него

### Матрица подключения

| Область функции | Frontend UI | CLI | REST API |
|-----------------|-------------|-----|----------|
| Управление отчетами | ✅ | ✅ | ✅ |
| Рабочий процесс рецензирования | ✅ | ✅ | ✅ |
| Поиск (TTX) | ✅ | ✅ | ✅ |
| Анализ совместной встречаемости | ✅ | ✅ | ✅ |
| Анализ покрытия | ✅ | - | ✅ |
| Мониторинг состояния | ✅ | - | ✅ |
| Обнаружения/Sigma | ✅ | - | ✅ |
| Потоки атак | ✅ | - | ✅ |
| Наложение защиты | ✅ | - | ✅ |
| Последовательности/PTG | ✅ | - | ✅ |
| Субъекты | ✅ | - | ✅ |
| Симуляция атак | - | - | ✅ |
| Обнаружение дрейфа | - | - | ✅ |
| Метрики ML | - | - | ✅ |
| Управление векторами | - | - | ✅ |
| Список игнорирования сущностей | - | - | ✅ |
| Кандидаты закономерностей | - | - | ✅ |
| Уведомления | - | - | ✅ |
| Происхождение | - | - | ✅ |
| Соответствие требованиям | - | - | ✅ |

### Страницы Frontend
| Страница | Статус | Примечания |
|----------|--------|------------|
| `/reports` | ✅ Работает | Список, создание, просмотр отчетов |
| `/reports/[id]/review` | ✅ Работает | Полный рабочий процесс рецензирования |
| `/analytics/cooccurrence` | ⚠️ Зависит от данных | Показывает KPI, если эпизоды существуют |
| `/analytics/cooccurrence/pairs` | ⚠️ Зависит от данных | Вызывает реальный API |
| `/analytics/cooccurrence/bundles` | ⚠️ Зависит от данных | Вызывает реальный API |
| `/analytics/cooccurrence/actors` | ⚠️ Зависит от данных | Вызывает реальный API |
| `/health` | ✅ Работает | Состояние в реальном времени |

## Устранение неполадок

### Типичные проблемы

1. **Не удалось подключиться к OpenSearch**
   - Убедитесь, что OpenSearch запущен: `curl http://localhost:9200`
   - Проверьте, существует ли индекс: `curl http://localhost:9200/bandjacks_attack_nodes-v1`

2. **Не удалось подключиться к Neo4j**
   - Проверьте, что Neo4j запущен: `neo4j status`
   - Проверьте, что `NEO4J_PASSWORD` установлен в файле `.env`
   - Убедитесь, что пароль соответствует вашему экземпляру Neo4j
   - Если вы видите сообщение "NEO4J_PASSWORD environment variable is required", вам нужно задать его в файле `.env`

3. **Низкая полнота извлечения**
   - Убедитесь, что вы используете метод `agentic_v2`
   - Проверьте, действителен ли ключ API LLM
   - Проверьте, правильное ли имя модели (gemini-flash-latest)

4. **Ошибки тайм-аута**
   - Увеличьте настройки тайм-аута для больших документов
   - Рассмотрите возможность разбивки очень больших отчетов на части

5. **Frontend не подключается к API**
   - Убедитесь, что API запущен на порту 8000
   - Проверьте настройки CORS в конфигурации API

### Режим отладки

Включить подробное логирование:```python
import logging
logging.basicConfig(level=logging.DEBUG)

# Run extraction with debug output
result = run_agentic_v2(text, config)

### Вклад

1. Форкните репозиторий
2. Создайте ветку для новой функции
3. Внесите изменения
4. Запустите тесты: `uv run pytest`
5. Выполните линтинг: `uv run ruff check`
6. Отправьте pull request

### Качество кода```bash
# Format code
uv run ruff format

# Check linting
uv run ruff check

# Type checking
uv run mypy bandjacks