BotScanner
Deterministic Firewall Management for Linux Systems
BotScanner is a deterministic, backend‑agnostic firewall manager designed for engineers who demand reproducible behavior, audit‑transparent enforcement, and clean architectural boundaries.
It replaces ad‑hoc firewall scripts with a structured, policy‑driven system that produces the same output every time — no drift, no hidden state, no surprises.
Overview
BotScanner enforces firewall policy using a declarative configuration model and a deterministic execution pipeline.
It supports multiple backends (nftables, firewalld, iptables, ufw) and provides a unified abstraction layer so the same policy can be applied consistently across distributions.
The system is built around three principles:
- Determinism — same input → same output
- Reproducibility— full state can be rebuilt from configuration
- Audit Transparency— every action is logged, every change is explicit
Key Features
- Deterministic Enforcement
- Declarative configuration model
- Reproducible state transitions
- No hidden state or implicit behavior
- Drift detection between desired and actual firewall state
Backend‑Agnostic Architecture
- nftables (primary backend)
- firewalld
- iptables / ip6tables
- ufw
- Unified abstraction layer ensures consistent behavior across all backends
Zone‑Based Policy Model
- Public, Local, Trusted, and BotBlock zones
- Dual‑stack IPv4/IPv6 support
- Automatic set creation for active or required sets
- Timeout‑based botblock elements for automatic expiration
Enforcement Modes
- Strict — full enforcement, immediate correction of drift
- Audit‑Only — logs differences without applying changes
- Hybrid — selective enforcement with full audit visibility
- Unknown modes fall back to strict with an explicit log entry
Deterministic Logging
- All logs written to
Logs/<basename>.log - Append‑only, timestamped, audit‑transparent
- Backend actions, diffs, and enforcement decisions logged explicitly
Reproducible Helpers
- Deterministic ID generation
- Explicit transformation helpers
- Backend‑specific rule builders
- No magic, no implicit behavior
Architecture Overview
1. Configuration Layer
BotScanner reads a structured configuration file (YAML) defining zones, services, applications, backend selection, and enforcement mode.
Services are defined by name only; BotScanner maps them to ports internally for consistency.
2. Transformation Layer
Configuration is transformed into deterministic internal structures: sets, chains, rules, and backend‑specific objects.
This layer ensures reproducibility and removes ambiguity.
3. Backend Abstraction Layer
A unified interface that normalizes nftables, firewalld, iptables, and ufw.
Each backend implements the same deterministic contract.
4. Enforcement Pipeline
- Compute desired state
- Read actual state
- Compare
- Log diffs
- Apply changes (strict/hybrid) or skip (audit‑only)
5. Logging Layer
- State diffs
- Rule creation
- Set updates
- Backend commands
- Errors and fallbacks
Current Status
- Version: 0.3.0
- Edition: Community Edition (public)
- Professional Edition: In development (private)
- Backend Support: nftables, firewalld, iptables, ufw
- Platform: Linux
Roadmap
Near‑Term
- Complete deterministic renewal of all rule sets
- Finalize dual‑stack zone support
- Implement NAT flow visibility (Professional Edition)
- Add transactional rule updates
- Expand test suite for v3
Mid‑Term
- Full documentation site
- Web‑based audit viewer
- Policy simulation mode
- Multi‑host orchestration
Long‑Term
- Distributed enforcement
- Policy templating
- Integration with deterministic update frameworks
Why BotScanner Exists
Traditional firewall tools are inconsistent across distributions, prone to drift, difficult to audit, full of implicit behavior, and hard to reproduce.
BotScanner solves this by applying deterministic engineering principles:
- explicit state
- reproducible workflows
- audit‑transparent logs
- backend‑agnostic design
- clean architectural boundaries
Links
- GitHub Repository
- Documentation
- CLI Usage Examples
- Release Notes