Policy: Main branch is always green. Failed CI blocks merge. No manual overrides for truth-critical checks. Evidence over claims.
Current version: v1.89.0 Truth model: Kernel → Validator → CLI Enforcement: Design Principles
This is not a badge collection.
This page is a live, machine-verifiable audit surface showing how NFTBan enforces system integrity through automated CI/CD pipelines.
Authority model:
Kernel (nftables) is the only source of truth. All validation, metrics, and
CLI output derive from kernel state via the Go validator. The daemon /metrics
endpoint is the canonical runtime observability surface.
Evidence model: Protection state is derived from kernel-observable evidence (counters, sets, meters). Structural presence alone does not imply enforcement.
Every check listed here is:
- Automated — runs without human intervention on every PR and push
- Reproducible — identical inputs produce identical results
- Verifiable — badge links go directly to workflow run logs
No check relies on manual verification.
If any check fails, the corresponding code cannot be merged or released.
This model allows operators and auditors to independently verify system integrity without trusting documentation or claims.
This page covers four verification axes:
- Build correctness and runtime safety
- Architecture and contract enforcement
- Security and supply chain integrity
- Compliance and provenance attestation
These workflows verify that NFTBan compiles, installs, and executes correctly across all supported platforms.
| Workflow | What it verifies | Frequency | Status |
|---|---|---|---|
| Go Build & Test | Compilation, unit tests, race detection, module completeness (G8-1/2/3), schema codegen lock | Every PR + push |  |
| Bash Validation | Shell correctness under set -Eeuo pipefail, execution safety |
Every PR + push |  |
| ShellCheck | Static shell analysis (SC2 rules) | Every PR + push |  |
| Build Packages | RPM + DEB build and install test across 7 platform targets | Every PR + push |  |
| Docker | Container build reproducibility | Every PR + push |  |
| Smoke Test | CLI runtime execution, JSON output validity, runtime anomaly detection | Every PR + push |  |
| Release | Signed release pipeline with provenance attestation | Release only |  |
These workflows enforce structural invariants that prevent regression of the kernel-first truth model.
Structural invariant: No rule may shadow another. Detection logic must remain reachable in the nftables chain. Shadowed logic (e.g., accept rules before detection jumps) is treated as DEGRADED state.
| Workflow | What it verifies | Frequency | Status |
|---|---|---|---|
| Architecture Policy | Schema integrity, vocabulary discipline (G1-1), module consistency (G8-4), codegen drift detection, nft direct-write protection | Every PR + push |  |
| Documentation | Markdown lint, link validity, doc completeness | Every PR + push |  |
| Project Health | Repository hygiene, stale issues, PR quality | Scheduled |  |
The Architecture Policy workflow is the primary anti-regression guard. It prevents changes that would break the kernel → validator → CLI truth pipeline or introduce vocabulary drift in operator-facing output.
These workflows implement defense-in-depth security scanning. No single tool covers all attack surfaces — the combination provides layered coverage.
| Workflow | What it verifies | Frequency | Status |
|---|---|---|---|
| CodeQL | Semantic SAST for Go (data flow, taint tracking) | Every PR + push |  |
| Semgrep | Pattern-based security rules (Go + Shell) | Every PR + push |  |
| Secure Go | gosec, govulncheck, staticcheck, Trivy container scan | Every PR + push |  |
| OSV-Scanner | Dependency CVE detection via Google OSV database | Every PR + weekly |  |
| Gitleaks | Secret and credential leakage detection | Every PR + push |  |
| Fuzz Tests | Parser robustness via automated fuzzing | Nightly |  |
| Dependency Review | Dependency diff risk analysis on PRs | Every PR |  |
| Socket Supply Chain | Typosquatting, malicious package, and behavioral detection | Every PR + push |  |
| Security Summary | Consolidated security posture dashboard | Scheduled |  |
These workflows provide verifiable evidence of license compliance and build provenance for enterprise and audit requirements.
| Workflow | What it verifies | Frequency | Status |
|---|---|---|---|
| OSSRA Remediation | License compliance (go-licenses), SPDX header validation, dependency freshness (libyear), URL integrity (Lychee) | Every PR + push |  |
| OpenSSF Scorecard | OpenSSF security posture scoring | Scheduled |  |
| SLSA Provenance | Cryptographic build attestation (SLSA Level 3) | Release only |  |
Every release includes:
- SLSA Level 3 provenance (non-forgeable build attestation)
- SBOM in SPDX-JSON format
- GPG-signed tags and artifacts
- All GitHub Actions pinned to commit SHAs
These are blocking gates enforced by CI workflows. A failure in any gate prevents merge to main. They enforce Design Principles directly in code — not by policy document, but by automated test.
| Gate | Design Principle | What it prevents |
|---|---|---|
| G1-1 | Vocabulary discipline | Banned terms in CLI output ("healthy", "OK", "working", etc.) |
| G2-3 | Schema consistency | CLI expected schema ≠ validator schema version |
| G8-1 | Module completeness | CORE module missing from evaluator or JSON output |
| G8-2 | Config classification | Module config directory without classification |
| G8-3 | IPv6 parity | IPv4 structural check without matching IPv6 check |
| G8-4 | Cross-surface truth | Validator module list ≠ CLI module list |
| INV-M-001 | Single kernel read | Evidence layer calls nft directly (must go through validator) |
| INV-M-003 | Metric ownership | Duplicate metric collection across components |
| INV-M-005 | No shell duplication | Shell exporter duplicates daemon kernel collection |
These gates are tested as part of ci-go.yml (Go unit tests) and
ci-architecture.yml (structural policy checks).
These values represent enforced automation, not documentation claims.
| Metric | Value |
|---|---|
| CI/CD workflows | 24 |
| Security scanning tools | 10 |
| Contract gates (blocking) | 9 |
| Package build targets | 7 (el9, el10, ubuntu22/24, debian12/13, + validation) |
| Install test environments | 5 (rocky9, alma9, centos-stream9/10, debian12) |
| Canonical daemon metrics | ~110 (post v1.90 name freeze) |
| Provenance level | SLSA Level 3 |
| SBOM format | SPDX-JSON |
Post-deploy verification commands that prove kernel enforcement on live hosts:
# 1. Kernel-derived health state (authoritative)
nftban-validate --json | jq '.status'
# Expected: "protected", "idle", or "degraded"
# 2. CLI truth (must match validator — INV-CONS-001)
nftban health --json | jq '.status'
# Must match validator output exactly
# 3. Evidence metrics (observable enforcement data)
nftban metrics evidence
nftban metrics evidence-json
# 4. Kernel structure verification
nft list tables
nft list chain ip nftban input | grep ANCHOR
# Must show 7 anchors: HYGIENE → TRUSTED → BAN → ESTABLISHED → DETECT → SERVICE → FINALSystem invariant: Kernel == Validator == CLI
If any of these commands disagree, the system state is invalid and must be treated as DEGRADED regardless of what individual surfaces report.
- Main branch is always green
- Failed CI blocks merge — no exceptions
- No manual overrides for truth-critical checks
- Every release is CI-gated before tag
- Evidence over claims — if it cannot be measured, it cannot be stated
- Unknown state → DEGRADED (never PROTECTED)
| Badge status | Meaning |
|---|---|
| Green | Workflow passed — invariant verified |
| Red | Workflow failed — code cannot merge or release until resolved |
| Skipped | Workflow not triggered for this event type (expected for some PR-only checks) |
| Neutral | Advisory result (e.g., gosec code annotations) — does not block |
| No badge | Workflow runs on a different trigger (release-only, scheduled) |
NFTBan does not claim protection. It proves protection through:
- Kernel evidence — nftables counters, sets, and chain structure
- Automated validation — Go validator reads kernel state (~1ms)
- Reproducible CI — 24 workflows, 10 security tools, 9 contract gates
- Cryptographic provenance — SLSA Level 3 attestation on every release
If any invariant breaks, the system reports DEGRADED, not PROTECTED.
This is not a design claim. It is enforced by CI and validator logic.
SECURITY.md — Vulnerability reporting and supported versions Design Principles — Engineering contract for all components Wiki — Full system specification