Skip to content

About

Emergency SOC/NOC gateway for Raspberry Pi — deterministic triage + local AI assist (Ollama)

Topics

Resources

Contributing

Security policy

Stars

5 stars

Watchers

1 watching

Forks

Latest commit

 

History

727 Commits

Folders and files

Repository files navigation

AZ-01 Azazel-Edge - Deterministic Edge SOC/NOC Gateway

Codename: SENTINEL

Azazel-Edge Banner CI Release License: MIT Docs Platform: Raspberry Pi Python Rust Flask Black Hat Arsenal

Azazel-Edge is the AZ-01 core platform of the Azazel system, a Raspberry Pi-oriented deterministic edge SOC/NOC gateway and Cyber Scapegoat Gateway for constrained, temporary, and high-risk networks.

It observes local network evidence (Suricata EVE), and the Rust defense core (azazel-edge-core) decides a bounded action from it and, only when enforcement is explicitly enabled, applies it. Operator-visible explanations and audit traces are recorded for each decision.

Optional local AI assist runs after the deterministic decision. It may summarize or explain the result, but it does not decide or enforce anything.

Azazel-Edge is not a production SIEM replacement, not an autonomous AI defender, and not a promise of complete attack prevention.

For safe checkout checks, see Development Verification. The device installer below changes system, network, storage, and optional model-runtime state.

Who this is for: security operators, field defenders, incident responders, training teams, and researchers working with constrained local networks.

2025 -> 2026 evolution line:

  • Deployable focus (rapid portable edge setup) -> Auditable focus (explainable deterministic decisions, rejected alternatives, and reviewable trace evidence)

Responsibility Split

Component Role today
Rust core (rust/azazel-edge-core, azazel-edge-core.service) The live decision and enforcement path. It reads Suricata EVE, selects the action (decide_defense()), and applies it only when enforcement is enabled (maybe_enforce()). It releases leases on expiry.
Python ActionArbiter (py/azazel_edge/arbiter/) A deterministic decision record for scenario replay, benchmarks and the SOC policy dry run. No running service applies its output.
AI agent (azazel-edge-ai-agent.service, py/azazel_edge_ai/) Receives each event after the core has decided. It records the decision, computes the tactical score and second-pass SOC evaluation, and writes advisory text. It cannot change the action.
Shared M.I.O. package (azazel_mio) If installed, the AI agent uses the pinned shared AssistantCore without a model for bounded post-decision advisory analysis. The current immutable source pin is commit a1807bf7abb08788b834ae038f7a8b46d09d0acc (package version 0.1.0.dev20261106+gitbb6dcfd), not a public MIO release. Edge retains this pin independently of the newer Nexus runtime candidate and the separate IR candidate. Its output cannot change Edge's action.
Edge-local M.I.O. modules (py/azazel_edge/mio/) Shadow, replay, and evaluation tools only; no systemd unit starts these local modules. They are distinct from the shared azazel_mio package. Their recommendations are never executable.
Control daemon and Web UI Display, operator controls and fixed control actions. The core never reads their state.

Automatic actions can observe, notify and apply temporary flow-scoped throttling. Redirection to a prepared decoy is allowed in semi-auto only when high-impact automation is enabled, and in full-auto. isolate is not an automatic action.

The live agent submits the shared no-model M.I.O. advisory by default when the package is importable. AZAZEL_MIO_MODEL_ENABLED=1 separately enables the local-model lane; it is disabled by default. The separate Knowledge Context lane also requires AZAZEL_MIO_KNOWLEDGE_CONTEXT_ENABLED=1 and is disabled by default. A package pin or producer-capture fixture does not establish end-to-end Knowledge producer interoperability.

Full authority matrix: M.I.O. Cognitive Plane.

Requirements

Requirement Detail
Hardware Raspberry Pi-oriented; tested/developed for constrained edge deployment
OS Raspberry Pi OS / Linux
Runtime Python 3.11 or later (CI tests 3.11; Raspberry Pi OS trixie, the device target, ships 3.13), Rust core components
Network Local edge segment with optional Suricata/OpenCanary integration
Optional Ollama (local AI model runtime), Mattermost, Wazuh, Vector, Aggregator

