* 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
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 legacysnitch-ext.goconsumed. 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 asorg.freedesktop.Notificationsalerts.
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).