NFTBan Development Methodology: Evidence-Driven Security Engineering

[itcmsgr]

NFTBan started as a single-purpose Linux intrusion-prevention tool. It has grown into a broader Linux security and enforcement project built around nftables, a Go daemon (nftband), package-native deployment as DEB and RPM, multiple detection sources, operational health reporting, and release evidence bound to specific commits.

That growth changed what "done" has to mean.

A feature is not complete merely because the code exists or a test reports green. It is complete only when the real runtime path, package path and failure path are proven.

This post describes the development methodology that follows from that sentence, and the roadmap it produces.

---

Why the development process changed

As the test and CI surface got stronger, it began exposing assumptions that older checks did not measure. None of these were exotic. All of them were the ordinary result of validation catching up with a codebase:

• Checks that validated formatting but not semantic correctness — a file could be well-formed and still say the wrong thing.
• PR workflows that appeared green while publication-only paths had not executed — a path that only runs on a tag is not exercised by a pull request.
• Package behaviour that needs independent DEB and RPM validation — the two families have different scriptlet interpreters, different config-file semantics, and different transaction models. Proving one does not prove the other.
• Configured values that did not prove effective runtime state — a setting present in a config file is a declaration, not evidence that the running system adopted it.
• Health and status messages needing one authoritative source — when several code paths can each render a verdict, they can disagree.
• Release metadata that stayed syntactically valid while going stale — a well-formed field can still be wrong.

These findings did not mean validation was failing. They meant previously unmeasured behaviour was becoming visible.

---

The new methodology

1. One product source authority

Remote main is the authoritative product source. Branches start from clean, current main. Historical archives and statistics branches are explicitly classified as non-product authorities — they exist, they are useful, and they are not a source that product changes may be taken from.

2. Exact-commit validation

Evidence binds to an exact commit. If the commit changes, the evidence does not carry forward. A validation result is a statement about one specific tree, not about a branch name.

3. PR green does not mean every path executed

Distinct validation planes are tracked separately:

• PR checks
• Post-merge checks on main
• Package-native validation
• Publication-path validation
• Multi-host runtime validation

A path that did not run is recorded as untested, not as passed. A skipped job is an absence of evidence.

4. Human approval for protected release gates

Automation may prepare and dispatch work. Protected execution requires deliberate human approval. The record retains the exact commit, the requesting actor, the approving actor, the approval time, and the gate result.

5. Package-native proof

Real package transitions are validated independently for DEB and RPM:

• Upgrade behaviour
• Configuration preservation across the transition
• Installed version and commit identity
• Service health after the transaction
• Rollback readiness
• DEB/RPM outcome parity

6. Failure paths are first-class

Negative controls, injected failure cases, recovery verification, rollback evidence, and proof that a test exercised what it claims to exercise. The standing rule:

PASS does not equal injection proven.

A test that passes because the failure was never injected has measured nothing.

7. One authority for each operational fact

Each of the following has a single authority that produces it:

• Configured mode versus effective mode
• Package transaction outcome
• Firewall enforcement state
• Health verdicts
• Delivery outcomes
• Release metadata
• File ownership and classification

The goal is consolidation, not more status systems. Adding a second reporter for an existing fact is the problem being solved, not the solution.

---

The roadmap

Current phase

• Package lifecycle and post-install outcome truth
• Exact-commit release evidence
• Semantic release metadata
• CI completeness and publication-path validation

This is the work in v1.228.0, published on 27 July 2026. Its central change is at the package boundary: a package manager reports success when the payload unpacks, not when the installer succeeds. The DEB and RPM post-install paths now emit a machine-readable result that distinguishes a verified installation from a transaction that merely completed, and freshness is evaluated before the recorded state value — a stored result from an earlier transaction is not accepted as evidence about the current one.

The release notes also record what was not proven, in the same place as what was: a pre-transition boundary case that remains unverified, and an SELinux-enforcing validation gap on one packaging family. Recording the unproven alongside the proven is the point of the methodology described above.

Next authority phases

• Runtime mode admission, and configured-versus-effective truth
• Enforcement reachability and worker-liveness evidence
• Health and verdict correctness
• Residual lifecycle, recovery and negative-proof closure

Parallel maintenance work

• CLI and shell-completion consistency
• Operator-facing wording
• Release metadata safeguards
• CI diagnostics
• Bounded retry for external registry transport failures
• Clearer fuzz timeout and corpus diagnostics
• Documentation and legal identity consistency

Low-risk maintenance will not be mixed into changes that touch firewall semantics, update-state authority, package scriptlets, runtime mode resolution, or shared security decisions. Those changes are separated so that a small fix cannot ride along with a security-relevant one.

---

Why this may look slower

Authority work has a wide validation surface. A single change to how a fact is produced has to hold across:

• DEB and RPM
• IPv4 and IPv6
• Upgrade and fresh install
• Success and failure
• Configured and effective state
• Package, publication and runtime evidence

That is the cost of establishing an authority once. The return is reuse: the next feature that needs the same fact inherits the proof surface instead of rebuilding it. That is the intended payoff — less rework per change in the same area, and failure modes that are already characterised before the change lands.

---

What users should expect

• Fewer ambiguous status claims
• Stronger evidence for package upgrades
• More explicit failure reporting
• A clearer distinction between configured and effective state
• Health output with a single authority behind each verdict
• Improved auditability
• Deliberate release gates rather than calendar-driven publication

To be plain about the objective: it is not an empty open register. An active security project always carries maintenance, compatibility and hardening work, and a register that reaches zero usually means the register stopped being honest. The meaningful measure is different:

Can a known defect class still reach the main branch or a published release undetected?

---

Human responsibility remains central

AI-assisted tools are used in this project. They help with code review, investigation, documentation, and hypothesis generation.

They are not the release authority.

Security-impacting changes still require measured evidence, human review, exact-commit gates, package-native validation, and explicit release approval. A protected gate requires an explicit human approval, and that approval is recorded.

See AI_ASSISTED_DEVELOPMENT.md and GOVERNANCE.md for the current policy.

---

Thanks

Thank you to everyone running NFTBan, filing issues, and reporting behaviour that did not match the documentation. A report that contradicts the documentation is how an unmeasured path becomes a measured one.

• Repository: https://github.com/itcmsgr/nftban
• Website: https://nftban.com