feat(metrics): v1.88 Metrics Phase 2 — journal evidence + enrichments + docs (#429)

* feat(metrics): v1.88 Metrics Phase 2 — journal evidence + enrichments

M88-1: Total processed packets (sum of all counters, labeled clearly)
M88-2: Journal integration for LoginMon evidence
  - Bounded: 15m window, 500 lines, 3s timeout
  - Distinguishes exec failure (Unknown) from empty result (quiet)
  - LoginMon promoted from expected_limitation to evidence-backed
M88-6: Anchor flow counters (7 anchors, labeled as pipeline stages)

Evidence schema bumped to 1.88.0.
External plane added (JournalEvidenceResult).

Correlation updates:
- LoginMon: bans + validator agrees = match
- LoginMon: bans + validator idle = warning (shared counter)
- LoginMon: events only (no bans) = warning (partial evidence)
- LoginMon: no journal = unknown
- All defaults → unknown (conservative)

Renderer improvements:
- Total counted packets with explicit semantics note
- Anchor flow labeled "(pipeline stage transitions, not enforcement)"
- Journal evidence section (LoginMon bans/events in 15m window)
- Additional notes for LoginMon shared attribution and anchor meaning

Golden fixture updated. All metadata bumped to v1.88.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: M88-9 evidence contract + M88-10 build status page

M88-9: docs/EVIDENCE_CONTRACT.md
- Evidence states (present/absent/unknown)
- Counter/set/chain/journal semantics
- Correlation rules and allowed values
- nft command compatibility reference
- Schema version 1.88.0

M88-10: docs/BUILD_STATUS.md
- 26 CI workflows in transparency table
- Contract gates (G1-1, G2-3, G8-1/2/3/4, B86-1, M84-2)
- Runtime test inventory
- Known issues
- Health policy
- How to verify section

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(metrics): M88-3/4 — feed + GeoIP data freshness in evidence

M88-3: Feed data freshness check
  - Scans /var/lib/nftban/feeds/ for newest file
  - Fresh if any file < 7 days old
  - Shows age in human renderer

M88-4: GeoIP DB freshness check
  - Checks /var/lib/nftban/geoip/dbip-country-lite.mmdb mtime
  - Fresh if < 45 days old
  - Shows age in human renderer

DataFreshnessResult added to EvidenceSnapshot.
Human renderer shows "Data Pipeline Freshness" section.
BUILD_STATUS.md updated per review (version, date, M87/M88 gates).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: itcmsgr

docs/BUILD_STATUS.md

@@ -0,0 +1,122 @@
+# NFTBan — Integrity & Build Status
+
+> **Policy:** Main branch is always green. Failed CI blocks merge.
+> No exceptions, no manual overrides for truth-critical checks.
+
+**Current version:** v1.88.0
+**Last audit:** 2026-04-16
+
+---
+
+## Build & Test
+
+| Workflow | What it verifies | Frequency | Status |
+|----------|-----------------|-----------|--------|
+| [Go Build & Test](https://github.com/itcmsgr/nftban/actions/workflows/ci-go.yml) | Go compilation, unit tests (race detector), module completeness (G8-1/G8-2/G8-3), schema version lock | Every PR + push | [![Go](https://github.com/itcmsgr/nftban/actions/workflows/ci-go.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/ci-go.yml) |
+| [Bash Validation](https://github.com/itcmsgr/nftban/actions/workflows/ci-bash.yml) | Shell syntax, strict mode compliance, header spec | Every PR + push | [![Bash](https://github.com/itcmsgr/nftban/actions/workflows/ci-bash.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/ci-bash.yml) |
+| [ShellCheck](https://github.com/itcmsgr/nftban/actions/workflows/shellcheck.yml) | Static analysis of all shell scripts | Every PR + push | [![ShellCheck](https://github.com/itcmsgr/nftban/actions/workflows/shellcheck.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/shellcheck.yml) |
+| [Build Packages](https://github.com/itcmsgr/nftban/actions/workflows/build-packages.yml) | RPM (el9/el10) + DEB (debian12/13, ubuntu22/24) build + install test | Every PR + push | [![Build](https://github.com/itcmsgr/nftban/actions/workflows/build-packages.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/build-packages.yml) |
+| [Docker](https://github.com/itcmsgr/nftban/actions/workflows/docker.yml) | Container image build | Every PR + push | [![Docker](https://github.com/itcmsgr/nftban/actions/workflows/docker.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/docker.yml) |
+| [Smoke Test](https://github.com/itcmsgr/nftban/actions/workflows/ci-smoke.yml) | CLI command execution, runtime anomaly checks | Every PR + push | [![Smoke](https://github.com/itcmsgr/nftban/actions/workflows/ci-smoke.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/ci-smoke.yml) |
+
+## Architecture & Contract Enforcement
+
+| Workflow | What it verifies | Frequency | Status |
+|----------|-----------------|-----------|--------|
+| [Architecture Policy](https://github.com/itcmsgr/nftban/actions/workflows/ci-architecture.yml) | FHS spec drift, schema codegen sync, vocabulary (G1-1), schema version (G2-3), module smoke (G8-4), legacy regression blockers (B86-1/M84-2 guards) | Every PR + push | [![Architecture](https://github.com/itcmsgr/nftban/actions/workflows/ci-architecture.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/ci-architecture.yml) |
+| [Documentation Validation](https://github.com/itcmsgr/nftban/actions/workflows/ci-docs.yml) | Markdown lint, link validation, doc completeness | Every PR + push | [![Docs](https://github.com/itcmsgr/nftban/actions/workflows/ci-docs.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/ci-docs.yml) |
+| [Project Health](https://github.com/itcmsgr/nftban/actions/workflows/project-health.yml) | Repository health metrics, stale issues, PR hygiene | Scheduled | [![Health](https://github.com/itcmsgr/nftban/actions/workflows/project-health.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/project-health.yml) |
+
+## Security (SAST + SCA + Secrets)
+
+| Workflow | What it verifies | Frequency | Status |
+|----------|-----------------|-----------|--------|
+| [CodeQL](https://github.com/itcmsgr/nftban/actions/workflows/codeql.yml) | Go semantic code analysis (GitHub Advanced Security) | Every PR + push | [![CodeQL](https://github.com/itcmsgr/nftban/actions/workflows/codeql.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/codeql.yml) |
+| [Semgrep](https://github.com/itcmsgr/nftban/actions/workflows/semgrep.yml) | Pattern-based security rules (Go + Shell) | Every PR + push | [![Semgrep](https://github.com/itcmsgr/nftban/actions/workflows/semgrep.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/semgrep.yml) |
+| [Secure Go](https://github.com/itcmsgr/nftban/actions/workflows/secure-go.yml) | gosec + staticcheck + govulncheck + Trivy | Every PR + push | [![SecureGo](https://github.com/itcmsgr/nftban/actions/workflows/secure-go.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/secure-go.yml) |
+| [OSV-Scanner](https://github.com/itcmsgr/nftban/actions/workflows/osv-scanner.yml) | Google OSV vulnerability database scan | Every PR + weekly | [![OSV](https://github.com/itcmsgr/nftban/actions/workflows/osv-scanner.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/osv-scanner.yml) |
+| [Gitleaks](https://github.com/itcmsgr/nftban/actions/workflows/gitleaks.yml) | Secret/credential detection in commits | Every PR + push | [![Gitleaks](https://github.com/itcmsgr/nftban/actions/workflows/gitleaks.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/gitleaks.yml) |
+| [Fuzz Tests](https://github.com/itcmsgr/nftban/actions/workflows/fuzz.yml) | Automated fuzz testing for parser robustness | Nightly | [![Fuzz](https://github.com/itcmsgr/nftban/actions/workflows/fuzz.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/fuzz.yml) |
+| [Dependency Review](https://github.com/itcmsgr/nftban/actions/workflows/dependency-review.yml) | PR-level dependency diff analysis | Every PR | [![DepReview](https://github.com/itcmsgr/nftban/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/dependency-review.yml) |
+| [Socket Supply Chain](https://github.com/itcmsgr/nftban/actions/workflows/socket-supplychain.yml) | Typosquatting and malicious package detection | Every PR | [![Socket](https://github.com/itcmsgr/nftban/actions/workflows/socket-supplychain.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/socket-supplychain.yml) |
+
+## Compliance & Supply Chain
+
+| Workflow | What it verifies | Frequency | Status |
+|----------|-----------------|-----------|--------|
+| [OSSRA Remediation](https://github.com/itcmsgr/nftban/actions/workflows/ossra-remediation.yml) | License compliance (go-licenses), SPDX headers, dependency freshness (libyear), URL validation (Lychee) | Every PR + push | [![OSSRA](https://github.com/itcmsgr/nftban/actions/workflows/ossra-remediation.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/ossra-remediation.yml) |
+| [OpenSSF Scorecard](https://github.com/itcmsgr/nftban/actions/workflows/scorecard.yml) | OpenSSF security health score | Scheduled | [![Scorecard](https://github.com/itcmsgr/nftban/actions/workflows/scorecard.yml/badge.svg)](https://github.com/itcmsgr/nftban/actions/workflows/scorecard.yml) |
+| [SLSA Go Releaser](https://github.com/itcmsgr/nftban/actions/workflows/slsa-go-releaser.yml) | SLSA Level 3 provenance attestation | On release | — |
+
+---
+
+## Contract Gates (v1.84+)
+
+These are **blocking** — a PR cannot merge if any gate fails.
+
+| Gate | What it enforces | Since | Workflow |
+|------|-----------------|-------|----------|
+| G1-1 | No banned terms in CLI output (vocabulary discipline) | v1.84 | ci-architecture.yml |
+| G2-3 | Schema version: Go source = CLI expectation | v1.84 | ci-architecture.yml |
+| G8-1 | Every CORE module in ModuleHealthMap + JSON | v1.85 | ci-go.yml (Go tests) |
+| G8-2 | Every config directory has a classification | v1.85 | ci-go.yml (Go tests) |
+| G8-3 | IPv6 parity: no IPv4-only evaluator checks | v1.85 | ci-go.yml (Go tests) |
+| G8-4 | Cross-surface module consistency (validator = health) | v1.85 | ci-architecture.yml |
+| B86-1 | No ModuleTruth reintroduction | v1.86 | ci-architecture.yml |
+| M84-2 | No legacy fallback reintroduction | v1.86 | ci-architecture.yml |
+| M87-1 | Evidence schema version lock (1.88.0) | v1.87 | ci-go.yml (Go tests) |
+| M87-2 | Correlation enum restricted to allowed values | v1.87 | ci-go.yml (Go tests) |
+| M87-3 | EvidenceSnapshot golden JSON must not drift | v1.87 | ci-go.yml (Go tests) |
+| M88-1 | Journal evidence must not affect truth authority | v1.88 | ci-go.yml (Go tests) |
+
+## Host Runtime Gate (pre-release)
+
+| Test | What it verifies | File |
+|------|-----------------|------|
+| CLI runtime smoke | 27 CLI commands execute without bash errors | test_cli_runtime.sh |
+
+This gate runs on deployed hosts before release tagging.
+It catches runtime failures (bad array subscript, unbound variable, syntax error)
+that cannot be detected in CI containers without nftables/systemd.
+
+## Runtime Tests (host-deployed)
+
+These require a deployed system and are not part of PR CI:
+
+| Test | What it verifies | File |
+|------|-----------------|------|
+| G2-1 | Truth consistency: validator status = health status | test_truth_consistency.sh |
+| G7-3 | Exit code contract: 0=PROTECTED, 1=DEGRADED, 2=DOWN | test_exit_code_consistency.sh |
+| G8-4 | Module list: validator JSON = health JSON | test_module_smoke.sh |
+
+---
+
+## Known Issues
+
+| Issue | Severity | Status |
+|-------|----------|--------|
+| gosec SARIF alerts on installer G104 | LOW | Dismissed as false positive (pre-existing, not PR-related) |
+
+---
+
+## Health Policy
+
+- **Main is always green.** Failed CI blocks merge.
+- **No manual overrides** for truth-critical checks (G1-1, G2-3, G8-*).
+- **Failing badge = working system.** It proves CI is active and catching issues.
+- **Every release is CI-gated.** No tag without green pipeline.
+- **Evidence over claims.** Click any badge to see full run logs.
+
+---
+
+## How to Verify
+
+```bash
+# On any deployed host:
+nftban-validate --json | jq '.status'          # Kernel truth
+nftban health --json | jq '.status'            # CLI agrees
+nftban metrics evidence                         # Evidence snapshot
+nftban metrics evidence-json | jq '.correlation' # Correlation diagnostic
+```
+
+All outputs are verifiable against the [contract rules](docs/CONTRACT_RULES.md).

docs/EVIDENCE_CONTRACT.md

@@ -0,0 +1,102 @@
+# NFTBan Evidence Contract (v1.88)
+
+Evidence is an observability layer over kernel enforcement.
+It answers: "what is actually happening?" — not "what should be happening?"
+
+## Position in Architecture
+
+| Layer | Role | Authority |
+|-------|------|-----------|
+| Kernel | Enforcement | Source of truth |
+| Validator | Interpretation | Health authority |
+| Evidence | Observability | No authority |
+
+**Evidence MUST NOT influence status, exit codes, or protection decisions.**
+
+## Evidence States
+
+Every evidence datum is one of:
+
+| State | Meaning |
+|-------|---------|
+| Present | Confirmed by kernel/journal data |
+| Absent | Confirmed not present |
+| Unknown | Collection failed — absence not known |
+
+Evidence MUST NOT guess or infer missing data.
+Failure MUST NOT be collapsed into absence.
+
+## Counter Semantics
+
+- Counter > 0 = positive enforcement evidence
+- Counter = 0 = neutral (not failure)
+- Counter unavailable (nil) = unknown
+- Shared counters are family-level only; no source attribution
+
+## Set Semantics
+
+- Exists=true, Count>=0 = collected successfully
+- Exists=false, Unknown=false = confirmed absent
+- Unknown=true = collection failure
+
+## Chain Semantics
+
+- Same three-state model as sets
+
+## Journal Evidence (v1.88)
+
+- Bounded: 15m window, 500 lines, 3s timeout
+- Exec failure = Unknown (not absence)
+- Empty output with exit 0 = no events (not failure)
+- LoginMon: bans and login_failed events from nftband journal
+
+## Correlation
+
+Correlation compares kernel evidence against validator interpretation.
+It is **diagnostic only**.
+
+### Allowed values
+
+| Value | Meaning |
+|-------|---------|
+| match | Evidence agrees with validator |
+| mismatch | Evidence contradicts validator |
+| warning | Suspicious but explainable |
+| expected_limitation | Not provable (portscan) |
+| unknown | Insufficient evidence |
+
+### Rules
+
+- Unknown evidence → unknown correlation (never guessed)
+- Correlation MUST NOT derive PROTECTED/DEGRADED/DOWN
+- Correlation MUST NOT influence exit codes
+- Default fallthrough → unknown (not match)
+
+## Evidence Schema
+
+Version: 1.88.0
+
+```json
+{
+  "schema_version": "1.88.0",
+  "collected_at": "...",
+  "truth_authority": "kernel",
+  "kernel": { "counters", "sets", "chains" },
+  "external": { "loginmon_active", "loginmon_bans", "loginmon_events" },
+  "validator": { "status", "modules", "findings" },
+  "correlation": { "module": "result" }
+}
+```
+
+## nft Command Compatibility
+
+Safe everywhere:
+- `nft -j list counters` (global)
+- `nft list table <family> <table>`
+- `nft list set <family> <table> <name>` (singular)
+- `nft -j list ruleset` (global)
+
+Broken on v1.0.x-v1.1.x:
+- `nft list counters <family> <table>`
+- `nft list chains <family> <table>`
+- `nft list sets <family> <table>`

internal/metrics/evidence_chains.go

@@ -1,10 +1,10 @@
 // =============================================================================
-// NFTBan v1.87 - Chain Presence Evidence Collector (M87-4)
+// NFTBan v1.88 - Chain Presence Evidence Collector (M87-4)
 // =============================================================================
 // SPDX-License-Identifier: MPL-2.0
 // meta:name="evidence_chains"
 // meta:type="package"
-// meta:version="1.87.0"
+// meta:version="1.88.0"
 // meta:owner="Antonios Voulvoulis <contact@nftban.com>"
 // meta:created_date="2026-04-15"
 // meta:description="Collects chain presence for Phase 1 evidence"

internal/metrics/evidence_chains_test.go

@@ -1,5 +1,5 @@
 // =============================================================================
-// NFTBan v1.87 - Chain Presence Evidence Tests (M87-4)
+// NFTBan v1.88 - Chain Presence Evidence Tests (M87-4)
 // =============================================================================
 // SPDX-License-Identifier: MPL-2.0
 // meta:name="evidence_chains_test"

internal/metrics/evidence_correlate.go

@@ -1,10 +1,10 @@
 // =============================================================================
-// NFTBan v1.87 - Correlation Engine (M87-6)
+// NFTBan v1.88 - Correlation Engine (M87-6)
 // =============================================================================
 // SPDX-License-Identifier: MPL-2.0
 // meta:name="evidence_correlate"
 // meta:type="package"
-// meta:version="1.87.0"
+// meta:version="1.88.0"
 // meta:owner="Antonios Voulvoulis <contact@nftban.com>"
 // meta:created_date="2026-04-15"
 // meta:description="Evidence correlation engine for metrics Phase 1"
@@ -50,6 +50,7 @@ func CorrelateEvidence(
 	counters map[string]CounterValue,
 	sets map[string]SetInfo,
 	validator *ValidatorSnapshot,
+	journal *JournalEvidenceResult,
 ) map[string]string {
 	results := make(map[string]string)
 
@@ -66,7 +67,7 @@ func CorrelateEvidence(
 	results["ddos"] = correlateDDoS(counters, validator)
 	results["botguard"] = correlateBotGuard(sets, validator)
 	results["portscan"] = correlatePortscan(validator)
-	results["loginmon"] = correlateLoginMon()
+	results["loginmon"] = correlateLoginMon(journal, validator)
 	results["blacklist_manual"] = correlateBlacklistManual(counters, sets, validator)
 
 	return results
@@ -151,11 +152,33 @@ func correlatePortscan(_ *ValidatorSnapshot) string {
 	return CorrelationExpectedLimitation
 }
 
-// correlateLoginMon: no Phase 1 journal evidence collection.
-func correlateLoginMon() string {
-	// LoginMon enforcement is through shared blacklist sets.
-	// Journal evidence not collected in Phase 1.
-	return CorrelationExpectedLimitation
+// correlateLoginMon: v1.88 uses journal evidence for LoginMon activity.
+// LoginMon uses shared blacklist sets, so counter evidence is not attributable.
+// Journal evidence (ban/login_failed events) is the primary signal.
+func correlateLoginMon(journal *JournalEvidenceResult, val *ValidatorSnapshot) string {
+	if journal == nil || journal.Unknown {
+		return CorrelationUnknown
+	}
+
+	valState := val.Modules["loginmon"]
+
+	switch {
+	case journal.LoginMonActive && journal.LoginMonBans > 0 && valState == "idle":
+		// Bans happening but validator says idle — shared counter limitation
+		return CorrelationWarning
+	case journal.LoginMonActive && journal.LoginMonBans > 0:
+		// Bans happening and validator is not idle — evidence agrees
+		return CorrelationMatch
+	case !journal.LoginMonActive && (valState == "idle" || valState == ""):
+		// No activity, validator idle — evidence agrees
+		return CorrelationMatch
+	case journal.LoginMonActive && journal.LoginMonBans == 0:
+		// Events detected but no bans — observing, not enforcing.
+		// Evidence is partial (events ≠ enforcement), attribution indirect.
+		return CorrelationWarning
+	default:
+		return CorrelationUnknown
+	}
 }
 
 // correlateBlacklistManual: elements + drops vs validator state.