From a40659e9164eb69b0e72bfddb85ae6aa159860ca Mon Sep 17 00:00:00 2001 From: "Mr.Rabbit" Date: Tue, 23 Sep 2025 20:48:42 +0900 Subject: [PATCH] docs(api): clarify /v1/mode side effects and presets table --- README.md | 6 ++++++ configs/profiles/fiber.yaml | 25 +++++++++++++++++++++++++ configs/profiles/lte.yaml | 25 +++++++++++++++++++++++++ configs/profiles/sat.yaml | 25 +++++++++++++++++++++++++ docs/API_REFERENCE.md | 12 ++++++++++++ docs/OPERATIONS.md | 16 +++++++++------- 6 files changed, 102 insertions(+), 7 deletions(-) create mode 100644 configs/profiles/fiber.yaml create mode 100644 configs/profiles/lte.yaml create mode 100644 configs/profiles/sat.yaml diff --git a/README.md b/README.md index d127cc1..f549799 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,12 @@ These principles converge in Azazel’s design: **defense is not about passive p ## What's new +- Sample configs under `configs/profiles/` showcase SAT, LTE, and fiber tuning + complete with thresholds and notify/storage defaults. +- The operations guide now carries a mode action table describing preset intent + for each defensive posture. +- `/v1/mode` documentation clarifies that invoking the endpoint applies presets + and records operator-triggered decisions in `decisions.log`. - Mode-aware presets backed by `azazel.yaml` apply delay/shape/block actions as the daemon transitions between portal, shield, and lockdown. - Vector remap normalization now emits a unified schema (ts/node/src/dst/proto diff --git a/configs/profiles/fiber.yaml b/configs/profiles/fiber.yaml new file mode 100644 index 0000000..642e759 --- /dev/null +++ b/configs/profiles/fiber.yaml @@ -0,0 +1,25 @@ +node: azazel-fiber-hub +interfaces: { lan: lan0, wan: wan0 } +profiles: + active: fiber + sat: { uplink_kbps: 2500, rtt_ms: 600 } + lte: { uplink_kbps: 18000, rtt_ms: 35 } + fiber: { uplink_kbps: 120000, rtt_ms: 5 } +qos: + medical: { dest_fqdns: ["clinic.example.org"], dest_cidrs: ["203.0.113.0/25"] } + ops: { ports: [22,443,3389] } + public: {} +soc: + suricata_ruleset: balanced + canary_services: ["ssh", "http", "smb"] +actions: + portal: { delay_ms: 50, shape_kbps: null, block: false } + shield: { delay_ms: 125, shape_kbps: 512, block: false } + lockdown: { delay_ms: 200, shape_kbps: 128, block: true } +thresholds: + t1_shield: 35 + t2_lockdown: 65 + unlock_wait_secs: { shield: 480, portal: 1200 } +notify: { level: warn } +storage: { log_dir: "/var/log/azazel", retain_days: 30 } +privacy: { pii_minimize: true, hash_fields: ["src.ip", "dst.ip", "username"] } diff --git a/configs/profiles/lte.yaml b/configs/profiles/lte.yaml new file mode 100644 index 0000000..74ca308 --- /dev/null +++ b/configs/profiles/lte.yaml @@ -0,0 +1,25 @@ +node: azazel-lte-field +interfaces: { lan: lan0, wan: wan0 } +profiles: + active: lte + sat: { uplink_kbps: 1800, rtt_ms: 650 } + lte: { uplink_kbps: 12000, rtt_ms: 45 } + fiber: { uplink_kbps: 80000, rtt_ms: 10 } +qos: + medical: { dest_fqdns: ["telemed.example.net"], dest_cidrs: ["198.18.0.0/15"] } + ops: { ports: [22,443,1194] } + public: {} +soc: + suricata_ruleset: max-performance + canary_services: ["ssh", "http", "rdp"] +actions: + portal: { delay_ms: 75, shape_kbps: null, block: false } + shield: { delay_ms: 150, shape_kbps: 256, block: false } + lockdown: { delay_ms: 250, shape_kbps: 96, block: true } +thresholds: + t1_shield: 40 + t2_lockdown: 70 + unlock_wait_secs: { shield: 600, portal: 1800 } +notify: { level: warn } +storage: { log_dir: "/var/log/azazel", retain_days: 14 } +privacy: { pii_minimize: true, hash_fields: ["src.ip", "dst.ip", "username"] } diff --git a/configs/profiles/sat.yaml b/configs/profiles/sat.yaml new file mode 100644 index 0000000..3c58487 --- /dev/null +++ b/configs/profiles/sat.yaml @@ -0,0 +1,25 @@ +node: azazel-sat-field +interfaces: { lan: lan0, wan: wan0 } +profiles: + active: sat + sat: { uplink_kbps: 2000, rtt_ms: 700 } + lte: { uplink_kbps: 6000, rtt_ms: 90 } + fiber: { uplink_kbps: 60000, rtt_ms: 12 } +qos: + medical: { dest_fqdns: ["emis.example.org"], dest_cidrs: ["203.0.113.0/24"] } + ops: { ports: [22,443,853] } + public: {} +soc: + suricata_ruleset: balanced + canary_services: ["ssh", "http", "pgsql"] +actions: + portal: { delay_ms: 100, shape_kbps: null, block: false } + shield: { delay_ms: 200, shape_kbps: 128, block: false } + lockdown: { delay_ms: 300, shape_kbps: 64, block: true } +thresholds: + t1_shield: 45 + t2_lockdown: 75 + unlock_wait_secs: { shield: 900, portal: 2400 } +notify: { level: warn } +storage: { log_dir: "/var/log/azazel", retain_days: 21 } +privacy: { pii_minimize: true, hash_fields: ["src.ip", "dst.ip", "username"] } diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index b8499b6..4b0eac7 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -50,6 +50,18 @@ loads YAML describing synthetic events. `main(argv)` powers the systemd service by feeding events into `AzazelDaemon`, which applies score-based decisions and writes `decisions.log` entries containing the chosen mode and action presets. +## HTTP endpoints + +### `POST /v1/mode` + +The controller exposes a minimal HTTP interface for supervised overrides. A +`POST` request to `/v1/mode` with a JSON body such as `{ "mode": "shield" }` +will transition the daemon to the requested state. The handler immediately +applies the corresponding preset from `azazel.yaml` (delay, shaping rate, and +block flag) and records the outcome to `decisions.log` alongside operator +metadata. Preset values are documented in the operations guide's +[mode action table](OPERATIONS.md#mode-presets). + ## Scripts - `scripts/suricata_generate.py` renders the Suricata YAML template. diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index 8289865..12d5bde 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -46,13 +46,15 @@ into `/etc/azazel`, installs systemd units, and enables the aggregate ### Mode presets The controller maintains three defensive modes. Each mode applies a preset of -delay, traffic shaping, and block behaviour sourced from `azazel.yaml`: - -| Mode | Delay (ms) | Shape (kbps) | Block | -|----------|-----------:|-------------:|:-----:| -| portal | 100 | – | No | -| shield | 200 | 128 | No | -| lockdown | 300 | 64 | Yes | +delay, traffic shaping, and block behaviour sourced from `azazel.yaml`. Refer to +the [API reference – `/v1/mode`](API_REFERENCE.md#post-v1mode) section for the +remote override that activates these presets during incident response. + +| Mode | Delay (ms) | Shape (kbps) | Block | Use case | +|----------|-----------:|-------------:|:-----:|----------| +| portal | 100 | – | No | Baseline latency padding to slow automated scanning while keeping users online. | +| shield | 200 | 128 | No | Elevated response once intrusion scoring passes T1; throttles attackers but preserves remote work. | +| lockdown | 300 | 64 | Yes | Emergency containment when T2 is exceeded; combines shaping with hard blocks until the unlock timer expires. | Transitions to stricter modes occur when the moving average of recent scores exceeds the configured thresholds. Unlock timers enforce a cooling-off period