gloamfire 0.1.0

Purple-team attack replay platform for SOC and detection validation

Gloamfire

Purple-team attack replay and detection validation platform

---

Gloamfire is a local-first, Docker-native adversary simulation and detection validation framework for SOC teams, purple teams, homelabs, and detection engineers.

It safely simulates attack techniques inside isolated Docker containers, validates that your detections fire, and maps everything to MITRE ATT&CK — fully offline with no cloud dependencies.

This is NOT malware. All simulations are safe, sandboxed, and deterministic.

---

Quick Start

Prerequisites: Python 3.12+, Docker Engine with Compose plugin, 4 GB RAM free.

# Kali / Debian / Ubuntu — venv required on externally-managed Python
python3 -m venv .venv && source .venv/bin/activate
pip install gloamfire

Or from source:

git clone https://github.com/CommonHuman-Lab/gloamfire.git
cd gloamfire
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Boot the full lab (victims + Wazuh SIEM + Suricata IDS)

gloamfire up

This single command:

• Starts three victim containers on an isolated network
• Builds and starts the Wazuh manager, indexer, and dashboard
• Downloads 50,000+ Emerging Threats rules into Suricata

Tear down

gloamfire down

Web Dashboard

gloamfire dashboard

Opens a browser to http://127.0.0.1:7100 with a live dashboard.

See docs/cli-commands.md for the full command reference — simulations, PCAP capture, ATT&CK Navigator export, and independent stack management.

---

Available Scenarios

20 scenarios covering ~55 MITRE ATT&CK techniques across 11 of 14 tactics.

All available scenarios

---

Architecture

• Plugin registry — Attack modules self-register at import time; adding a simulation is one Python file.
• YAML-driven scenarios — Scenarios are data, not code.
• File-based collection — No API or OpenSearch connection needed; collectors read bind-mounted log files directly.
• Isolated network — Victim containers run on gloamfire-attack-net (172.30.0.0/24).

---

Development

pip install -e ".[dev]"

pytest tests/unit/ tests/scenarios/   # no Docker required
pytest                                 # full suite (requires Docker)

ruff check gloamfire/ tests/
ruff format gloamfire/ tests/
mypy gloamfire/

#UI
cd ui
npm install
npm run dev       # dev server at :5173, proxies /api to :7100
npm run build     # outputs to gloamfire/api/static/ (served by FastAPI)

---

Related

OctoRig — Docker-based vulnerable lab launcher (Juice Shop, DVWA, Metasploitable, and more).

---

License

Licensed under the AGPLv3. You are free to use, modify, and distribute this software. If you run it as a service or distribute it, the source must remain open.

For commercial licensing, contact the author.