Shipped Defaults

The values below are the shipped systemd unit-file values declared with Environment= in systemd/azazel-edge-core.service. The unit also loads /etc/default/azazel-edge-security through EnvironmentFile=, and settings from that file override the unit's Environment= values on a device. The effective values on a given device can therefore differ from this table. Verify dry-run behavior with the Hardware First-Run Checklist.

The table is not exhaustive; the unit declares other variables as well.

Setting Shipped unit-file value Meaning
AZAZEL_DEFENSE_ENFORCE false No network change is applied
AZAZEL_DEFENSE_DRY_RUN true Planned actions are logged only
AZAZEL_DEFENSE_ENFORCE_LEVEL advisory Advisory policy level; enforcement is separately gated by AZAZEL_DEFENSE_ENFORCE and AZAZEL_DEFENSE_DRY_RUN
AZAZEL_DEFENSE_ACTION_TTL_SEC 300 Lifetime in seconds of a defense action lease
AZAZEL_DEFENSE_ALLOW_HIGH_IMPACT_AUTO false High-impact actions are not taken automatically

Enabling enforcement is a deliberate deployment change that must be verified in dry run first. Changing these settings is outside this README's scope; for the configuration reference, see Configuration Reference.

Development Verification

These checks need no root, network-namespace setup, or device. Installing the pinned dependencies requires GitHub network access. The commands match CI's test-python and test-rust jobs. The python -m compileall line is the Python compile check, which CI runs earlier in its lint-python job:

python3 -m venv .venv
. .venv/bin/activate
pip install -U pip wheel setuptools
pip install -r requirements/runtime.txt
pip install -r requirements/fabric.txt   # fetches a pinned Git tag from GitHub
pip install pytest
find bin -maxdepth 1 -type f -exec chmod +x {} +
python -m compileall -q py azazel_edge_web
node tests/touch_console_logic.test.js
node tests/sentinel_console_logic.test.js
PYTHONPATH=.:py pytest -q
cd rust/azazel-edge-core && cargo test
  • requirements/fabric.txt is an optional extra. Without it, Fabric integrations are guarded no-ops and the deterministic path is unchanged. CI installs it so the shadow/replay contract tests run on every change.
  • The node tests need Node 20 (the version CI uses). Without Node, the Python wrappers skip them.
  • The Suricata, service-objective, network-namespace and non-root CI jobs require root or a Suricata install. They are CI-only and are not part of the safe local checks above.
  • Results from these commands are runner or workstation results. They are not hardware evidence.

Quick Start: System-Changing Device Deployment (sudo)

This command changes the system. It is for a dedicated Raspberry Pi, run as root from a console or tmux, not for a workstation. Read the Physical Setup Guide first.

cd /home/azazel/Azazel-Edge
sudo ENABLE_INTERNAL_NETWORK=1 \
     ENABLE_APP_STACK=1 \
     ENABLE_AI_RUNTIME=1 \
     ENABLE_DEV_REMOTE_ACCESS=0 \
     WIFI_COUNTRY=JP \
     bash installer/internal/install_all.sh

What this run does to the device:

  • Interactive encrypted-secret setup. The app stack's security step creates an encrypted secrets volume by default (unless SKIP_LUKS=1). It prompts for a passphrase on the terminal. On first install, when the volume is absent, the installer stops if there is no terminal; SKIP_LUKS=1 must be set explicitly to skip the volume.
  • Network changes. It builds the internal LAN bridge (br0) and its access point. Building br0 drops an SSH session over eth0 or wlan0, so run it on the console or in tmux. On a Raspberry Pi 5, the uplink needs a USB Ethernet or USB Wi-Fi adapter. WIFI_COUNTRY is required unless a Wi-Fi country is already set. The WIFI_COUNTRY=JP in the command above is an example; change it to your deployment country's code. The AP passphrase is generated and saved root-only in /etc/azazel-edge/internal-ap.psk.
  • Packages. It installs system packages with apt-get (including Rust tooling) and builds the Rust core.
  • Model download. With ENABLE_AI_RUNTIME=1, it starts the Ollama container and pulls qwen3.5:2b and qwen3.5:0.8b over the network.
  • Selftest. At the end, it runs bin/azazel-edge-selftest and installs a periodic selftest timer. A critical selftest failure exits non-zero and reports that the device is not ready.

