Metadata-Version: 2.4
Name: gloamfire
Version: 0.1.0
Summary: Purple-team attack replay platform for SOC and detection validation
Author: CommonHuman-Lab
License: AGPL-3.0-or-later
Keywords: security,purple-team,attack-simulation,detection-validation,mitre-attack,soc
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: docker>=7.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: types-pyyaml>=6.0; extra == "dev"
Dynamic: license-file

# Gloamfire

<p align="center"><em>Purple-team attack replay and detection validation platform</em></p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.12+-blue.svg" />
  <img src="https://img.shields.io/badge/Runtime-Docker-blue.svg" />
  <img src="https://img.shields.io/badge/License-AGPL--3.0-green.svg" />
  <img src="https://img.shields.io/badge/MITRE-ATT%26CK-orange.svg" />
</p>

---

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.

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

Or from source:

```bash
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)

```bash
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

```bash
gloamfire down
```

### Web Dashboard

```bash
gloamfire dashboard
```

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

See [docs/cli-commands.md](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](https://github.com/CommonHuman-Lab/gloamfire/wiki/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

```bash
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](https://github.com/CommonHuman-Lab/OctoRig) — Docker-based vulnerable lab launcher (Juice Shop, DVWA, Metasploitable, and more).

---

## License

Licensed under the [AGPLv3](LICENSE).
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.
