dma a8454fafad firewall: learning mode, agent fail-closed, UI fixes, docs
* engine: learning mode (allow+record, commit to rule; actor→dest[:port])
  with D-Bus GetLearned/CommitLearned/DiscardLearned/SetLearnMode,
  fwctl learn on|off|list|commit|discard, and a Learning UI page
* agent: --fail-closed / --fail-open on session loss
* ui: reset manager subscriptions on rebuild (no handler leak); render
  rules from the node tree; prompt dialog shows process path + rule preview
* data: egress-ownership nft fragment; config.toml documents new knobs
* tests: live-matrix dbus-daemon --fork fix; PRIORITY.md backlog
2026-11-16 11:01:38 -05:00
2026-11-16 10:12:31 -05:00
2026-11-16 10:12:31 -05:00
2026-11-16 10:12:31 -05:00
2026-11-16 10:12:31 -05:00

Citadel Firewall

A userland application firewall for Linux, in Rust — the reimplementation of the legacy fw-daemon (Subgraph OS / SGFW), built for Citadel.

It intercepts new outgoing connections with NFQUEUE (implemented in pure Rust over netlink — no libnetfilter_queue C library), attributes them to the owning process (via /proc) or to the Citadel realm (container) they came from, runs them against a persistent, operator-based rule engine, and asks the user when no rule matches — through the GTK4 / libadwaita UI (English + French, extensible) or GNOME desktop notifications.

┌──────────┐   nftables hooks    ┌──────────────┐   pure netlink   ┌─────────────┐
│  kernel  │ ──────────────────▶ │  citadel-fwd │ ◀───────────────▶ │ NFQUEUE(0,1)│
│ (inet)   │  ct state new ⇒ q   │   (daemon)   │   verdicts         └─────────────┘
└──────────┘                     └──────┬───────┘
                                        │ D-Bus com.subgraph.firewall.Manager
                   ┌────────────────────┼─────────────────────┐
                   ▼                    ▼                     ▼
            GTK4 UI (EN/FR)       citadel-fwctl         GNOME notifications

Components

crate / dir role
crates/fwcore engine: rules, connections, DNS/SNI enrichment, NFQUEUE, nft, proc/realm attribution
crates/citadel-fwd the daemon: interception loop, rules store, D-Bus Manager service, --simulate
crates/citadel-fwctl CLI client for the D-Bus API
crates/citadel-fw-agent in-guest reporter for pH VM realms (stage 2, docs/PH-FIREWALL.md)
ui/ GTK4/libadwaita (GJS) UI, catalogs for English + French
data/ D-Bus policy, systemd unit, example config/rules, nft ruleset
docs/ARCHITECTURE.md full design notes (see below)
docs/PH-FIREWALL.md pH (KVM realm runtime) integration design + vsock agent protocol

Quick start

cargo build --release

# configure
install -Dm644 data/config.toml        /etc/citadel-fw/config.toml
install -Dm644 data/com.subgraph.firewall.conf /etc/dbus-1/system.d/
install -Dm644 data/citadel-firewalld.service /etc/systemd/system/
# (optional) seed rules
mkdir -p /var/lib/citadel-fw && install data/example-rules.json /var/lib/citadel-fw/rules.json

systemctl start citadel-firewalld
# UI
cd ui && meson setup build && meson compile -C build && ...

Run without root (development / CI):

cargo run -p citadel-fwd -- --simulate --config data/config.toml
citadel-fwctl --address unix:path=... status   # or point ctl at the system bus

Modes

  • Citadel hosts (realm_mode = true, default) — OUTPUT and FORWARD hooks; realm traffic is attributed via the realm↔IP map written by the realm runtime (/run/citadel/realms/network-clear), the same contract the legacy snitch-ext.go consumed. pH VM realms plug in via an extra map (realm_maps += /run/pH/instances.json) — see docs/PH-FIREWALL.md.
  • Vanilla Ubuntu / Debian / Fedora GNOME desktops (realm_mode = false) — host application firewall only; no citadel daemons required; prompts surface in the GTK4 UI or as org.freedesktop.Notifications alerts.

Controlling it

citadel-fwctl status                 # JSON state (incl. prompt_style, realm_defaults)
citadel-fwctl default deny           # global default action
citadel-fwctl prompt-style dialog    # notification (default) | dialog prompts
citadel-fwctl realm-default vm-research deny   # pin a realm/VM posture ("" clears)
citadel-fwctl resolve '<key json>' allow session [auto|process|host|hostport|realm]
citadel-fwctl watch                  # live connection stream

# pH VM realms (guest side; docs/PH-FIREWALL.md)
citadel-fw-agent --socket /run/citadel-fw/agent.sock --instance vm-work            # observe
citadel-fw-agent --instance vm-work --enforce --queue 0                            # guest-side verdicts

Feature map vs. the others

See docs/ARCHITECTURE.md → Design rationale: the rule / operator model, and where citadel-firewall goes beyond it (realm operand, pure-Rust nfqueue, JSON-over-D-Bus API, i18n UI, per-realm egress).

S
Description
No description provided
Readme
785 KiB
0 Stars 1 Watchers 0 Forks
Languages
Rust 85.1%
JavaScript 13.1%
Shell 1.5%
Meson 0.3%