Verify on the device after installation:

sudo systemctl status azazel-edge-web azazel-edge-control-daemon azazel-edge-core --no-pager
bin/azazel-edge-selftest   # the installer runs it as root

Detailed install/deploy guidance:

Architecture Overview

flowchart LR
    E[Suricata EVE] --> C[Rust core: decide]
    C --> V{Enforcement enabled?}
    V -- no, shipped --> L[Log planned action]
    V -- yes, explicit --> N[Apply bounded action]
    C --> AI[AI agent: post-decision advice]
    AI --> O[Operator plane]
    C --> A[Audit / decision explanation]
    AI --> A
Loading

Replay, benchmark and dry-run paths use the Python ActionArbiter instead of the live core.

Full architecture:

What Azazel-Edge does

  • runs a local edge gateway and operations surface
  • ingests local telemetry such as Suricata EVE
  • evaluates NOC and SOC state through deterministic evaluators
  • selects bounded actions in the Rust core
  • records explanations, alternatives, and audit traces
  • supports replay-safe demos and operator workflows
  • optionally uses local AI assist for summaries and triage hints after the decision

Security Boundary Summary

Azazel-Edge claims:

  • local-first deterministic decision support
  • explicit bounded actions, with enforcement off by default
  • operator-visible explanation and audit traces
  • optional AI assist that remains secondary to deterministic control

Azazel-Edge does not claim:

  • complete attack prevention
  • full SIEM replacement
  • autonomous AI defense
  • legal or regulatory compliance by itself
  • safe deployment without operator understanding

Documentation Map

Primary entry points:

Concept Profiles

Azazel-Edge is maintained as a single core platform. Different operational profiles are documented as concept profiles, not forks.

Candidate CFP and planning material:

Arsenal Demonstrations

Only accepted and public Black Hat Arsenal appearances are recorded here.

BHUSA 2026 presenter note:

See Arsenal Demonstration History.

Repository Layout

Path Role
rust/azazel-edge-core/ Rust defense core: live decision and enforcement
py/azazel_edge/ Evidence Plane, evaluators, ActionArbiter (replay/dry run), explanations, audit, M.I.O. cognitive core (shadow)
py/azazel_edge_control/ Control daemon and action handlers
py/azazel_edge_ai/ AI agent integration and M.I.O. assist path (post-decision)
azazel_edge_web/ Flask backend, dashboard, ops-comm UI
runbooks/ Runbook registry
concept_profiles/ Concept-to-configuration mapping layer
demos/concepts/ Concept-oriented deterministic demo grouping
docs/ Architecture, concept, operations, and reference documentation

Azazel Series

Azazel-Edge (AZ-01, codename SENTINEL) is one product of the Azazel series ("Cyber Scapegoat Gateway"). The series map, naming specification, AZ designations, and doctrine live in the umbrella repository: 01rabbit/Azazel.

Edge-local integration note: Edge is the largest consumer of the shared Azazel-Fabric contracts (guarded, emit-alongside, zero behavior change). requirements/fabric.txt pins the stable Fabric v0.10.0 release. The shared M.I.O. source pin in requirements/runtime.txt is the immutable commit listed above, not a release. See docs/AZAZEL_COMMON_EDGE_ADAPTER_PLAN.md.

If azazel_mio is not importable, the live M.I.O. auxiliary reports a degraded or unavailable record. It never delays or changes the Edge action.

License

MIT. See LICENSE.

About

Emergency SOC/NOC gateway for Raspberry Pi — deterministic triage + local AI assist (Ollama)

Topics

Resources

Contributing

Security policy

Stars

5 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages