LitterBox: A Self-Hosted Sandbox That Scores Payloads Before You Deploy Them

The gap LitterBox fills between writing a payload and shipping it

Red team payload development has an awkward middle stage. You have something that works against a lab target, and you have no idea whether a modern EDR will flag it in the first thirty seconds. The usual answers are a commercial sandbox you do not control, a manually assembled VM you rebuild every few months, or shipping it and finding out. LitterBox targets that middle stage. The README describes it as "a self-hosted payload-analysis sandbox for red teams" where you upload a sample, run static, dynamic and EDR analysis, and get a Detection Score plus a breakdown of triggering indicators.

The intended user is specific: an operator developing or adapting offensive tooling who wants a local verdict before deployment. The README also notes that blue teams running the same tools in malware-analysis workflows will find it useful, which is honest. The scanner set is not offensive-specific. PE-Sieve, Hollows-Hunter and Moneta are memory-forensics tools that happen to be exactly what you want when checking whether your injection technique leaves artefacts. If you are on the defensive side and already have these binaries, LitterBox is mostly an orchestration and reporting layer over them.

What actually runs when you upload a sample

The architecture is a Python application (3.11+) serving a web UI on port 1337, with scanner binaries under Scanners/ invoked as subprocesses and results correlated into a single report. The scanner table in the README lists twelve entries: PE-Sieve 0.4.1.2, Hollows-Hunter 0.4.1.2, Moneta at commit 5b65395, Patriot, Hunt-Sleeping-Beacons at commit 84dd3a9, RedEdr at commit 3bd6b97 as an EXE-only build, the YARA engine yara64.exe, two YARA rule sets (Elastic's protections-artifacts at commit d131ea8 and YARA-Forge Extended 0.9.1, release 20260503), plus three of the author's own tools: CheckPlz, Stringnalyzer and HolyGrail.

That list is the real substance of the project. The value is not any single scanner, it is that a YARA match, a PE-Sieve memory finding and a sleep-beacon detection land in one view instead of three terminals. The wiki page on the Detection Score is where the weighting is documented, and that page matters more than any other part of the docs, because a composite score is only as good as its inputs. The README does not state the weighting itself, so treat the score as an index into the underlying findings rather than a number to trust on its own.

EDR analysis is a separate path. LitterBox can dispatch payloads to a Windows VM instrumented with Elastic Defend or Fibratus and pull the correlated alerts back into the results page. That is a network hop to a second machine, not a local scanner, and it depends on the Whiskers agent installed on that VM. The wiki has separate setup pages for each EDR.

Getting it running: two install paths with very different costs

On Windows, the path is a venv and a script:

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

The README notes that an admin shell is required and that --debug enables verbose logging. The UI comes up at http://127.0.0.1:1337.

On Linux the project ships a Docker path under Docker/:

cd LitterBox/Docker chmod +x setup.sh ./setup.sh

That script provisions a Windows 10 container with KVM and runs LitterBox inside it. The README states the initial build takes roughly one hour. Three endpoints come out of it: the install monitor at http://localhost:8006, RDP at localhost:3389 with credentials in the docker compose file, and the LitterBox UI at http://127.0.0.1:1337 once setup finishes.

EDR profiles are dropped as YAML files under Config/edr_profiles/ and the upload page picks them up at boot. The Configuration Reference wiki page covers scanner paths and timeouts. Adding a scanner is documented separately, which suggests the scanner interface is meant to be extended rather than treated as fixed.

The scanner refresh problem is the maintenance bill

Bundled binaries age. The README's own table shows the spread: Moneta and the YARA engine both carry a 2024-12-29 date, Patriot 2024-12-29, Stringnalyzer 2025-01-27, HolyGrail 2025-08-18, while PE-Sieve, RedEdr and the YARA-Forge rules are dated within days of the v5.0.0 release in May 2026. The table exists precisely so an operator can see at a glance whether a scanner is current, and the README spells out the refresh procedure: replace the binary under Scanners/<Name>/ and update the row.

That is a manual maintenance loop with no automation described. If you run LitterBox for a year without touching it, your YARA rules and your memory scanners drift, and a clean Detection Score means less each month. The version format is also worth reading carefully: a version in backticks is a commit hash built from source, which means reproducing that build later requires the upstream repository to still have that commit.

Licence is GPL-3.0. If you modify LitterBox and distribute it, or run a modified version as a network service for others, the GPL's obligations are the ones to read. Bundling third-party scanner binaries (PE-Sieve, Moneta, YARA, Elastic's rule set) means you inherit their licences too, and those are not all the same. The README does not summarise the licence of each bundled component. Check them individually before any redistribution. None of this is legal advice.

