Bandjacks

Cyber Threat Defense World Modeling System

Overview

Bandjacks is a comprehensive cyber threat intelligence (CTI) system that:

• Extracts MITRE ATT&CK techniques from threat reports in 12-40 seconds
• Builds a knowledge graph of threat actors, techniques, and defenses
• Generates STIX 2.1 compliant bundles with full provenance tracking
• Integrates D3FEND ontology for defensive recommendations
• Provides vector search and graph analytics capabilities
• Computes co-occurrence analytics to identify technique patterns
• Features 94% faster extraction than earlier versions with LLM response caching
• Includes a Next.js frontend for report review and analytics visualization

📚 Documentation

Guide	Description
Quick Start	Get running in 5 minutes
Full Setup	Complete environment setup
CLI Usage	Command-line interface guide
API Reference	REST API documentation
Co-occurrence Analytics	Analytics documentation
AttackFlow Generation	Flow generation guide
Review System	Human-in-the-loop review

Architecture Highlights

TechniqueCache

• In-memory cache of all MITRE ATT&CK techniques loaded at startup
• O(1) lookups by external_id (e.g., T1557) for instant name resolution
• 1376 techniques cached with full metadata (name, description, tactics, platforms)
• Consistent naming ensures review UI always shows human-readable technique names

ActorCache

• In-memory cache of all intrusion sets and threat actors
• Fast lookups for actor name resolution and search
• Supports alias matching and fuzzy search

Quick Start

Prerequisites

• Python 3.11+
• Neo4j 5.x (graph database)
• OpenSearch 2.x (vector store)
• Redis (optional, for caching)
• Node.js 18+ (for frontend)
• LLM access: cloud API keys (Gemini or OpenAI) or a local OpenAI-compatible server

Installation

# 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 ..

Environment Setup

IMPORTANT: You must configure environment variables before starting the application. The application requires NEO4J_PASSWORD to be set.

Create a .env file in the project root:

# Copy the sample file
cp infra/env.sample .env

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

Required configuration in .env:

# 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

Note: The application will fail to start if NEO4J_PASSWORD is not set. See Environment Variables Fix for details.

Starting the Services

# 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

Command-Line Interface (CLI)

Bandjacks includes a comprehensive CLI for threat intelligence operations:

# Show all available commands
uv run python -m bandjacks.cli.main --help

Note: The CLI requires environment variables to be set (NEO4J_PASSWORD, etc.). Run from the project root where .env is located.

Query Commands

# 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

Review Queue Management

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

Document Extraction

# Extract CTI from a document
uv run python -m bandjacks.cli.main extract document ./report.pdf --confidence-threshold 80 --show-evidence

Analytics Commands

Note: Analytics commands require AttackEpisode data in Neo4j to return results.

# 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

Workflow Commands

# 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/

Admin Commands

# 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

Frontend UI

The Next.js frontend provides a modern interface for working with the system.

Report Management (/reports)

• Report List: View all ingested reports with status and technique counts
• New Report (/reports/new): Upload PDF/TXT files or paste report content
• Report Detail (/reports/[id]): View extracted techniques, entities, and evidence
• Review Interface (/reports/[id]/review): Human-in-the-loop review workflow

Co-occurrence Analytics (/analytics/cooccurrence)