Bandjacks

Система моделирования мира для киберугроз

Обзор

Bandjacks — это всеобъемлющая система киберразведки угроз (CTI), которая:

• Извлекает техники MITRE ATT&CK из отчетов об угрозах за 12–40 секунд
• Строит граф знаний угрозных акторов, техник и защит
• Генерирует совместимые с STIX 2.1 пакеты с полным отслеживанием происхождения
• Интегрирует онтологию D3FEND для рекомендаций по защите
• Предоставляет возможности векторного поиска и аналитики графов
• Вычисляет анализ совместной встречаемости для выявления паттернов техник
• Обеспечивает извлечение на 94% быстрее предыдущих версий благодаря кэшированию ответов LLM
• Включает фронтенд на Next.js для проверки отчетов и визуализации аналитики

📚 Документация

Руководство	Описание
Быстрый старт	Запуск за 5 минут
Полная настройка	Полная настройка окружения
Использование CLI	Руководство по интерфейсу командной строки
Справочник API	Документация REST API
Анализ совместной встречаемости	Документация по аналитике
Генерация AttackFlow	Руководство по созданию потоков
Система проверки	Проверка с участием человека

Основные архитектурные особенности

TechniqueCache

• Кэш в памяти всех техник MITRE ATT&CK, загружаемых при запуске
• Поиск за O(1) по external_id (например, T1557) для мгновенного определения имени
• 1376 техник кэшированы с полными метаданными (название, описание, тактики, платформы)
• Единообразие имен гарантирует, что в интерфейсе проверки всегда отображаются читаемые названия техник

ActorCache

• Кэш в памяти всех наборов вторжений и угрозных акторов
• Быстрый поиск для определения имени актора и его поиска
• Поддерживает сопоставление псевдонимов и нечеткий поиск

Быстрый старт

Необходимые компоненты

• Python 3.11+
• Neo4j 5.x (графовая база данных)
• OpenSearch 2.x (векторное хранилище)
• Redis (опционально, для кэширования)
• Node.js 18+ (для фронтенда)
• Доступ к LLM: облачные ключи API (Gemini или OpenAI) или локальный сервер, совместимый с OpenAI

Установка```bash

Clone the repository

git clone https://github.com/yourusername/bandjacks.git cd bandjacks

Install Python dependencies with uv (recommended)

uv sync

Or with pip

pip install -e .

Install frontend dependencies

cd ui && npm install && cd ..

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

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

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

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

Требуемая конфигурация в .env:```bash

Neo4j Configuration (REQUIRED)

NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=your-actual-neo4j-password # MUST BE SET - no default provided

OpenSearch Configuration

OPENSEARCH_URL=http://localhost:9200 OPENSEARCH_USER=admin OPENSEARCH_PASSWORD=your-opensearch-password # Optional if security is disabled

LLM Configuration — pick ONE of the options below:

Option A: Local OpenAI-compatible API (vLLM, llama.cpp, Ollama, LocalAI, LM Studio, etc.)

LOCAL_LLM_API_BASE=http://192.168.1.100:8080/v1 # Base URL of your local server LOCAL_LLM_MODEL=mistral-nemo # Model name as the server reports it LOCAL_LLM_API_KEY=no-key # Most local servers accept any value

Option B: Cloud LLM providers

PRIMARY_LLM=gemini GOOGLE_API_KEY=your-gemini-api-key

Optional: OpenAI as fallback (or primary if PRIMARY_LLM=openai)

OPENAI_API_KEY=your-openai-api-key

ATT&CK Configuration

ATTACK_INDEX_URL=https://raw.githubusercontent.com/mitre-attack/attack-stix-data/master/index.json ATTACK_COLLECTION=enterprise-attack ATTACK_VERSION=latest

Redis (optional, for caching)

REDIS_URL=redis://localhost:6379

**Примечание:** Приложение не запустится, если не задан `NEO4J_PASSWORD`. Подробнее см. [Исправление переменных окружения](https://github.com/blevene/bandjacks/blob/main/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)

Bandjacks включает полноценный CLI для операций разведки угроз:```bash

Show all available commands

uv run python -m bandjacks.cli.main --help

> **Примечание:** 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

Show review queue

uv run python -m bandjacks.cli.main review queue --status pending --limit 20

Approve a candidate

uv run python -m bandjacks.cli.main review approve "candidate-123" --reviewer analyst-1

Reject with reason

uv run python -m bandjacks.cli.main review reject "candidate-456" --reviewer analyst-1 --reason "False positive"

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

Команды аналитики

Примечание: Команды аналитики требуют данных AttackEpisode в Neo4j для возврата результатов.```bash

Show top co-occurring technique pairs

uv run python -m bandjacks.cli.main analytics top-cooccurrence --limit 25 --min-episode-size 2

Compute conditional co-occurrence P(B|A) for a technique

uv run python -m bandjacks.cli.main analytics conditional "attack-pattern--abc123" --limit 25

Analyze a specific threat actor

uv run python -m bandjacks.cli.main analytics actor "intrusion-set--xyz789" --metric npmi

Extract technique bundles

uv run python -m bandjacks.cli.main analytics bundles --min-support 3 --min-size 3 --max-size 5 --format json --output bundles.json

Global co-occurrence metrics

uv run python -m bandjacks.cli.main analytics global --min-support 2 --limit 50 --format csv --output pairs.csv

### Команды рабочего процесса```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/

Команды администратора```bash

Check system health

uv run python -m bandjacks.cli.main admin health

View cache statistics

uv run python -m bandjacks.cli.main admin cache-stats

Clear cache

uv run python -m bandjacks.cli.main admin cache-clear --pattern "search:*"

Optimize database

uv run python -m bandjacks.cli.main admin optimize

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

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