LitterBox

A self-hosted payload-analysis sandbox for red teams. Upload a sample, run static / dynamic / EDR analysis against it, get a Detection Score and a triggering-indicators breakdown — decide whether the payload is field-ready before it leaves the lab.

LitterBox can also dispatch payloads to a separate EDR-instrumented Windows VM (Elastic Defend or Fibratus) and pull the correlated detection alerts back into the results page.

While designed primarily for red teams, LitterBox is equally useful for blue teams running the same tools in their malware-analysis workflows.

Documentation

Operator and developer documentation lives in the LitterBox Wiki.

Topic	Wiki page
How everything fits together	Application Architecture
Run static + every reachable EDR in parallel	All in One Pipeline
Dispatch payloads to a real EDR VM	EDR Integration → Elastic Defend / Fibratus
Whiskers agent (install, endpoints, build)	Whiskers Agent
Every HTTP endpoint	HTTP API Reference
CLI / Python lib / MCP for LLMs	GrumpyCats CLI · GrumpyCats Library · LitterBoxMCP
What feeds the Detection Score	Detection Score Explained
Configure scanners / paths / timeouts	Configuration Reference
Add custom YARA rules / scanners	YARA Rules Management · New Scanner

Installation

Windows

git clone https://github.com/BlackSnufkin/LitterBox.git
cd LitterBox
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
python litterbox.py            # add --debug for verbose logging

Open http://127.0.0.1:1337. Requires Python 3.11+ and an admin shell.

Linux (Docker)

git clone https://github.com/BlackSnufkin/LitterBox.git
cd LitterBox/Docker
chmod +x setup.sh
./setup.sh

The setup script provisions a Windows 10 container with KVM and runs LitterBox inside. Initial build takes ~1 hour.

• Install monitor: http://localhost:8006
• RDP: localhost:3389 (creds in the docker compose file)
• LitterBox UI: http://127.0.0.1:1337 once setup completes

EDR setup (optional)

Drop one or more profile YAMLs under Config/edr_profiles/ and the upload page picks them up at boot. Full walkthroughs in the wiki: Whiskers Agent → Elastic Defend Setup or Fibratus Setup.

Scanners

Bundled binaries under Scanners/. Versions and last-update dates tracked here so operators can tell at a glance whether a scanner is current.