A secure sandbox environment for malware developers and red teamers to test payloads against detection mechanisms before deployment. Integrates with LLM agents via MCP for enhanced analysis capabiliti
LitterBox provides a controlled sandbox environment designed for security professionals to develop and test payloads. This platform allows red teams to:
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.
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 |
For Windows PE files (.exe, .dll, .sys):
For Microsoft Office files:
Available in dual operation modes:
Capabilities include:
Provides system-wide process comparison by:
Delivers code similarity analysis through:
POST /upload # Upload samples for analysis
GET /files # Retrieve processed file list
GET /analyze/static/<hash> # Execute static analysis
POST /analyze/dynamic/<hash> # Perform dynamic file analysis
POST /analyze/dynamic/<pid> # Conduct process analysis
# 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"}
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/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)
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 /health # System health verification
POST /cleanup # Remove analysis artifacts
POST /validate/<pid> # Verify process accessibility
DELETE /file/<hash> # Remove specific analysis
git clone https://github.com/BlackSnufkin/LitterBox.git
cd LitterBox
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
Standard operation:
python litterbox.py
Diagnostic mode:
python litterbox.py --debug
LitterBox offers three access interfaces:
http://127.0.0.1:1337
For API access, see the Client Libraries section.
All settings are stored in config/config.yml
. Edit this file to:
For programmatic access to LitterBox, use the GrumpyCats package:
The package includes:
Development contributions should be conducted in feature branches on personal forks.
For detailed contribution guidelines, refer to: CONTRIBUTING.md
This project incorporates technologies from the following contributors:
BlackSnufkin/LitterBox
December 25, 2024
July 5, 2025
YARA