Application Architecture
LitterBox is a Flask app with server-rendered Jinja templates and vanilla-JS ES6 modules on the frontend (no build step). Analysis is performed by a registry of pluggable analyzer classes; the EDR pipeline is a separate orchestrator that talks to a remote agent over HTTP.
graph LR
Upload[Operator uploads sample] --> Hash[Hash + metadata + entropy]
Hash --> Type{Type}
Type -->|.exe / .dll / .lnk / .docx / .xlsx / .bin| FileFlow[File analysis]
Type -->|.sys| DriverFlow[Driver analysis]
PID[Operator picks a PID] --> ProcessFlow[Process analysis]
FileFlow --> StaticGroup[Static analyzers]
FileFlow --> DynamicGroup[Dynamic analyzers]
FileFlow --> EdrGroup[EDR profiles]
DriverFlow --> Holygrail[HolyGrail BYOVD]
ProcessFlow --> DynamicGroup
StaticGroup --> Persist[(Saved JSON)]
DynamicGroup --> Persist
EdrGroup --> Persist
Holygrail --> Persist
Persist --> Risk[Risk scoring]
Risk --> Render[Results pages]
Each rounded box is a separate JSON file under Results/<hash>_<original-name>/:
| File | Source |
|---|---|
file_info.json |
written at upload — hashes, entropy, PE info, etc. |
static_analysis_results.json |
YARA + CheckPlz + Stringnalyzer findings |
dynamic_analysis_results.json |
YARA-mem + PE-Sieve + Moneta + Patriot + HSB + RedEdr |
byovd_results.json |
HolyGrail driver analysis |
edr_<profile>_results.json |
one per dispatched EDR profile (kind: elastic or kind: fibratus) |
_summary_cache.json |
mtime-validated dashboard payload (auto-generated) |
LitterBox host EDR-instrumented Windows VM
┌─────────────────────────────────┐ ┌─────────────────────────────┐
│ ElasticEdrAnalyzer / │ │ Whiskers.exe (Rust HTTP) │
│ FibratusEdrAnalyzer │ ──HTTP─►│ /api/info │
│ ┌─ Phase 1 (sync) ─┐ │ ◄──────┤ /api/lock/{acquire,...} │
│ │ get_info │ │ │ /api/execute/exec (XOR) │
│ │ lock_acquire │ │ │ /api/logs/execution │
│ │ exec (XOR'd) │ │ │ /api/alerts/fibratus/... │
│ │ wait_for_exit │ │ │ │
│ │ kill (idempotent)│ │ │ ↑ same VM ↑ │
│ │ get_logs │ │ │ │
│ │ lock_release │ │ │ ┌──────────────────────┐ │
│ └──────────────────┘ │ │ │ Elastic Defend agent │ │
│ ↓ returns Phase 1 dict │ │ │ OR │ │
│ ↓ status=polling_alerts │ │ │ Fibratus (ETW) │ │
│ ┌─ Phase 2 (daemon thread)──┐ │ │ └──────────────────────┘ │
│ │ poll alerts every 2s │ │ │ ↓ │
│ │ early-return on first hit │ │ │ Application event log │
│ │ settle window for bursts │ │ │ (Provider=Fibratus) │
│ │ save final findings JSON │ │ │ ↓ │
│ └───────────────────────────┘ │ └─── Whiskers wevtutil-queries│
│ ↓ │ │
│ Frontend polls saved JSON │ OR Elastic stack │
│ every 2-15s (adaptive) │ ↑ HTTP to │
└─────────────────────────────────┘ ElasticClient.fetch_alerts
Two-phase split keeps the agent lock window tight: Phase 1 holds the lock through exec → log fetch → release (~1-7s typical); Phase 2 runs unlocked so back-to-back dispatches don't queue. Time-bounded queries keep concurrent runs from polluting each other.
See EDR Integration for the full discussion.
litterbox.py # admin-check + Flask app.run(); entry point
config/config.yaml # all paths, tool configs, timeouts, enable flags
app/
├── __init__.py # create_app() — wires AnalysisManager + RouteHelpers
├── helpers.py # RouteHelpers — load_analysis_data, calculate risk
├── blueprints/ # one Flask blueprint per concern
│ ├── upload.py # GET / (dashboard) + GET /upload + POST /upload
│ ├── analysis.py # /validate, /analyze/*, /analyze/all, /analyze/edr,
│ │ # /holygrail, /whiskers
│ ├── results.py # /results/<type>/<target>, /results/edr/<profile>/<target>,
│ │ # /summary, /files
│ ├── doppelganger.py # /doppelganger
│ ├── management.py # /cleanup, /health, DELETE /file/<target>
│ └── api.py # /api/results/..., /api/edr/..., /api/system/scanners,
│ # /api/report/<target>
├── services/
│ ├── rendering.py # render_pid_results, render_file_results
│ ├── summary.py # process_pid_summary, process_file_summary
│ ├── summary_cache.py # mtime-validated per-sample cache
│ ├── tool_check.py # check_analysis_tool, check_holygrail_tool
│ ├── edr_health.py # TTL-cached agent reachability + background poller
│ └── error_handling.py # @error_handler decorator
├── utils/
│ ├── file_io.py # FileTypeDetector, save_uploaded_file, get_pe_info
│ ├── validators.py
│ ├── path_manager.py # find_file_by_hash (mtime-cached)
│ ├── risk_analyzer.py # RiskCalculator + calculate_risk
│ ├── forensics.py # SecurityAnalyzer (MalAPI), entropy
│ ├── json_helpers.py
│ └── reporting.py # generate_html_report
├── analyzers/
│ ├── base.py # BaseAnalyzer + BaseSubprocessAnalyzer
│ ├── manager.py # AnalysisManager — parallel static, parallel dynamic + serial hsb
│ ├── blender.py # system-process baseline comparison
│ ├── fuzzy.py # ssdeep-style fuzzy matching DB
│ ├── holygrail.py # BYOVD driver analysis
│ ├── static/ # yara, checkplz, stringnalyzer
│ ├── dynamic/ # yara, pe_sieve, moneta, patriot, hsb, hollows_hunter, rededr
│ └── edr/ # NOT a subprocess — talks to remote Whiskers + alert source
│ ├── profile.py # EdrProfile dataclass + load_profiles
│ ├── agent_client.py # AgentClient → Whiskers HTTP API
│ ├── elastic_client.py # ElasticClient → security alerts indices
│ ├── elastic_edr_analyzer.py # kind=elastic orchestrator
│ ├── fibratus_edr_analyzer.py # kind=fibratus orchestrator
│ └── registry.py # init() + dispatch_split() — kind dispatch
└── templates/
├── base.html, dashboard.html, upload.html, agents.html,
├── analyze_all.html, edr_info.html, results.html, file_info.html,
└── …
Vanilla JS, ES6 modules, no bundler. Loaded via <script type="module">.
app/static/js/
├── base.js # universal — sidebar, modals, status, cleanup
├── summary.js # /summary page
├── blender.js, fuzzy.js # /doppelganger tabs
├── results/
│ ├── core.js # AnalysisCore + DOMContentLoaded entry
│ ├── managers.js # TabManager, PayloadManager, ModalHandler
│ ├── tools.js # registry of per-tool modules
│ ├── renderers.js
│ ├── edr-saved.js # /results/edr/<profile>/<target> bootstrap
│ └── tools/ # one module per scanner — all consume `_shared.js` helpers
│ ├── _shared.js
│ ├── yara.js, checkplz.js, stringnalyzer.js
│ ├── pe_sieve.js, moneta.js, patriot.js, hsb.js, rededr.js
│ ├── edr.js # diff-aware re-render, lazy detail, adaptive poll
│ └── summary.js
├── dashboard/core.js # / dashboard
├── agents/core.js # /whiskers
├── analyze-all/core.js # /analyze/all/<target>
└── utils/ # escape, formatters, severity, fetch, modals, dom
All polling JS pauses on document.visibilityState === 'hidden' and resumes (with one immediate refresh) on visible.
Whiskers/ # separate Rust crate, single binary
├── Cargo.toml, Cargo.lock
├── README.md # install, CLI flags, endpoints, build-from-source
└── src/
├── main.rs # CLI: --port / --bind / --samples-dir / --install / --uninstall
├── api/
│ ├── info.rs # /api/info — hostname + telemetry_sources detection
│ ├── lock.rs # single-occupancy gate
│ ├── execute.rs # multipart exec, chunked-XOR write, rundll32 for DLLs
│ ├── logs.rs # execution + agent log buffers
│ └── alerts.rs # /api/alerts/fibratus/since — wevtutil queries Application log
├── state.rs # AppState + RunState
├── file_writer.rs # chunked-XOR (64 KiB working buffer)
└── agent_log.rs
Built with cargo build --release → target/release/Whiskers.exe (~1.6 MB, no runtime deps). See Whiskers Agent.
