LitterBox Files

LitterBox v5.0.0

A self-hosted payload-analysis sandbox for red teams. v5 is a major release: the Whiskers Rust agent, an EDR-integration pipeline (Elastic Defend + Fibratus), a system dashboard at /, an All-in-One pipeline that runs static + every reachable EDR profile in parallel, a unified /health route, full backend / frontend refactor, and a perf cluster across the stack.

Drop Whiskers.exe on your EDR VM, copy a profile YAML from Config/edr_profiles/*.yml.example, restart LitterBox — the new profile button appears on the upload page.

---

Downloads

File	Purpose
Whiskers.exe	Single-binary Rust agent — drop on the EDR-instrumented Windows VM.
Whiskers.exe.sha256	SHA256 of the binary — verify before deploying.
Source code (zip / tar.gz)	Auto-attached by GitHub. Full LitterBox source at this tag.

Verifying the binary

:::powershell
Get-FileHash Whiskers.exe -Algorithm SHA256
# compare against the value in Whiskers.exe.sha256

---

Quick start

Full setup lives in the README and the Wiki. Two EDR paths after the LitterBox install:

• Elastic Defend — copy Config/edr_profiles/elastic.yml.example → elastic.yml, fill in agent_url (Whiskers VM), elastic_url, and elastic_apikey. Optional Whiskers auto-start: Whiskers.exe --install.
• Fibratus (open-source ETW) — copy fibratus.yml.example → fibratus.yml with just agent_url. On the VM, edit %PROGRAMFILES%\Fibratus\Config\fibratus.yml and set alertsenders.eventlog: {enabled: true, format: json}, then restart the Fibratus service.

---

Highlights

EDR Integration

• Two profile kinds — kind: elastic (queries an Elastic stack for Defend alerts) and kind: fibratus (polls Whiskers's wevtutil event-log endpoint for Provider=Fibratus rule matches; no remote backend).
• Two-phase orchestration — Phase 1 holds the agent lock for exec + log fetch (~1–7 s). Phase 2 polls alerts unlocked, with early-return on first hit and an 8 s settle window for related-alert bursts.
• Per-payload alert correlation — scoped by host.name + filename match across file.name / process.name / file.path / process.executable / process.command_line / process.args.
• AV-block detection — Whiskers status:"virus" (Windows errno 225 / 995 / 1234) surfaces as summary.blocked_by_av.
• EDR-kill detection — non-zero exit without an agent-issued kill labeled "killed by EDR behavior protection" (alert-gated for DLL payloads to avoid false positives).
• Rich per-alert detail — Rule Reason, MITRE ATT&CK chips, Triggering API, Memory Region, Call Stack with module provenance, Process / Parent / EDR Response cards, raw _source.
• DLL execution — .dll payloads spawn via rundll32.exe <path>,<entry> [args...]; entry point is the first token of the executable-args field.
• XOR-on-the-wire — payload XOR'd in transit + during chunked-write to disk on the agent. Avoids cleartext sitting in HTTP buffers where Defender's network inspection might match a known-bad sample pre-spawn.

Whiskers Rust agent

Single-binary HTTP runner (~1.6 MB, no runtime deps).

• --install / --uninstall register an at-logon Windows scheduled task (no UAC, runs as invoking user)
• --samples-dir configurable drop path; default <exe-dir>\samples\ (auto-created)
• Chunked XOR write (64 KiB working buffer) — multi-MB payloads finish in ms
• /api/info self-reports hostname / OS / agent version; flags Fibratus presence in telemetry_sources
• /api/alerts/fibratus/since?from=...&until=... queries the Application event log for Provider=Fibratus records and returns raw JSON

Dashboard + saved-view

• System dashboard at / — scanner availability + EDR agent reachability, server-cached, polls every minute, pauses on hidden tab
• /whiskers — full EDR agent inventory page
• /analyze/all/<target> — All-in-One coordinator runs Static + every reachable EDR profile in parallel
• /results/edr/<profile>/<target> — saved-view route renders the run's findings using the same renderer as the live scan view

Detection signals

• High/critical EDR alerts contribute up to +50 to the Detection Score (AV blocks +35; multi-profile takes the max)
• RedEdr now captures Microsoft-Windows-Kernel-File / -Network / -Audit-API-Calls / Antimalware-Engine ETW events; new sub-tabs surface File Ops / Network / Audit API / Defender with a Process Tree panel
• Defender threat verdicts at runtime contribute +50 (verdicts only; scan activity stays descriptive)

GrumpyCats client

• Library reorganized into per-domain mixins (litterbox_client/{files,analysis,doppelganger,results,edr,reports,system}.py)
• 6 new EDR CLI subcommands (edr-run, edr-results, edr-profiles, edr-status, scanners, fibratus-alerts)
• 29 MCP tools + 4 OPSEC-review prompts (detection_summary, evasion_recommendations, attribution_check, deployment_readiness)
• install_mcp.py — one-shot installer that wires LitterBoxMCP into Claude Desktop, Claude Code (project + global), Cursor, Windsurf, or VS Code

Performance

• Parallel static analyzers (thread pool); HSB still runs serially after the parallel batch (timing-sensitive)
• mtime-validated _summary_cache.json per result dir
• Per-folder hash → dirname index (mtime-keyed) replaces full directory walks
• Lazy-fetch saved-view (saved EDR view dropped from ~330 KB inline JSON to ~13 KB)
• Adaptive frontend polling (2 s base, ×1.5 backoff to 15 s, snap-back on movement); pauses while tab is hidden

Security

• cryptography 44.0.2 → 47.0.0 (clears the SECT subgroup attack + DNS name-constraint advisories)
• Werkzeug 3.1.3 → 3.1.8 (clears the safe_join Windows device-name + compound-extension advisories)
• requests 2.32.3 → 2.33.1 (clears the .netrc credential leak + extract_zipped_paths temp-file advisories)
• Flask 3.1.0 → 3.1.3 (clears the session Vary: Cookie advisory)
• cffi 1.17.1 → 2.0.0 (transitive update for the cryptography bump)

---

Documentation

Operator and developer documentation lives in the LitterBox Wiki — Application Architecture, EDR Integration, per-EDR setup walkthroughs, full HTTP API reference, GrumpyCats CLI / Library / MCP, Detection Score Explained, Configuration Reference.