Skip to content

Configuration Reference

Jump to bottom Edit New page
BlackSnufkin edited this page May 5, 2026 · 3 revisions

Configuration Reference

LitterBox configuration lives in Config/config.yaml. EDR profiles live one-per-file under Config/edr_profiles/*.yml. Both are read on startup; reload requires a restart.

application — server settings

application:
  name: "LitterBox"
  host: "127.0.0.1"
  port: 1337
  debug: false
  version: "5.0.0"
Key Notes
host Bind address. 0.0.0.0 for non-loopback access. No auth — only expose on a private network
port Server port
debug Verbose logging
name / version Surface info, no functional effect

utils — file handling

utils:
  allowed_extensions:
    # Executables / loaders / drivers
    - exe
    - dll
    - bin
    - sys
    - lnk
    # Word (OOXML + legacy CFBF)
    - docx
    - docm        # macro-enabled
    - dotm        # template macro-enabled (T1221 target)
    - doc         # Word 97-2003 -- frequently weaponised with VBA macros
    - rtf         # OLE-embedded payloads
    # Excel (OOXML + legacy CFBF)
    - xlsx
    - xlsm        # macro-enabled
    - xltm        # template macro-enabled
    - xls         # Excel 97-2003 (VBA + Excel 4.0 / XLM macros)
    # HTML / HTM -- routed through the SmuggleShield-derived analyzer
    - html
    - htm
  max_file_size: 104857600        # 100 MB
  upload_folder: "Uploads"
  result_folder: "Results"
  malapi_path: "Utils\\malapi.json"
Key Notes
allowed_extensions Hard whitelist for /upload. The list groups into Executables / Word / Excel / HTML. Each group routes to a different per-file-type analyzer at upload time (PE → forensics.SecurityAnalyzer, Office → utils/office.py, HTML → utils/htmlsmuggle.py, LNK → utils/lnk.py). .sys is what gates the BYOVD / HolyGrail path. The upload page also gates which analysis tabs are visible per family — office + html only show Static.
max_file_size Bytes. Whiskers separately accepts up to 200 MB to leave envelope headroom
upload_folder Where uploaded samples go (<hash>_<original-name>)
result_folder Where per-sample result folders are written
malapi_path MalAPI reference DB used by the forensics module to flag sensitive imports

analysis.process — runtime knobs

analysis:
  process:
    init_wait_time: 5

init_wait_time is how long dynamic analysis waits after spawning the payload before attaching scanners. Long enough for the payload to do its initial DLL-resolve; short enough that fast payloads don't terminate before the wait elapses.

analysis.doppelganger — Blender + FuzzyHash DB

analysis:
  doppelganger:
    db:
      path: "Utils\\DoppelgangerDB"
      blender: "Blender"
      fuzzyhash: "FuzzyHash"
      fuzzy_extensions:
        - exe
        - dll
        - bin
Key Notes
path Root for both modules' data
blender Subdir for BlenderScan_*.json snapshots — see Blender Scanner
fuzzyhash Subdir for the compressed ssdeep DB — see FuzzyHash Scanner
fuzzy_extensions Default file types when building a fuzzy DB

analysis.holygrail — BYOVD scanner

analysis:
  holygrail:
    enabled: true
    tool_path: ".\\Scanners\\HolyGrail\\HolyGrail.exe"
    policies_path: ".\\Scanners\\HolyGrail\\Policies\\"
    command: "{tool_path} -d {file_path} -p {policies_path} -j -o {results_path}"
    results_path: ".\\Scanners\\HolyGrail\\Analysis\\"
    timeout: 120
Key Notes
enabled Disable to grey-out the BYOVD upload page button
policies_path Microsoft SiPolicy XML directory (Win10 + Win11 driver block lists)
results_path Tool-internal scratch — cleared by the /cleanup endpoint

See HolyGrail BYOVD Scanner for what the tool produces.

analysis.static — file-on-disk scanners

Each block follows the same shape: {enabled, tool_path, command, timeout, ...}.

analysis:
  static:
    yara:
      enabled: true
      tool_path: ".\\Scanners\\Yara\\yara64.exe"
      command: "{tool_path} -s -m {rules_path} {file_path}"
      rules_path: ".\\Scanners\\Yara\\LitterBox.yar"
      timeout: 120

    checkplz:
      enabled: true
      tool_path: ".\\Scanners\\CheckPlz\\CheckPlz.exe"
      command: "{tool_path} -m -r -f {file_path}"
      timeout: 120

    stringnalyzer:
      enabled: true
      tool_path: ".\\Scanners\\Stringnalyzer\\Stringnalyzer.exe"
      command: "{tool_path} --wide -f {file_path}"
      timeout: 120
Tool Purpose
yara Signature matching against Scanners/Yara/LitterBox.yar — see YARA Rules Management
checkplz Vendor AV-signature scanner; produces initial_threat + indicator list
stringnalyzer String extraction with categorization (URLs, suspicious commands, MalAPI hits)

Static analyzers run in parallel via a thread pool — startup time is bounded by the slowest scanner, not the sum.

analysis.dynamic — running-process scanners

analysis:
  dynamic:
    yara:
      enabled: true
      tool_path: ".\\Scanners\\Yara\\yara64.exe"
      command: "{tool_path} -s -m {rules_path} {pid}"
      rules_path: ".\\Scanners\\Yara\\LitterBox.yar"
      timeout: 120

    pe_sieve:
      enabled: true
      tool_path: ".\\Scanners\\PE-Sieve\\pe-sieve.exe"
      command: "{tool_path} /pid {pid} /threads /data 3 /iat 3 /obfusc 3 /shellc 3 /dir .\\Scanners\\PE-Sieve\\analysis"
      timeout: 120

    hollows_hunter:
      enabled: true
      tool_path: ".\\Scanners\\HollowsHunter\\hollows_hunter.exe"
      command: "{tool_path} /threads /data 3 /iat 3 /obfusc 3 /hooks /shellc 3 /json /jlvl 2 /quiet /ofilter 2"
      timeout: 600

    moneta:
      enabled: true
      tool_path: ".\\Scanners\\Moneta\\Moneta64.exe"
      command: "{tool_path} -m ioc -p {pid} --option from-base suppress-banner"
      timeout: 360

    patriot:
      enabled: true
      tool_path: ".\\Scanners\\Patriot\\Patriot.exe"
      command: "{tool_path} -p {pid}"
      timeout: 120

    hsb:
      enabled: true
      tool_path: ".\\Scanners\\HuntSleepingBeacons\\Hunt-Sleeping-Beacons.exe"
      command: "{tool_path} -p {pid}"
      timeout: 360

    rededr:
      enabled: true
      tool_path: ".\\Scanners\\RedEdr\\RedEdr.exe"
      command: "{tool_path} --etw --show --with-antimalwareengine --with-defendertrace --trace {process_name}"
      timeout: 120
Tool What it watches
yara YARA rules against process memory
pe_sieve In-memory PE integrity (hooks, hollowing, replaced sections)
hollows_hunter Process-hollowing variants — used by Blender Scanner for the system snapshot, not currently in the live-payload DYNAMIC_ANALYZERS registry
moneta Memory anomalies — Private RWX, Modified Code, Modified PE Header, Phantom Image, etc.
patriot Behavioral indicators (process injection, suspicious API patterns)
hsb Sleep-pattern detection for beaconing implants
rededr ETW telemetry — Kernel-Process / Kernel-File / Kernel-Network / Kernel-Audit-API / Microsoft-Antimalware-Engine. The flags above enable Defender's runtime verdict observation, which feeds the score

hsb runs serially after the parallel batch finishes — concurrent scanners (which open handles, walk VAD, briefly suspend threads) distort HSB's sleep-timing measurements. See app/analyzers/manager.py:56.

rededr's flag set is non-default — see Detection Score Explained for what --with-antimalwareengine and --with-defendertrace add.

EDR profiles — Config/edr_profiles/*.yml

One YAML file per profile. Real files are gitignored; example files (*.yml.example) are tracked. Common shape:

name: "elastic"                  # used in URLs (/analyze/edr/<name>/<target>)
display_name: "Elastic Defend"   # shown on the upload page button
kind: "elastic"                  # or "fibratus" — defaults to "elastic" for back-compat
agent_url: "http://192.168.1.100:8080"

wait_seconds_for_alerts: 90      # max poll budget — successful exec
av_block_wait_seconds: 60        # max poll budget — AV-block path
exec_timeout_seconds: 60         # hard cap on payload runtime

# drop_path: "C:\\Users\\Public\\sample.exe"   # optional override

kind: elastic-only fields:

elastic_url: "https://192.168.1.50:9200"
elastic_apikey: "<base64-encoded-API-key>"
elastic_verify_tls: false
elastic_index_pattern: ".ds-logs-endpoint.alerts-default-*,.internal.alerts-security.alerts-default-*"

kind: fibratus adds nothing — the Whiskers agent does the alert-source work via wevtutil. See:

Common scanner-config keys

Every analyzer in static.* and dynamic.* (and holygrail) shares this base shape:

Key Notes
enabled Toggle without removing the block. Disabled analyzers are still registered but skipped at run time
tool_path Path to the binary. Relative is fine — analyzers os.path.abspath() when needed
command str.format() template — see placeholder list below
timeout Seconds. Triggers status: timeout in the result envelope
rules_path (YARA) Path to the YARA rules file
results_path (HolyGrail) Output directory for tool-internal scratch

Command placeholders

The command string is str.format()-rendered with these keyword args:

Placeholder Provided by
{tool_path} Resolved from tool_path (with abspath if the analyzer sets abspath_targets = True)
{file_path} Static analyzer target — the uploaded sample's path
{pid} Dynamic analyzer target — the live PID
{process_name} RedEdr-specific — the spawned process basename
{rules_path} Forwarded from config when the analyzer declares extra_format_kwargs = ('rules_path',)
{results_path} HolyGrail's tool-internal scratch directory

Adding a new placeholder requires both a config field and the analyzer's extra_format_kwargs declaration — see New Scanner.

Logging

LitterBox uses a compact log formatter:

HH:MM:SS  LEVEL  module  message

Werkzeug access logs are renamed to http and reformatted to METHOD path → status. Set application.debug: true to see DEBUG-level messages.

The MCP server logs to stderr (stdio transport reserves stdout for JSON-RPC).

Restart vs reload

There is no live-reload of config. Edit a YAML, restart with py litterbox.py. EDR-profile loads happen at startup — adding a new profile YAML requires a restart before the upload page picks it up.

See also

Repo · Releases · CHANGELOG · Issues · GPLv3

📌 LitterBox · self-hosted payload analysis sandbox

Release

🚀 Getting Started

📊 Pipelines & Pages

🔬 Scanners · 4 modules

🛰️ EDR Integration
🔌 API & Clients
⚙️ Configuration & Dev

Clone this wiki locally