Overview

LitterBox provides a controlled sandbox environment designed for security professionals to develop and test payloads. This platform allows red teams to:

• Test evasion techniques against modern detection techniques
• Validate detection signatures before field deployment
• Analyze malware behavior in an isolated environment
• Keep payloads in-house without exposing them to external security vendors
• Ensure payload functionality without triggering production security controls

The platform includes LLM-assisted analysis capabilities through the LitterBoxMCP server, offering advanced analytical insights using natural language processing technology.

Note: While designed primarily for red teams, LitterBox can be equally valuable for blue teams by shifting perspective – using the same tools in their malware analysis workflows.

Documentation

LitterBox Wiki - Advanced configuration and technical guides

Key sections:

• Scanner Configuration - HolyGrail, Blender, and FuzzyHash setup
• YARA Rules Management - Custom rules and organization
• Configuration Reference - Complete config.yml options
• Architecture & Development - System design and custom scanners

Analysis Capabilities

Initial Processing

| Feature | Description | |---------|-------------| | File Identification | Multiple hashing algorithms (MD5, SHA256) | | Entropy Analysis | Detection of encryption and obfuscation | | Type Classification | Advanced MIME and file type analysis | | Metadata Preservation | Original filename and timestamp tracking | | Runtime detection | Compiled binary identification

Executable Analysis

For Windows PE files (.exe, .dll, .sys):

• Architecture identification (PE32/PE32+)
• Compilation timestamp verification
• Subsystem classification
• Entry point analysis
• Section enumeration and characterization
• Import/export table mapping
• Runtime detection for Go and Rust binaries with specialized import analysis

Document Analysis

For Microsoft Office files:

• Macro detection and extraction
• VBA code security analysis
• Hidden content identification
• Obfuscation technique detection

LNK Analysis

For Windows shortcut Files (.lnk)

• Target execution paths and arguments
• Machine tracking identifiers
• Timestamps and file attributes
• Network share information
• Volume and drive details
• Environment variables and metadata

Analysis Engines

Static Analysis

• Industry-standard signature detection
• Binary entropy profiling
• String extraction and classification
• Pattern matching for known indicators

Dynamic Analysis

Available in dual operation modes:

• File Analysis: Focused on submitted samples
• Process Analysis: Targeting running processes by PID

Capabilities include:

• Runtime behavioral monitoring
• Memory region inspection and classification
• Process hollowing detection
• Code injection technique identification
• Sleep pattern analysis
• Windows telemetry collection via ETW

HolyGrail BYOVD Analysis

Find undetected legitimate drivers for BYOVD attacks:

• LOLDrivers Database: Cross-reference against known vulnerable drivers
• Windows Block Policy: Validation against Microsoft's recommended driver block rules for Windows 10/11
• Dangerous Import Analysis: Detection of privileged functions commonly exploited in BYOVD attacks
• BYOVD Score Calculation: Risk assessment based on exploitation potential and defensive controls

Doppelganger Analysis

Blender Module

Provides system-wide process comparison by:

• Collecting IOCs from active processes
• Comparing process characteristics with submitted payloads
• Identifying behavioral similarities

FuzzyHash Module

Delivers code similarity analysis through:

• Maintained database of known tools and malware
• ssdeep fuzzy hash comparison methodology
• Detailed similarity scoring and reporting

Integrated Tools

Static Analysis Suite

• YARA - Signature detection engine
• CheckPlz - AV detection testing framework
• Stringnalyzer - Advanced string analysis utility
• HolyGrail - BYOVD Hunter

Dynamic Analysis Suite

• YARA Memory - Runtime pattern detection
• PE-Sieve - In-memory malware detection
• Moneta - Memory region IOC analyzer
• Patriot - In-memory stealth technique detection
• RedEdr - ETW telemetry collection
• Hunt-Sleeping-Beacons - C2 beacon analyzer
• Hollows-Hunter - Process hollowing detection

API Reference

File Operations

POST   /upload                    # Upload samples for analysis
GET    /files                     # Retrieve processed file list

Analysis Endpoints

GET    /analyze/static/<hash>     # Execute static analysis
POST   /analyze/dynamic/<hash>    # Perform dynamic file analysis  
POST   /analyze/dynamic/<pid>     # Conduct process analysis

HolyGrail BYOVD Analysis

POST   /holygrail                 # Upload driver for BYOVD analysis
GET    /holygrail?hash=<hash>     # Execute BYOVD analysis on uploaded driver

Doppelganger API

# Blender Module
GET    /doppelganger?type=blender               # Retrieve latest scan results
GET    /doppelganger?type=blender&hash=<hash>   # Compare process IOCs with payload  
POST   /doppelganger                            # Execute system scan with {"type": "blender", "operation": "scan"}

# FuzzyHash Module
GET    /doppelganger?type=fuzzy                 # Retrieve fuzzy analysis statistics
GET    /doppelganger?type=fuzzy&hash=<hash>     # Execute fuzzy hash analysis
POST   /doppelganger                            # Generate database with {"type": "fuzzy", "operation": "create_db", "folder_path": "C:\path\to\folder"}

Results Retrieval (JSON)

GET    /api/results/<hash>/info      # Retrieve file metadata
GET    /api/results/<hash>/static    # Access static analysis results
GET    /api/results/<hash>/dynamic   # Obtain dynamic analysis data
GET    /api/results/<pid>/dynamic    # Retrieve process analysis data
GET    /api/results/<hash>/holygrail # Access BYOVD analysis results

HTML Report Generation

GET    /api/report/          # Generate comprehensive HTML report (target = hash or pid)
GET    /api/report/?download=true  # Download report as file attachment
GET    /report/              # Download report directly (redirects to api with download=true)

Web Interface Results

GET    /results/<hash>/info      # View file information
GET    /results/<hash>/static    # Access static analysis reports
GET    /results/<hash>/dynamic   # View dynamic analysis reports
GET    /results/<pid>/dynamic    # Access process analysis reports
GET    /results/<hash>/byovd     # View BYOVD analysis results

System Management

GET    /health                   # System health verification
POST   /cleanup                  # Remove analysis artifacts
POST   /validate/<pid>           # Verify process accessibility
DELETE /file/<hash>              # Remove specific analysis

Installation

Windows Installation

System Requirements:

• Windows operating system
• Python 3.11 or higher
• Administrator privileges

Deployment Process:

1. Clone the repository:

git clone https://github.com/BlackSnufkin/LitterBox.git
cd LitterBox

2. Configure environment:

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

Operation:

# Standard operation
python litterbox.py

# Diagnostic mode
python litterbox.py --debug

Access:

• Web UI: http://127.0.0.1:1337
• API Access: Python client integration
• LLM Integration: MCP server

Linux Installation

System Requirements:

• Linux operating system
• Docker and Docker Compose
• Hardware virtualization support

Deployment Process:

1. Clone the repository:

git clone https://github.com/BlackSnufkin/LitterBox.git
cd LitterBox/Docker

2. Ru