Content
# LitterBox
[]()
[]()
[]()
[]()
[]()
[](https://github.com/BlackSnufkin/LitterBox/stargazers)
## Table of Contents
- [Overview](#overview)
- [Documentation](#documentation)
- [Analysis Capabilities](#analysis-capabilities)
- [Analysis Engines](#analysis-engines)
- [Integrated Tools](#integrated-tools)
- [API Reference](#api-reference)
- [Installation](#installation)
- [Windows Installation](#windows-installation)
- [Linux Installation (Docker)](#linux-installation)
- [Configuration](#configuration)
- [Client Libraries](#client-libraries)
- [Contributing](#contributing)
- [Security Advisory](#security-advisory)
- [Acknowledgments](#acknowledgments)
- [Interface](#interface)
## 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](../../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](https://github.com/elastic/protections-artifacts/tree/main/yara) - Signature detection engine
- [CheckPlz](https://github.com/BlackSnufkin/CheckPlz) - AV detection testing framework
- [Stringnalyzer](https://github.com/BlackSnufkin/Rusty-Playground/tree/main/Stringnalyzer) - Advanced string analysis utility
- [HolyGrail](https://github.com/BlackSnufkin/HolyGrail) - BYOVD Hunter
### Dynamic Analysis Suite
- [YARA Memory](https://github.com/elastic/protections-artifacts/tree/main/yara) - Runtime pattern detection
- [PE-Sieve](https://github.com/hasherezade/pe-sieve) - In-memory malware detection
- [Moneta](https://github.com/forrest-orr/moneta) - Memory region IOC analyzer
- [Patriot](https://github.com/BlackSnufkin/patriot) - In-memory stealth technique detection
- [RedEdr](https://github.com/dobin/RedEdr) - ETW telemetry collection
- [Hunt-Sleeping-Beacons](https://github.com/thefLink/Hunt-Sleeping-Beacons) - C2 beacon analyzer
- [Hollows-Hunter](https://github.com/hasherezade/hollows_hunter) - Process hollowing detection
## API Reference
### File Operations
```http
POST /upload # Upload samples for analysis
GET /files # Retrieve processed file list
```
### Analysis Endpoints
```http
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
```http
POST /holygrail # Upload driver for BYOVD analysis
GET /holygrail?hash=<hash> # Execute BYOVD analysis on uploaded driver
```
### Doppelganger API
```http
# 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)
```http
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
```http
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
```http
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
```http
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:
```bash
git clone https://github.com/BlackSnufkin/LitterBox.git
cd LitterBox
```
2. Configure environment:
```bash
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
```
**Operation:**
```bash
# 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:
```bash
git clone https://github.com/BlackSnufkin/LitterBox.git
cd LitterBox/Docker
```
2. Run automated setup:
```bash
chmod +x setup.sh
./setup.sh
```
> **Note**: Initial setup takes approximately `1 hour` depending on internet speed and system resources.
The setup script automatically:
- Installs Docker, Docker Compose, and CPU checker
- Verifies KVM hardware virtualization support
- Creates Windows 10 container environment with automated LitterBox installation
- Starts containerized Windows instance
**Access:**
- **Installation monitor**: `http://localhost:8006` (track Windows setup progress)
- **RDP access**: `localhost:3389` (available after installation completes, creds in docker file)
Once installation completes, LitterBox provides:
- **Web UI**: `http://127.0.0.1:1337`
- **API Access**: Python client integration
- **LLM Integration**: MCP server
---
>For API access, see the [Client Libraries](#client-libraries) section.
## Configuration
All settings are stored in `config/config.yml`. Edit this file to:
- Change server settings (host/port)
- Set allowed file types
- Configure analysis tools
- Adjust timeouts
## Client Libraries
For programmatic access to LitterBox, use the **GrumpyCats** package:
**[GrumpyCats Documentation](GrumpyCats/README.md)**
The package includes:
* **grumpycat.py**: Dual-purpose tool that functions as:
* Standalone CLI utility for direct server interaction
* Python library for integrating LitterBox capabilities into custom tools
* **LitterBoxMCP.py**: Specialized server component that:
* Wraps the GrumpyCat library functionality
* Enables LLM agents to interact with the LitterBox analysis platform
* Provides natural language interfaces to malware analysis workflows
## Contributing
Development contributions should be conducted in feature branches on personal forks.
For detailed contribution guidelines, refer to: [CONTRIBUTING.md](./CONTRIBUTING.md)
## Support 🍺
If LitterBox has been useful for your security research:
<a href="https://www.buymeacoffee.com/blacksnufkin"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" width="200" height="60"></a>
## Stargazers 🌟
[](https://starchart.cc/blacksnufkin/litterbox)
## Security Advisory
- **DEVELOPMENT USE ONLY**: This platform is designed exclusively for testing environments. Production deployment presents significant security risks.
- **ISOLATION REQUIRED**: Execute only in isolated virtual machines or dedicated testing environments.
- **WARRANTY DISCLAIMER**: Provided without guarantees; use at your own risk.
- **LEGAL COMPLIANCE**: Users are responsible for ensuring all usage complies with applicable laws and regulations.
## Acknowledgments
This project incorporates technologies from the following contributors:
- [Elastic Security](https://github.com/elastic/protections-artifacts/tree/main/yara)
- [hasherezade](https://github.com/hasherezade/pe-sieve)
- [Forrest Orr](https://github.com/forrest-orr/moneta)
- [rasta-mouse](https://github.com/rasta-mouse/ThreatCheck)
- [thefLink](https://github.com/thefLink/Hunt-Sleeping-Beacons)
- [joe-desimone](https://github.com/joe-desimone/patriot)
- [dobin](https://github.com/dobin/RedEdr)
- [mr.d0x](https://malapi.io/)
## Interface
