litterbox/runbook.md

LitterBox + Fibratus Operational Runbook

GreySec Red Team — Pre-Engagement Payload Validation Owner: Hermes (COO) Last updated: 2026-05-05

---

Overview

LitterBox is a self-hosted payload analysis sandbox. Upload a binary, run it through 11 static and dynamic scanners, dispatch it to a Fibratus-instrumented Windows VM, and get back a Detection Score — a 0-100 measure of how loudly the payload triggers EDR sensors.

GreySec's use case: validate all C2 and post-exploitation payloads before an engagement. If Detection Score > 50, iterate on evasion before use. Document scores in the operation order.

---

Architecture

Operator (this host)
    |
    +-- GrumpyCats CLI --> LitterBox (port 1337)
    |                          |
    |                          +-- Static scanners (PE-sieve, YARA, Stringnalyzer, etc.)
    |                          |      runs on this host, no VM needed
    |                          |
    |                          +-- Whiskers HTTP --> EDR VM (port 8080)
    |                                        |
    |                                        +-- Spawns payload
    |                                        +-- Fibratus ETW sensor watches
    |                                        +-- Fibratus writes JSON alerts -->
    |                                                   Windows Application Event Log
    |                                                             |
    |                                               wevtutil <----+
    |                                        LitterBox reads + correlates
    |                                                  |
    +-- grumpycat.py CLI                            +-- Detection Score (0-100)
                                                   +-- Per-scanner results

Fibratus event log path (no network required inbound to VM):

• Whiskers polls wevtutil qe Application /c:10 ... Provider=Fibratus outbound
• No inbound ports on VM required, no Elasticsearch, no backend

---

Scanner Reference

Static Scanners (run on this host, no VM)

Scanner	What it detects	High Score Means
YARA	Matches against LitterBox.yar rule pack (custom + community rules)	Payload contains known malicious strings/immutable patterns
CheckPlz	PE header validation, packer detection, malformed PE indicators	Packed, obfuscated, or PE anomalies
Stringnalyzer	Embedded strings, IP addresses, URLs, API calls, PDB paths	Credential patterns, C2 URLs, suspicious API sequences
HolyGrail	Behavioral detection policies — YARA rules applied to runtime behavior	Policy violations during execution
Patriot	Binary hardening: DEP, ASLR, SEH, Code Guard flags	Unhardened binary — easier to exploit but also easier to detect

Dynamic Scanners (run inside Whiskers/EDR VM)

Scanner	What it detects	High Score Means
PE-Sieve	Process hollowing, injection, unpacking — compares memory to disk	Process manipulation detected
HollowsHunter	All processes in memory, injected code, hollowed sections	Code injection or process replacement
Moneta	Malware classification — categorizes IOCs, persistence, anti-VM	Clear malware classification
HuntSleepingBeacons	C2 beacon patterns — long-duration call home signatures	Active or dormant C2 channel
RedEdr	EDR evasion techniques — direct syscalls, unhooked functions, patched ETW	Payload is trying to evade EDR detection
Patriot	Same as static — hardening flags on the running process	Process is unhardened
HuntSleepingBeacons	Beacon cadence detection — sleep time, jitter, HTTP vs DNS	C2 protocol characteristics

---

Detection Score Interpretation

Score	Interpretation	Action
0-20	Near-silent — no or minimal EDR alerts	Field-ready for engagement
21-50	Moderate — some scanner alerts, minor EDR activity	Usable; iterate on highest-scoring scanner
51-80	Loud — multiple EDR sensors triggered, Fibratus active	Do not use without evasion iteration
81-100	Blatant — blocked, terminated, or immediate alerts	Abandon or rebuild; not engagement-ready

---

CLI Usage

GrumpyCats CLI (recommended interface)

# Activate venv
source ~/greysec/tools/LitterBox/venv/bin/activate

# Run a full analysis (static + dynamic/Fibratus)
python GrumpyCats/grumpycat.py run --profile fibratus --payload /path/to/payload.exe

# Check Whiskers/EDR VM status
python GrumpyCats/grumpycat.py edr-status --profile fibratus

# Query Fibratus alerts directly
python GrumpyCats/grumpycat.py fibratus-alerts --profile fibratus --since "2026-05-05T00:00:00"

# All scanners in parallel (no EDR VM needed)
python GrumpyCats/grumpycat.py run --profile all --payload /path/to/payload.exe

LitterBox Web UI

# Run as admin on the host (or via SSH tunnel)
sudo ~/greysec/tools/LitterBox/venv/bin/python litterbox.py
# Open http://127.0.0.1:1337

Fibratus Manual Query (on VM)

# Query Fibratus events from last 24h
wevtutil qe Application /c:10 /f:text /q:"*[System[Provider[@Name='Fibratus']]]"

# Clear Fibratus log (before a fresh test run)
wevtutil cl Application

