nftbackend

package
v1.230.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 14, 2026 License: MPL-2.0 Imports: 25 Imported by: 0

Documentation

Overview

Package nftbackend provides the core interface to nftables operations.

Architecture

This package is the single point of truth for nftables write operations in NFTBan. It enforces the single-writer architecture where only the nftband daemon should perform nftables modifications.

Operations

The backend supports:

  • Ban: Add IP to blacklist set
  • Unban: Remove IP from blacklist set
  • Whitelist: Add/remove from whitelist set
  • Sync: Bulk update of sets (feeds, geoban)
  • Flush: Clear all entries from a set

Safety Features

  • Validates IPs before operations
  • Prevents blocking of system IPs
  • Uses atomic nft transactions
  • Logs all operations for audit

Thread Safety

The Backend type uses mutex locking to ensure thread-safe operations. Multiple goroutines can safely call Ban/Unban concurrently.

Usage

The backend is instantiated by nftband daemon: 

backend := nftbackend.New()
err := backend.Ban("192.168.1.100", "manual", 0)
err := backend.Unban("192.168.1.100")

CLI tools should use the IPC client instead of this package directly.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNeverBanExempt = errors.New("never-ban exempt: refused add to enforcement set")

AddElement adds an element to any set This is the ONLY authorized add element implementation ErrNeverBanExempt is returned by AddElement when a single exempt IP is refused entry into an enforcement (drop) set. Callers can errors.Is() it to give a clear message.

Functions

func IsEnforcementSet added in v1.218.0 

func IsEnforcementSet(set string) bool

IsEnforcementSet reports whether set is a drop/block set subject to the never-ban invariant on element add. Never-ban is a target-set + element property, not a verb property — so the generic add path must consult this, not only the ban verb.

Types

type AddElementRequest 

type AddElementRequest struct {
	Table   string // e.g., "ip nftban", "ip6 nftban"
	Set     string // e.g., "whitelist_ipv4", "tcp_ports_in"
	Element string // e.g., "1.2.3.4", "8080"
	Timeout int    // seconds, 0 = permanent
}

AddElementRequest for generic set element operations

type ApplyRulesetRequest 

type ApplyRulesetRequest struct {
	FilePath string // path to .nft file
	Check    bool   // if true, validate only (nft -c)
}

ApplyRulesetRequest for applying complete rulesets

type Backend 

type Backend struct {
	// contains filtered or unexported fields
}

Backend provides serialized access to nftables write operations. All operations are thread-safe and atomic where possible. Uses netlink (google/nftables) for performance instead of CLI.

func New 

func New() *Backend

New creates a new nftables backend with netlink connection

func (*Backend) AddElement 

func (b *Backend) AddElement(ctx context.Context, req AddElementRequest) error

func (*Backend) ApplyRuleset 

func (b *Backend) ApplyRuleset(ctx context.Context, req ApplyRulesetRequest) error

ApplyRuleset applies a ruleset from a file This is the ONLY authorized apply ruleset implementation NOTE: This still uses CLI as netlink doesn't support loading .nft files

func (*Backend) Ban 

func (b *Backend) Ban(ctx context.Context, req BanRequest) (*BanResult, error)

Ban adds an IP to the appropriate blacklist set This is the ONLY authorized ban implementation Uses netlink for ~50x faster performance vs CLI

func (*Backend) CheckIP 

func (b *Backend) CheckIP(ctx context.Context, ip string) (bool, string, error)

CheckIP checks if an IP is in a specific set (read operation)

func (*Backend) DeleteElement 

func (b *Backend) DeleteElement(ctx context.Context, req DeleteElementRequest) error

DeleteElement removes an element from any set This is the ONLY authorized delete element implementation

func (*Backend) EnableExemptionGuard added in v1.210.0 

func (b *Backend) EnableExemptionGuard(configDir, scannerFile string)

EnableExemptionGuard wires the authoritative never-ban exemption guard. configDir is the nftban config dir (for whitelist.d); scannerFile is the path the resolved exempt list is published to for the unprivileged BotScan scanner ("" to skip publishing). Safe to call once at daemon init. Idempotent.

func (*Backend) FlushSet 

func (b *Backend) FlushSet(ctx context.Context, req FlushSetRequest) error

FlushSet flushes all elements from a set This is the ONLY authorized flush set implementation

func (*Backend) GetNFTManager 

func (b *Backend) GetNFTManager() *nftsync.NFTManager

GetNFTManager returns the underlying NFTManager for advanced operations This allows the daemon to use the same connection for sync operations

func (*Backend) GetStats 

func (b *Backend) GetStats() Stats

GetStats returns current statistics

func (*Backend) HealthCheck 

func (b *Backend) HealthCheck(ctx context.Context) error

HealthCheck verifies nftables is operational

func (*Backend) InvalidateCache 

func (b *Backend) InvalidateCache()

InvalidateCache invalidates cached tables and sets Call this after external nftables modifications

func (*Backend) IsExempt added in v1.218.0 

func (b *Backend) IsExempt(ip string) (bool, string)

IsExempt reports whether ip must never be banned (admin/management/whitelist/system/ live-SSH), delegating to the authoritative resolver. Nil-safe: no resolver → not exempt (fail-safe; never blocks a legitimate operation). Exposed so handlers can pre-check.

func (*Backend) Unban 

func (b *Backend) Unban(ctx context.Context, req UnbanRequest) (*UnbanResult, error)

Unban removes an IP from all blacklist sets (hash + interval) This is the ONLY authorized unban implementation v1.33.0: Tries hash set first (fast), then interval set

type BanRequest 

type BanRequest struct {
	IP      string
	Timeout int // seconds, 0 = permanent
	Reason  string
	// Source is PROVENANCE ONLY — it is recorded in the ban log, metrics and the
	// source index, and must never decide storage. Origin decides storage.
	Source string
	// Origin is the PRODUCER CONTEXT (v1.229.13 LANE-BST). The producer knows what
	// it is; a string table can only guess. Zero value is OriginUnspecified, which
	// falls back to label inference for legacy callers.
	Origin bansource.Origin
}

BanRequest contains parameters for banning an IP

type BanResult 

type BanResult struct {
	Success bool
	IP      string
	Set     string
	Message string
	Exempt  bool // true if the ban was REFUSED because the IP is never-ban exempt (F2 guard)
}

BanResult contains the result of a ban operation

type DeleteElementRequest 

type DeleteElementRequest struct {
	Table   string
	Set     string
	Element string
}

DeleteElementRequest for removing set elements

type FlushSetRequest 

type FlushSetRequest struct {
	Table string
	Set   string
}

FlushSetRequest for flushing sets

type Stats 

type Stats struct {
	Bans        int64
	Unbans      int64
	Syncs       int64
	Errors      int64
	ExemptSkips int64 // bans refused because the IP is never-ban exempt (F2 guard)
	// L3a: add_element requests refused because a single exempt IP targeted an
	// enforcement set (never-ban invariant enforced on the generic add path too).
	AddElementExemptSkips int64
	LastError             string
}

Stats tracks operation counts

type UnbanRequest 

type UnbanRequest struct {
	IP string
}

UnbanRequest contains parameters for unbanning an IP

type UnbanResult 

type UnbanResult struct {
	Success bool
	IP      string
	Set     string
	Message string
}

UnbanResult contains the result of an unban operation

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.