Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
122 lines (91 loc) · 4.5 KB

ARCHITECTURE.md

File metadata and controls

122 lines (91 loc) · 4.5 KB
Raw

array-firewall — target architecture

North star: array-firewall becomes the network exit for the entire LAN — protect, NAT, segment, observe — with full customization via dashboard + API.

Current state: lab mode (bench on secondary NIC). Target state: gateway mode inline between ISP and house LAN.

Topology

Today (lab / sidecar)

192.0.2.0/24 (existing LAN, legacy gateway still active)
        │
   eth0 ${ARRAY_FW_IP}  ← management + API + sentinel
        │
   array-firewall (CT ${ARRAY_FW_CTID})
        │
   eth1 198.51.100.0/24  ← test clients on lab NIC only

Target (gateway — full network exit)

        ISP / modem
            │
      WAN  eth1  ── default route, unsolicited inbound DROP
            │
     array-firewall
            │
      LAN  eth0  ── DHCP, DNS, whole-house NAT, device policies
            │
    switch / MoCA / Wi‑Fi AP
            │
   consoles, laptops, IoT, cameras, …

The legacy appliance can move to bridge/monitor, retire, or stay as a read-only telemetry source during migration.

Design principles

Principle Meaning
Default deny Forward and input drop; only established/related + explicit allows
Unsolicited blocked No inbound from WAN unless port-forward / related
NAT by default Masquerade all LAN → WAN
Device-centric Every client identified by MAC/IP; allow/deny + per-device policy
Observable Dashboard, API, sentinel, IDS hooks, session timeline
Gaming-aware Packet shield, QoS, peer blocklist, upload/download assist
Probe-aware Active countermeasures (honeypot + UDP confusion), session forensics, abuse automation

Gaming & probe stack

When Warzone Lobby Sentinel is co-hosted, the gaming path looks like:

Xbox ──► nft packet shield ──► Sentinel poll/score
              ▲                      │
              │                      ▼
         peer blocklist ◄── gaming_mitigate ◄── session risk payload
              │
              ├── probe_confusion (UDP DNAT → mutate-echo sink)
              ├── probe-sink (TCP honeypot personas + tarpit)
              ├── probe_ops (live stats, sync-on-block, evidence)
              ├── mesh_reputation → /24 subnet blocks
              └── session_audit → post-mortem + PROBE HEAVY verdict backfill

Probe countermeasure services

Service Port Role
array-firewall-probe-sink 39217/tcp Fake http/ssh/ftp/rdp banners; tarpit; auto-block
array-firewall-probe-udp-confusion 39218/udp Mutated echo / jitter / why?? responses for DNAT’d probes

Blocked probe peers are synced into nft confusion_peers and suspicious-peers.txt. Persona and echo mode profiles persist per attacker IP.

Session forensics

Path Content
/var/lib/array-firewall/session-reports/ Post-mortem JSON per session
/var/lib/array-firewall/session-evidence/ Exported zip bundles
/var/lib/array-firewall/probe-live-stats.json Live cheater counter + spike state
/var/lib/array-firewall/session-events.jsonl Killcam / shield / block event log

Key API surfaces

  • GET /api/v1/gaming/probe-ops/* — live stats, health, metrics, export
  • GET/POST /api/v1/gaming/session-audit/* — batch audit, playback, postmortem
  • POST /api/v1/gaming/mitigate — closed-loop actions from Sentinel

Policy knobs: gaming.mitigation.probe_confusion and gaming.mitigation.probe_ops in policies.json (see config/policies.json.example).

Migration phases

  1. Lab — secondary NIC bench; allow/deny, DHCP, API validation
  2. Sidecar — same LAN as legacy gateway; sentinel + gaming tools online
  3. Cutover — physical rewire; array-firewall becomes 192.0.2.1 (or your chosen gateway)
  4. Harden — zones, IDS, subnet blocklist, provider catalog

Services (target stack)

Service Port Role
array-firewall-api 8090 Dashboard + REST API
warzone-lobby-sentinel 8098 Lobby integrity, gaming automation
array-firewall-probe-sink 39217 TCP honeypot + persona tarpit
array-firewall-probe-udp-confusion 39218 UDP probe confusion sink
dnsmasq 53/67 DHCP + DNS (LAN)
nftables — Forward filter, NAT, gaming sets, confusion DNAT

See CUTOVER.md for the gateway switch procedure.