Documentation
¶
Overview ¶
SPDX-License-Identifier: MPL-2.0 Copyright (c) 2025 Antonios Voulvoulis <contact@nftban.com>
Package banlog provides centralized ban logging for NFTBan All ban actions (from any source) should log here for stats tracking
meta:name="banlog" meta:type="package" meta:version="1.41.0" meta:owner="Antonios Voulvoulis <contact@nftban.com>" meta:description="Central ban logging with audit trail support" meta:inventory.files="/var/log/nftban/bans.log" meta:inventory.binaries="" meta:inventory.env_vars="" meta:inventory.config_files="/etc/nftban/nftban.conf" meta:inventory.systemd_units="" meta:inventory.network="" meta:inventory.privileges="write:/var/log/nftban/"
Index ¶
- Constants
- func GenerateBanID() string
- func LogBan(ip, source, country string) error
- func LogBanFull(ip, source, country, reason, banID string, timeoutSec int, class string) error
- func LogBanWithID(ip, source, country, reason, banID string) error
- func LogBanWithReason(ip, source, country, reason string) error
- func LogUnban(ip, source, country string) error
- func LogUnbanWithID(ip, source, country, reason, banID string) error
- func LogUnbanWithReason(ip, source, country, reason string) error
Constants ¶
const ( SourceManual = "manual" SourceLogin = "login" SourcePortscan = "portscan" SourceDDoS = "ddos" SourceFeeds = "feeds" SourceSuricata = "suricata" )
Source constants for ban log entries
const ( StatusBanned = "BANNED" StatusUnbanned = "UNBANNED" )
Status constants
const ( ClassTemp = "temp" // auto-ban with kernel TTL (default 15m) ClassEscalated = "escalated" // auto-ban with extended TTL (repeat offender) ClassPermanent = "permanent" // auto-ban promoted to permanent (score≥100 or persistent) ClassManual = "manual" // operator-issued via nftban ban CLI )
BanClass identifies the type of ban for lifecycle tracking (BLC-2).
BanClass is recorded in the ban log (field 10) and in the future active_bans.json index (BLC-3). It is determined at ban-emission time by the scorer or the CLI and must never be empty for BANNED entries.
Variables ¶
This section is empty.
Functions ¶
func GenerateBanID ¶ added in v1.41.0
func GenerateBanID() string
GenerateBanID creates a unique 16-char hex ban correlation ID
func LogBan ¶
LogBan writes a ban entry to the central ban.log Parameters:
- ip: IP address being banned
- source: Ban source (manual, login, portscan, ddos, feeds, suricata)
- country: Country code (e.g., "US", "CN", "UNK" if unknown)
Format: DATE|TIME|SOURCE|IP|COUNTRY|BANNED|REASON (reason empty for this func) Use LogBanWithReason for audit trail with reason
func LogBanFull ¶ added in v1.80.0
LogBanFull writes a ban entry with all lifecycle fields (BLC-1). This is the preferred function for new callers. It records timeout and class so the ban log can answer lifecycle questions (when does this expire? what kind of ban is it?).
timeoutSec: original timeout in seconds at ban time. 0 = permanent. class: one of ClassTemp, ClassEscalated, ClassPermanent, ClassManual.
func LogBanWithID ¶ added in v1.41.0
LogBanWithID writes a ban entry with a reason and correlation ID (v1.41.0) The banID links this BAN entry to a future UNBAN entry for the same incident Format: DATE|TIME|SOURCE|IP|COUNTRY|BANNED|REASON|BAN_ID
func LogBanWithReason ¶
LogBanWithReason writes a ban entry with a reason for audit trail Format: DATE|TIME|SOURCE|IP|COUNTRY|BANNED|REASON
func LogUnban ¶
LogUnban writes an unban entry to the central ban.log Parameters:
- ip: IP address being unbanned
- source: Unban source (usually "manual")
- country: Country code
Format: DATE|TIME|SOURCE|IP|COUNTRY|UNBANNED
func LogUnbanWithID ¶ added in v1.41.0
LogUnbanWithID writes an unban entry with a correlation ID (v1.41.0) The banID should match the ID from the original ban entry Format: DATE|TIME|SOURCE|IP|COUNTRY|UNBANNED|REASON|BAN_ID
func LogUnbanWithReason ¶
LogUnbanWithReason writes an unban entry with a reason for audit trail Format: DATE|TIME|SOURCE|IP|COUNTRY|UNBANNED|REASON
Types ¶
This section is empty.
Source Files