Whiskers Health Check (from this host)

curl http://192.168.200.100:8080/api/info
# Expected: {"hostname":"litterbox-edr","os_version":"Windows 11 ...","agent_version":"0.1.0","telemetry_sources":["fibratus"]}

---

Evasion Iteration Workflow

1. Submit payload
   grumpycat.py run --profile fibratus --payload /tmp/payload.exe

2. Get Detection Score
   Example output: Score 68 — PE-Sieve triggered (3), RedEdr flagged (2), Fibratus alert (1)

3. Identify highest-scoring scanner
   PE-Sieve score 3 = process injection detected

4. Apply targeted evasion
   - PE-Sieve loud: use alternative process injection (APC queue vs CreateRemoteThread)
   - RedEdr loud: replace direct syscalls with Win32 API calls, unhook NTDLL
   - Fibratus loud: reduce syscalls, delay execution, use indirect syscalls

5. Re-submit and compare
   Record before/after scores

6. Repeat until score < 30
   Document final score and evasion techniques used

---

Pre-Engagement Checklist

Before any engagement:

• All C2 payloads tested through LitterBox with fibratus profile
• Detection Scores documented in operation order
• Scores > 50 flagged and evasion iteration completed
• Whiskers VM confirmed reachable: curl http://192.168.200.100:8080/api/info
• Fibratus service confirmed running on VM: Get-Service fibratus (via RDP/console)
• Whiskers.exe staged at ~/greysec/tools/LitterBox/staging/Whiskers.exe (for redeployment)
• Runbook read and understood by all operators

---

Deployment Summary

Component	Status	Location
LitterBox (orchestrator)	Deployed	~/greysec/tools/LitterBox
venv	Deployed	~/greysec/tools/LitterBox/venv
Whiskers.exe	Built (1.6MB)	~/greysec/tools/LitterBox/staging/Whiskers.exe
GrumpyCats MCP	Installed	.mcp.json (project-level)
fibratus.yml profile	Configured	Config/edr_profiles/fibratus.yml
Windows VM (EDR)	Provisioning	litterbox-edr, 192.168.200.100
Fibratus EDR	Pending install	Staged via PS1 on VM

---

Troubleshooting

Whiskers won't start on VM (port 8080 in use):

netstat -ano | findstr 8080
# Kill the process or change port: .\Whiskers.exe --port 8081

Fibratus service won't start:

# Check install path
Get-Service fibratus
# Check logs: C:\Program Files\Fibratus\logs\
# Reinstall if needed

Fibratus not writing to Application log:

# Verify alertsenders.eventlog.enabled: true and format: json in fibratus.yml
# Restart: net stop fibratus && net start fibratus

GrumpyCats can't reach LitterBox:

# Check config: ~/greysec/tools/LitterBox/Config/config.yaml
# host: 127.0.0.1, port: 1337
curl http://127.0.0.1:1337/health

Detection Score 0 on everything (no alerts from Fibratus):

• Fibratus not installed or not writing to event log
• Whiskers not reaching Fibratus (check /api/info telemetry_sources)
• Profile not set to kind: fibratus in fibratus.yml

Windows VM won't get IP (litterbox-net DHCP):

virsh net-dhcp-leases litterbox-net
virsh domifaddr litterbox-edr
# If no IP after OOBE, reboot VM: virsh reboot litterbox-edr

---

Smoke Test Sequence

Run after initial deployment to verify everything is connected:

# 1. Verify Whiskers is up on VM
curl http://192.168.200.100:8080/api/info
# Must return: telemetry_sources: ["fibratus"]

# 2. Verify Fibratus is writing to event log (on VM)
wevtutil qe Application /c:3 /f:text /q:"*[System[Provider[@Name='Fibratus']]]"
# Should show recent events after step 3

# 3. Trigger Fibratus rule on VM (e.g., spawn mshta)
# On VM: mshta "javascript:close()"

# 4. Run full LitterBox analysis
python ~/greysec/tools/LitterBox/GrumpyCats/grumpycat.py run \
  --profile fibratus \
  --payload /tmp/smoke_test.exe

# 5. Verify Detection Score returned
# Expected: > 0 for any real payload

---

Baseline Detection Score Table

Payload	Source	Expected Score	Actual Score	Date Tested
calc.exe	Windows built-in	Low (0-20)
whoami.exe	Windows built-in	Low (0-20)
ipconfig.exe	Windows built-in	Low (0-20)
mshta javascript	EDR trigger	Medium (21-50)
Empire launcher	C2 payload	High (51-100)

---

GreySec Integration Points

• Operation orders: Detection Score field required for every payload > 30
• C2 infrastructure: LitterBox validates staging and C2 beacon cadence
• IR prep: Baseline score established before engagement; deviation = anomaly during op
• Post-engagement: Re-test any payloads that behaved unexpectedly