Documentation
¶
Index ¶
- Constants
- func AddSessionWhitelist(exec executor.Executor, log *logging.Logger, entry SessionWhitelistEntry) error
- func CaptureSSHPeerIP() string
- func CleanupExpiredSessionWhitelist(exec executor.Executor, log *logging.Logger) (int, error)
- func RemoveSessionWhitelist(exec executor.Executor, log *logging.Logger, ip string) (int, error)
- func SeedManualWhitelist(exec executor.Executor, log *logging.Logger) error
- type SessionWhitelistEntry
Constants ¶
const DefaultSessionWhitelistTTL = 30 * time.Minute
DefaultSessionWhitelistTTL is the default time-to-live for auto-seeded operator SSH peer entries during `nftban update` / `firewall takeover`. Chosen at 30 minutes to comfortably cover a normal upgrade + validation window without leaving long-lived stale allow entries.
Variables ¶
This section is empty.
Functions ¶
func AddSessionWhitelist ¶ added in v1.120.0
func AddSessionWhitelist(exec executor.Executor, log *logging.Logger, entry SessionWhitelistEntry) error
AddSessionWhitelist appends an entry to /etc/nftban/whitelist.d/00-session.conf. File is created with seed header on first add. Entries are deduplicated by IP (a new add for the same IP REFRESHES the EXPIRES_AT/REASON/ADDED_BY fields rather than creating a duplicate line).
Caller responsibility: validate `entry.IP` is a routable IP or CIDR. This function does NOT re-validate (mirrors SeedManualWhitelist's contract).
Atomic write semantics: the function reads the current file (if any), removes any prior entry for the same IP, appends the new entry, and writes the result via exec.WriteFileAtomic (which uses temp-file + rename to guarantee race-free updates).
func CaptureSSHPeerIP ¶ added in v1.120.0
func CaptureSSHPeerIP() string
CaptureSSHPeerIP returns the active SSH peer IP, preferring the explicit NFTBAN_OPERATOR_SESSION_IP env-mirror (set by `nftban update` wrapper in cli/lib/nftban/cli/cmd_update.sh) and falling back to the first whitespace-delimited field of $SSH_CLIENT. Returns empty string if both sources are absent or the resulting token is not a routable IP.
The explicit env-mirror takes precedence because the update wrapper captures SSH_CLIENT before any sudo / package-scriptlet hop that might scrub it. Direct invocations of nftban-installer (without the wrapper) still get SSH_CLIENT fallback if the SSH session env is intact.
SSH_CLIENT format set by sshd: "client_ip client_port server_port". In non-SSH contexts (cron, systemd timer, etc.) both sources are empty — callers must treat empty return as "no SSH session; skip seeding."
func CleanupExpiredSessionWhitelist ¶ added in v1.120.0
CleanupExpiredSessionWhitelist removes entries past EXPIRES_AT from 00-session.conf. Returns (removed_count, error). Idempotent: safe to call when the file is absent (returns 0, nil) or has no expired entries.
The whitelist loader already skips expired entries at runtime, so this function is OPTIONAL for correctness — it is provided as a file-hygiene helper so the on-disk file doesn't accumulate stale entries indefinitely.
func RemoveSessionWhitelist ¶ added in v1.120.0
RemoveSessionWhitelist deletes any entry for the given IP from 00-session.conf. Returns (removed_count, error). 0 removed is not an error.
func SeedManualWhitelist ¶
SeedManualWhitelist ensures /etc/nftban/whitelist.d/99-manual.conf exists and contains the minimum entries needed to prevent accidental SSH lockout on a fresh source install.
Contract:
- If the file exists and contains any non-comment / non-blank line, the function is a no-op: the operator's content is preserved.
- If the file does not exist OR contains only header/blank lines, the function writes a new file with the canonical header + detected system IPs (interface IPs + SSH-client IP from $SSH_CLIENT if set).
- File mode and ownership match the shipped template: root:nftban 0640 (the payload package will set this; this package only writes content — ownership enforcement is payload's job).
Non-fatal: errors detecting individual IPs are logged at Debug level and the seed proceeds with whatever was detected. If NO IPs are detected at all, the file is still created with the header only — the operator retains control and switchop.InjectEmergencySSH provides port-level protection independently.
Types ¶
type SessionWhitelistEntry ¶ added in v1.120.0
type SessionWhitelistEntry struct {
IP string // exact IP or CIDR (already validated by caller)
ExpiresAt time.Time // UTC, RFC3339-serialized in the file
Reason string // short human-readable purpose (e.g. "v120-update-session")
AddedBy string // source identifier (e.g. "nftban-update", "nftban-firewall-whitelist-session")
}
SessionWhitelistEntry captures a time-bounded whitelist entry.
func ReadSessionWhitelist ¶ added in v1.120.0
func ReadSessionWhitelist(exec executor.Executor, log *logging.Logger) ([]SessionWhitelistEntry, error)
ReadSessionWhitelist returns all non-expired entries from 00-session.conf. Used by the CLI list subcommand. Returns an empty slice (not an error) when the file is absent.
Source Files