Skip to content
Back to search

LitterBox

A self-hosted sandbox for red teams to test payloads against modern detection before deployment. MCP integration lets an LLM agent drive analysis end to end.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/blacksnufkin--litterbox/badge.svg)](/listings/blacksnufkin--litterbox)

HTML

<a href="/listings/blacksnufkin--litterbox"><img src="/api/listings/blacksnufkin--litterbox/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](../../wiki/Whiskers-Agent) → [Elastic Defend Setup](../../wiki/Elastic-Defend-Setup) or [Fibratus Setup](../../wiki/Fibratus-Setup).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 127 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # LitterBox
  2. ![LitterBox Logo](Screenshots/lb-logo.png)
  3. [![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=plastic&logo=python&logoColor=white)]()
  4. [![Windows](https://img.shields.io/badge/Windows-Supported-0078D6?style=plastic&logo=onlyfans&logoColor=black)]()
  5. [![Linux](https://img.shields.io/badge/Linux-Supported-FCC624?style=plastic&logo=linux&logoColor=black)]()
  6. [![Docker](https://img.shields.io/badge/Docker-Enabled-2496ED?style=plastic&logo=docker&logoColor=white)]()
  7. [![MCP](https://img.shields.io/badge/MCP-Enabled-412991?style=plastic&logo=openai&logoColor=black)]()
  8. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/BlackSnufkin/LitterBox)
  9. [![GitHub Stars](https://img.shields.io/github/stars/BlackSnufkin/LitterBox)](https://github.com/BlackSnufkin/LitterBox/stargazers)
  10. 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.
  11. 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.
  12. > While designed primarily for red teams, LitterBox is equally useful for blue teams running the same tools in their malware-analysis workflows.
  13. ## Documentation
  14. Operator and developer documentation lives in the **[LitterBox Wiki](../../wiki)**.
  15. | Topic | Wiki page |
  16. |---|---|
  17. | How everything fits together | [Application Architecture](../../wiki/Application-Architecture) |
  18. | Run static + every reachable EDR in parallel | [All in One Pipeline](../../wiki/All-in-One-Pipeline) |
  19. | Dispatch payloads to a real EDR VM | [EDR Integration](../../wiki/EDR-Integration) → [Elastic Defend](../../wiki/Elastic-Defend-Setup) / [Fibratus](../../wiki/Fibratus-Setup) |
  20. | Whiskers agent (install, endpoints, build) | [Whiskers Agent](../../wiki/Whiskers-Agent) |
  21. | Every HTTP endpoint | [HTTP API Reference](../../wiki/HTTP-API-Reference) |
  22. | CLI / Python lib / MCP for LLMs | [GrumpyCats CLI](../../wiki/GrumpyCats-CLI) · [GrumpyCats Library](../../wiki/GrumpyCats-Library) · [LitterBoxMCP](../../wiki/LitterBoxMCP) |
  23. | What feeds the Detection Score | [Detection Score Explained](../../wiki/Detection-Score-Explained) |
  24. | Configure scanners / paths / timeouts | [Configuration Reference](../../wiki/Configuration-Reference) |
  25. | Add custom YARA rules / scanners | [YARA Rules Management](../../wiki/YARA-Rules-Management) · [New Scanner](../../wiki/New-Scanner) |
  26. ## Installation
  27. ### Windows
  28. ```bash
  29. git clone https://github.com/BlackSnufkin/LitterBox.git
  30. cd LitterBox
  31. python -m venv venv
  32. .\venv\Scripts\Activate.ps1
  33. pip install -r requirements.txt
  34. python litterbox.py # add --debug for verbose logging
  35. ```
  36. Open `http://127.0.0.1:1337`. Requires Python 3.11+ and an admin shell.
  37. ### Linux (Docker)
  38. ```bash
  39. git clone https://github.com/BlackSnufkin/LitterBox.git
  40. cd LitterBox/Docker
  41. chmod +x setup.sh
  42. ./setup.sh
  43. ```
  44. The setup script provisions a Windows 10 container with KVM and runs LitterBox inside. Initial build takes ~1 hour.
  45. - **Install monitor**: `http://localhost:8006`
  46. - **RDP**: `localhost:3389` (creds in the docker compose file)
  47. - **LitterBox UI**: `http://127.0.0.1:1337` once setup completes
  48. ### EDR setup (optional)
  49. 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](../../wiki/Whiskers-Agent) → [Elastic Defend Setup](../../wiki/Elastic-Defend-Setup) or [Fibratus Setup](../../wiki/Fibratus-Setup).
  50. ## Scanners
  51. Bundled binaries under `Scanners/`. Versions and last-update dates tracked here so operators can tell at a glance whether a scanner is current.
  52. | Scanner | Version | Last updated | Source |
  53. |---|---|---|---|
  54. | [PE-Sieve](https://github.com/hasherezade/pe-sieve) | 0.4.1.2 (`f1dc39d`) | 2026-05-02 | hasherezade/pe-sieve |
  55. | [Hollows-Hunter](https://github.com/hasherezade/hollows_hunter) | 0.4.1.2 (`e271f7e`) | 2026-04-18 | hasherezade/hollows_hunter |
  56. | [Moneta](https://github.com/forrest-orr/moneta) | `5b65395` | 2024-03-16 | forrest-orr/moneta |
  57. | [Patriot](https://github.com/joe-desimone/patriot) | — | 2024-12-29 | joe-desimone/patriot |
  58. | [Hunt-Sleeping-Beacons](https://github.com/thefLink/Hunt-Sleeping-Beacons) | `84dd3a9` | 2026-01-25 | thefLink/Hunt-Sleeping-Beacons |
  59. | [RedEdr](https://github.com/dobin/RedEdr) | `3bd6b97` (EXE-only build) | 2026-05-03 | dobin/RedEdr |
  60. | [YARA](https://github.com/VirusTotal/yara/releases) (engine `yara64.exe`) | — | 2024-12-29 | VirusTotal/yara |
  61. | Elastic YARA rules (`Scanners/Yara/rules/elastic-yara/`) | `d131ea8` | 2026-04-30 | elastic/protections-artifacts |
  62. | YARA-Forge Extended (`Scanners/Yara/rules/YARAForge/`) | 0.9.1 (release `20260503`) | 2026-05-03 | YARAHQ/yara-forge |
  63. | [CheckPlz](https://github.com/BlackSnufkin/CheckPlz) | — | 2024-12-29 | BlackSnufkin/CheckPlz |
  64. | [Stringnalyzer](https://github.com/BlackSnufkin/Rusty-Playground/tree/main/Stringnalyzer) | — | 2025-01-27 | BlackSnufkin/Rusty-Playground |
  65. | [HolyGrail](https://github.com/BlackSnufkin/HolyGrail) | — | 2025-08-18 | BlackSnufkin/HolyGrail |
  66. 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.
  67. When you refresh a scanner: replace the binary under its `Scanners/<Name>/` directory and update the row above (version + date).
  68. ## Contributing
  69. See [CONTRIBUTING.md](./CONTRIBUTING.md). Work in feature branches on personal forks.
  70. ## Support 🍺
  71. <a href="https://www.buymeacoffee.com/blacksnufkin"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" width="200" height="60"></a>
  72. [![Stars](https://starchart.cc/blacksnufkin/litterbox.svg?variant=adaptive)](https://starchart.cc/blacksnufkin/litterbox)
  73. ## Security Advisory
  74. - **Development use only.** This platform is designed for testing environments. Production deployment presents significant security risks.
  75. - **Isolation required.** Run only in isolated VMs or dedicated testing environments.
  76. - **No warranty.** Provided without guarantees; use at your own risk.
  77. - **Legal compliance.** Users are responsible for ensuring usage complies with applicable laws.
  78. ## Acknowledgments
  79. LitterBox stands on the work of these projects and their authors:
  80. | Tool | Author |
  81. |---|---|
  82. | [YARA rules](https://github.com/elastic/protections-artifacts/tree/main/yara) · [Elastic Defend](https://www.elastic.co/security/endpoint-security) | [Elastic Security](https://github.com/elastic) |
  83. | [PE-Sieve](https://github.com/hasherezade/pe-sieve) · [Hollows-Hunter](https://github.com/hasherezade/hollows_hunter) | [hasherezade](https://github.com/hasherezade) |
  84. | [Moneta](https://github.com/forrest-orr/moneta) | [Forrest Orr](https://github.com/forrest-orr) |
  85. | [Patriot](https://github.com/joe-desimone/patriot) | [joe-desimone](https://github.com/joe-desimone) |
  86. | [Hunt-Sleeping-Beacons](https://github.com/thefLink/Hunt-Sleeping-Beacons) | [thefLink](https://github.com/thefLink) |
  87. | [RedEdr](https://github.com/dobin/RedEdr) | [dobin](https://github.com/dobin) |
  88. | [Fibratus](https://github.com/rabbitstack/fibratus) | [rabbitstack](https://github.com/rabbitstack) |
  89. | [ThreatCheck](https://github.com/rasta-mouse/ThreatCheck) (basis for CheckPlz) | [rasta-mouse](https://github.com/rasta-mouse) |
  90. | [MalAPI](https://malapi.io/) reference DB | [mr.d0x](https://github.com/mrd0x) |
  91. ## Interface
  92. ![LitterBox Demo](Screenshots/lb-demo.gif)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.