Where LitterBox is the wrong tool

The security advisory in the README is blunt: development use only, isolation required, run only in isolated VMs or dedicated testing environments, no warranty. Take that literally. A sandbox that executes payloads and hosts an EDR-instrumented Windows VM on your network is a target, and the Docker path exposes RDP on localhost:3389 with credentials sitting in a compose file.

The Linux path also assumes KVM. Nested virtualisation on a cloud instance frequently is not available, and the one-hour build is a poor fit for ephemeral CI. If your workflow is "analyse this sample in a pipeline and throw the VM away", the Docker setup is heavier than the job.

Detection Score is a composite. A single number compresses twelve scanners into one figure, and the composition is documented in the wiki rather than the README. If your threat model is one specific EDR product, the Elastic Defend or Fibratus dispatch path is the part that answers your question; the aggregate score is a summary, not a verdict. And if you need to detonate live malware at scale, with legal cover and retention policies, a managed sandbox service handles that as a product rather than a side effect.

How this differs from CAPE, Cuckoo-lineage sandboxes and a bare VM

The closest comparison is CAPE, the maintained fork in the Cuckoo lineage. CAPE is built around behavioural monitoring: it hooks the guest, records API calls, network traffic and dropped files, and produces a behavioural report. LitterBox does not describe a behavioural monitor of that kind. It runs a fixed set of memory and static scanners as subprocesses and aggregates their output. The difference matters. CAPE tells you what the sample did over time; LitterBox tells you which artefacts the sample left and which rules fired. If your question is "does my loader trip a YARA rule or leave an unbacked executable region in memory", the scanner-aggregation model answers it directly. If your question is "what registry keys did this write", you want a behavioural sandbox.

The second comparison is a hand-built analysis VM, which is what most people actually use. A VM with PE-Sieve and YARA installed manually does the same work. What LitterBox adds is orchestration, a persistent results store, and the MCP layer, which lets an LLM agent drive analysis end to end rather than a human copying command output into a report. Whether that last part is useful depends entirely on whether you already run agent tooling against your analysis workflow. If you do not, the MCP server is inert weight.

Who should adopt it, and what to check on day one

LitterBox fits a team that develops offensive tooling in-house, already runs isolated Windows infrastructure, and wants a local gate before a payload goes to a customer. It also fits a blue team that already has these scanners and wants them in one place with a shared result format.

It does not fit anyone without a dedicated isolated environment, anyone who needs cloud-scale malware detonation with legal cover, or anyone who will not maintain the scanner table. The manual refresh loop is the deciding factor. If nobody owns updating Scanners/<Name>/ and the README table, the Detection Score quietly becomes a historical artefact.

Verify first: the versions of the bundled binaries against the README table, since several entries are months behind the most recent ones; that your EDR profile YAML loads at boot by checking the upload page after dropping it in Config/edr_profiles/; and the Detection Score weighting in the wiki, so you know whether the number reflects the scanners you care about. The GPL-3.0 licence and the licences of the bundled third-party binaries are a separate review before any redistribution.

Editorial conclusion

Adopt LitterBox if you run offensive tooling development and want a repeatable local gate before a payload touches a customer environment, and if you already operate isolated Windows infrastructure with KVM available. Skip it if you need a managed or cloud sandbox, if you cannot dedicate a Windows VM plus an EDR licence, or if your samples are live malware you are not licensed to detonate. Before committing, verify three things: that the bundled scanner binaries under Scanners/ are at the versions the README table claims, that your chosen EDR profile YAML under Config/edr_profiles/ actually loads at boot, and that the Detection Score weighting described in the wiki matches the detection sources you care about.

Official sources

1. BlackSnufkin/LitterBox on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases