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.

| Scanner | Version | Last updated | Source | |---|---|---|---| | PE-Sieve | 0.4.1.2 (f1dc39d) | 2026-05-02 | hasherezade/pe-sieve | | Hollows-Hunter | 0.4.1.2 (e271f7e) | 2026-04-18 | hasherezade/hollows_hunter | | Moneta | 5b65395 | 2024-03-16 | forrest-orr/moneta | | Patriot | — | 2024-12-29 | joe-desimone/patriot | | Hunt-Sleeping-Beacons | 84dd3a9 | 2026-01-25 | thefLink/Hunt-Sleeping-Beacons | | RedEdr | 3bd6b97 (EXE-only build) | 2026-05-03 | dobin/RedEdr | | YARA (engine yara64.exe) | — | 2024-12-29 | VirusTotal/yara | | Elastic YARA rules (Scanners/Yara/rules/elastic-yara/) | d131ea8 | 2026-04-30 | elastic/protections-artifacts | | YARA-Forge Extended (Scanners/Yara/rules/YARAForge/) | 0.9.1 (release 20260503) | 2026-05-03 | YARAHQ/yara-forge | | CheckPlz | — | 2024-12-29 | BlackSnufkin/CheckPlz | | Stringnalyzer | — | 2025-01-27 | BlackSnufkin/Rusty-Playground | | HolyGrail | — | 2025-08-18 | BlackSnufkin/HolyGrail |

Version format: <release-version> or <release-version> (release) when the binary is pulled from an upstream release; <release-version> (\<commit>`)or just`<commit>`` when built from source. Last-updated date is the upstream commit / release date, not the local build date.

When you refresh a scanner: replace the binary under its Scanners/<Name>/ directory and update the row above (version + date).

Contributing

See CONTRIBUTING.md. Work in feature branches on personal forks.

Support 🍺

<a href="https://www.buymeacoffee.com/blacksnufkin"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" width="200" height="60"></a>

Security Advisory

• Development use only. This platform is designed for testing environments. Production deployment presents significant security risks.
• Isolation required. Run only in isolated VMs or dedicated testing environments.
• No warranty. Provided without guarantees; use at your own risk.
• Legal compliance. Users are responsible for ensuring usage complies with applicable laws.

Acknowledgments

LitterBox stands on the work of these projects and their authors:

| Tool | Author | |---|---| | YARA rules · Elastic Defend | Elastic Security | | PE-Sieve · Hollows-Hunter | hasherezade | | Moneta | Forrest Orr | | Patriot | joe-desimone | | Hunt-Sleeping-Beacons | thefLink | | RedEdr | dobin | | Fibratus | rabbitstack | | ThreatCheck (basis for CheckPlz) | rasta-mouse | | MalAPI reference DB | mr.d0x |

Interface