Bandjacks

网络威胁防御世界建模系统

概述

Bandjacks 是一个全面的网络威胁情报（CTI）系统，能够：

• 在 12-40 秒内 从威胁报告中提取 MITRE ATT&CK 技术
• 构建威胁行为者、技术和防御措施的知识图谱
• 生成符合 STIX 2.1 的捆绑包，并带有完整的溯源追踪
• 集成 D3FEND 本体以提供防御建议
• 提供向量搜索和图分析能力
• 计算 共现分析 以识别技术模式
• 通过 LLM 响应缓存，提取速度比早期版本快 94%
• 包含 Next.js 前端 用于报告审核和分析可视化

📚 文档

指南	描述
快速开始	在 5 分钟内启动并运行
完整安装	完整的环境设置
CLI 使用	命令行界面指南
API 参考	REST API 文档
共现分析	分析文档
攻击流生成	流程生成指南
审核系统	人机交互审核

架构亮点

TechniqueCache

• 启动时加载所有 MITRE ATT&CK 技术的 内存缓存
• 通过 external_id（例如 T1557）进行 O(1) 查找，实现即时名称解析
• 缓存 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

Required configuration in .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`，应用程序将无法启动。详情请参阅 [Environment Variables Fix](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

分析命令

注意： 分析命令需要Neo4j中的AttackEpisode数据才能返回结果。```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 的前端提供了用于操作系统的现代界面。

### 报告管理 (`/reports`)
- **报告列表**: 查看所有已导入的报告及其状态和技术计数
- **新建报告** (`/reports/new`): 上传 PDF/TXT 文件或粘贴报告内容
- **报告详情** (`/reports/[id]`): 查看提取的技术、实体和证据
- **审核界面** (`/reports/[id]/review`): 人机协同审核工作流

### 共现分析 (`/analytics/cooccurrence`)

> **注意:** 这些页面需要 Neo4j 中存在 `AttackEpisode` 数据。请先通过提取流程处理报告，或使用 `POST /v1/flows/build` 从入侵集数据生成事件。

- **中心页面**: 概览页面，显示事件/技术/行为者计数
- **热门配对** (`/pairs`): 共现技术配对及其 NPMI/提升度指标
- **条件概率** (`/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

使用指南

1. 加载 MITRE ATT&CK 数据

首先，将 MITRE ATT&CK 框架加载到您的知识图谱中：```bash

Load the latest enterprise ATT&CK release

curl -X POST "http://localhost:8000/v1/stix/load/attack"
-H "Content-Type: application/json"
-d '{ "collection": "enterprise-attack", "version": "latest", "adm_strict": false }'

### 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")