Documentation
¶
Overview ¶
============================================================================= NFTBan v1.73 - Installer Authority Classification ============================================================================= SPDX-License-Identifier: MPL-2.0 meta:name="installer-authority-classify" meta:type="lib" meta:owner="Antonios Voulvoulis <contact@nftban.com>" meta:created_date="2026-04-04" meta:description="Authority decision tree: UPDATE/TAKEOVER/FRESH/ABORT/AMBIGUOUS" meta:inventory.files="internal/installer/authority/classify.go" meta:inventory.binaries="" meta:inventory.env_vars="NFTBAN_TAKEOVER, NFTBAN_PANEL_AUTO_TAKEOVER" meta:inventory.config_files="" meta:inventory.systemd_units="" meta:inventory.network="" meta:inventory.privileges="root" =============================================================================
============================================================================= NFTBan v1.73 - Installer Authority Types ============================================================================= SPDX-License-Identifier: MPL-2.0 meta:name="installer-authority-types" meta:type="lib" meta:owner="Antonios Voulvoulis <contact@nftban.com>" meta:created_date="2026-04-04" meta:description="Authority decision enum and types" meta:inventory.files="internal/installer/authority/types.go" meta:inventory.binaries="" meta:inventory.env_vars="NFTBAN_TAKEOVER" meta:inventory.config_files="" meta:inventory.systemd_units="" meta:inventory.network="" meta:inventory.privileges="none" =============================================================================
Index ¶
Constants ¶
const NftbanDaemonUnit = "nftband.service"
NftbanDaemonUnit is the systemd unit name of the nftban daemon. Kept as a package-level constant so the shared authoritative predicate and any future consumer cannot drift apart on unit-name spelling.
Variables ¶
This section is empty.
Functions ¶
func IsNftbanAuthoritative ¶ added in v1.100.4
IsNftbanAuthoritative is the CANONICAL predicate for "nftban currently owns the firewall on this host." It is the single source of truth; any other module that needs to answer the question (e.g. update.Preflight P-1) must call this function rather than re-implementing it.
The predicate requires THREE conditions to hold simultaneously:
- The ip nftban table exists in the kernel.
- The input chain inside that table exists.
- The nftband.service unit is currently active.
Previous versions of this package checked only (1) and (2). PR-22B tightened it: an orphan table left by a crashed prior install used to satisfy the predicate and classify the host as Update, causing phaseSwitch to skip the emergency SSH injection path. Requiring the active daemon forces that case into the Ambiguous branch instead.
All three probes are read-only.
Types ¶
type Decision ¶
type Decision string
Decision represents the authority classification for the install.
const ( // Update means NFTBan already owns the firewall (table + chain + daemon). // PR-22B tightened this predicate — a table or chain without an active // nftband.service is NOT Update; it is Ambiguous. Update Decision = "UPDATE" // Fresh means no conflicting firewalls — clean slate. Fresh Decision = "FRESH" // Takeover means conflicts exist but takeover is approved // (via env var, --takeover flag, or panel auto-approve when explicitly // enabled by --panel-auto-takeover). Takeover Decision = "TAKEOVER" // Abort means conflicts exist and takeover is not approved. Abort Decision = "ABORT" // Ambiguous means the host is in a half-installed / crashed state — // an ip nftban table exists in the kernel but the daemon is not // active, OR the detection is inconclusive. PR-22B added this state // on the install side to close the audit finding that orphan-table // hosts silently classified as Update and skipped the emergency SSH // injection path. phaseSwitch must treat Ambiguous with the same // pre-switch safety as Takeover — never silent-continue. Ambiguous Decision = "AMBIGUOUS" )
func Classify ¶
func Classify( exec executor.Executor, conflicts []detect.Conflict, panel detect.PanelType, forceApprove bool, panelAutoApprove bool, log *logging.Logger, ) Decision
Classify determines the installation authority based on the current system state.
Decision tree (PR-22B tightened):
UPDATE — nftban currently owns the firewall (IsNftbanAuthoritative returns true — table + chain + active daemon).
AMBIGUOUS — nftban artifacts are present but not all three conditions hold (orphan table, daemon without table, etc.). Never silent-continue — phaseSwitch must inject emergency SSH before any mutation.
FRESH — No conflicting firewalls detected AND no nftban artifacts observed.
TAKEOVER — Conflicts exist, AND takeover is explicitly approved via one of: a. NFTBAN_TAKEOVER=1 environment variable b. --takeover CLI flag (forceApprove=true) c. Panel auto-approve ONLY when panelAutoApprove=true (default is panelAutoApprove=false per PR-22B).
ABORT — Conflicts exist and no takeover approval was granted.
PR-22B change: panel auto-approve is no longer implicit. An operator who wants the old behaviour must pass --panel-auto-takeover (or set NFTBAN_PANEL_AUTO_TAKEOVER=1). This closes the audit finding that a panel-managed host disabled its own firewall silently on install.
Source Files