Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
65 lines (49 loc) · 2.8 KB

ARCHITECTURE.md

File metadata and controls

65 lines (49 loc) · 2.8 KB

Azazel Architecture

Azazel packages the SOC/NOC control plane into a self-contained repository. The solution is designed so a clean Raspberry Pi image can pull a tagged release and become operational without ad-hoc configuration.

Core services

Component Purpose
azazel_core/state_machine.py Governs transitions between posture states.
azazel_core/actions/ Models tc/nftables operations as idempotent plans.
azazel_core/ingest/ Parses Suricata EVE logs and OpenCanary events.
azazel_core/qos/ Maps profiles to QoS enforcement classes.
azctl/ Thin CLI/daemon interface used by systemd.
azctl/tui_zero.py + azctl/tui_zero_textual.py Unified Textual TUI (Azazel-Zero port).
configs/ Declarative configuration set including schema validation.
scripts/install_azazel.sh Provisioning script that stages the runtime and dependencies.
systemd/ Units and targets that compose the Azazel service stack.

State machine overview

The state machine promotes or demotes the defensive posture based on the score calculated from incoming alerts. Three stages are modelled:

  1. Idle – default, minimal restrictions.
  2. Shield – elevated monitoring, tc shaping applied.
  3. Lockdown – optional stage triggered by high scores where nftables rules restrict ingress to trusted ranges.

The scoring logic lives in azazel_core/scorer.py and is exercised by the unit tests under tests/unit.

Configuration

All runtime parameters are stored inside configs/azazel.yaml. A JSON Schema is published in configs/azazel.schema.json and enforced in CI. Vendor applications—Suricata, Vector, OpenCanary, nftables and tc—are provided with opinionated defaults that can be adapted per deployment.

TUI Architecture

Azazel-Edge uses a unified Textual UI ported from Azazel-Zero.

azctl/cli.py                  # `menu` subcommand entry
azctl/tui_zero.py             # Azazel-Edge adapters (snapshot/action mapping)
azctl/tui_zero_textual.py     # Textual application layout + key bindings

Execution flow:

  1. Operator runs python3 -m azctl.cli menu.
  2. cmd_menu() delegates to azctl.tui_zero.run_menu().
  3. Snapshot loader prefers runtime/ui_snapshot.json; fallback is azctl status --json.
  4. Textual actions (stage_open, reprobe, contain) are translated to mode events (portal, shield, lockdown).

Packaging goal

install_azazel.sh installs Azazel onto /opt/azazel, copies configuration and systemd units into place, and ensures Debian dependencies are present. The repository layout mirrors the staged filesystem, ensuring releases are reproducible. Tagging a commit triggers the release workflow that builds azazel-installer-<tag>.tar.gz containing the entire payload required for air-gapped installs.