Bandjacks

サイバー脅威防御世界モデリングシステム

概要

Bandjacksは、包括的なサイバー脅威インテリジェンス（CTI）システムであり、次の機能を提供します：

• 脅威レポートからMITRE ATT&CKの手法を12～40秒で抽出
• 脅威アクター、手法、防御策の知識グラフを構築
• 完全な出所追跡機能を備えたSTIX 2.1準拠のバンドルを生成
• 防御推奨のためのD3FENDオントロジーを統合
• ベクトル検索とグラフ分析機能を提供
• 共起分析を計算して手法パターンを特定
• LLM応答キャッシュにより、従来版よりも抽出速度が94%向上
• レポートレビューと分析可視化のためのNext.jsフロントエンドを含む

📚 ドキュメント

ガイド	説明
クイックスタート	5分で実行開始
完全セットアップ	完全な環境構築
CLIの使い方	コマンドラインインターフェースガイド
APIリファレンス	REST APIドキュメント
共起分析	分析ドキュメント
AttackFlow生成	フロー生成ガイド
レビューシステム	人間参加型レビュー

アーキテクチャのハイライト

TechniqueCache

• 起動時にロードされるすべてのMITRE ATT&CK手法のインメモリキャッシュ
• external_id（例：T1557）によるO(1)検索で瞬時に名前解決
• 1376の手法が完全なメタデータ（名前、説明、戦術、プラットフォーム）でキャッシュされる
• 一貫した命名により、レビューUIが常に人間が読める手法名を表示

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

分析コマンド

注記: 分析コマンドが結果を返すには、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

## フロントエンドUI

Next.jsのフロントエンドは、システムを操作するためのモダンなインターフェースを提供します。

### レポート管理 (`/reports`)
- **レポート一覧**: 取り込まれたすべてのレポートをステータスおよびテクニック数とともに表示
- **新規レポート** (`/reports/new`): PDF/TXTファイルのアップロードまたはレポート内容の貼り付け
- **レポート詳細** (`/reports/[id]`): 抽出されたテクニック、エンティティ、証拠を表示
- **レビューインターフェース** (`/reports/[id]/review`): ヒューマンインザループのレビューワークフロー

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

> **注意:** これらのページにはNeo4j内の`AttackEpisode`データが必要です。まず抽出パイプラインを通じてレポートを処理するか、`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

Usage Guide

1. Loading MITRE ATT&CK Data

まず、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