itcmsgr
diff --git a/‎CHANGELOG.md‎
Lines changed: 114 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 114 additions & 0 deletions
diff --git a/‎VERSION‎
Lines changed: 1 addition & 1 deletion b/‎VERSION‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎cli/lib/nftban/cli/cmd_list.sh‎
Lines changed: 1 addition & 1 deletion b/‎cli/lib/nftban/cli/cmd_list.sh‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎cli/lib/nftban/cli/cmd_status.sh‎
Lines changed: 12 additions & 8 deletions b/‎cli/lib/nftban/cli/cmd_status.sh‎
Lines changed: 12 additions & 8 deletions
diff --git a/‎cli/lib/nftban/core/nftban_fhs_spec.sh‎
Lines changed: 2 additions & 2 deletions b/‎cli/lib/nftban/core/nftban_fhs_spec.sh‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎cli/lib/nftban/tests/test_banned_phrases.sh‎
Lines changed: 116 additions & 0 deletions b/‎cli/lib/nftban/tests/test_banned_phrases.sh‎
Lines changed: 116 additions & 0 deletions
diff --git a/‎internal/validator/cli.go‎
Lines changed: 17 additions & 4 deletions b/‎internal/validator/cli.go‎
Lines changed: 17 additions & 4 deletions
@@ -11,6 +11,120 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.81.0] - 2026-04-14
+
+**Metrics alignment and health semantics implementation.** Module-aware
+health output with frozen JSON schema, vocabulary-aligned states, and
+CLI/JSON truth discipline. Portscan classic detection bug fixed and
+verified live.
+
+### Added
+
+- **M81-4** Per-module health evaluation in Go validator. Each module
+  evaluated on 4 axes: config, structural, runtime, effective. Truth
+  tables from `HEALTH_METRIC_DERIVATION_v1.81.md` implemented in code.
+  Modules: BotGuard, DDoS, Portscan, LoginMon, Blacklist (unified:
+  manual + feeds + geoban). (PR #381)
+- **M81-6** Frozen JSON schema via mapper layer. `MapToHealthOutput()`
+  is the single projection point — internal state never serialized
+  directly. Schema version `1.81.0`. No nulls. Vocabulary-approved
+  values only. (PR #381)
+- DDoS effective axis reads real kernel named counters (`input_ct_ssh_drop`,
+  `input_ct_http_drop`, `input_ct_mail_drop`, `input_syn_rate_exceeded`,
+  `input_syn_prefix_drop`). Any > 0 = ENFORCING. (PR #381)
+- `StatusIdle` enum: overall status distinguishes PROTECTED (at least one
+  module active) from IDLE (all modules valid but no enforcement). Both
+  exit 0. (PR #381)
+- BotGuard dual-family structural evaluation per Rule 9 (per-family
+  aggregation). IPv6 checked only if ip6 nftban table exists. (PR #381)
+- Consistency block stub in JSON output (`kernel_vs_validator: "ok"`).
+  Full consistency checking is v1.82 scope. (PR #381)
+- `VAL-GEOBAN-001` finding emitted when geoip database missing/empty
+  and geoban is enabled. (PR #381)
+- `test_banned_phrases.sh`: M81-5 regression scanner detecting 7 banned
+  phrase patterns across CLI files. Informational for v1.81. (PR #381)
+
+### Fixed
+
+- **Portscan classic log-path collision** (CRITICAL). `PORTSCAN_CLASSIC_LOG_FILE`
+  was defined twice in `classic.conf` — line 32 (kernel input source) and
+  line 172 (module output log). The detector was grepping its own output
+  log and finding nothing. Renamed output variable to
+  `PORTSCAN_CLASSIC_MODULE_LOG`. Detection now verified live: lab2=160/4,
+  lab4=349/6, monitor=59/1 IPs tracked/blocked. Both background timer and
+  manual `nftban portscan check` fixed. (PR #377)
+- **CF-1** `service_state.nftband` now emits uppercase (`RUNNING`|`STOPPED`|
+  `ERROR`) matching JSON schema spec. Module runtime fields remain
+  lowercase. (PR #381)
+- **CF-2** Geoban DB missing emits `"stale"` (in allowed enum) instead of
+  `"degraded"` (not in enum). Emits `VAL-GEOBAN-001` finding. (PR #381)
+- **M81-5** CLI banned phrases: `"healthy"` replaced with `"protected"` in
+  health word mappings. `"threats_blocked_24h"` renamed to
+  `"enforcement_events_24h"` in status JSON. (PR #381)
+
+### Changed
+
+- `ToJSON()` now uses `MapToHealthOutput()` (frozen schema). Legacy
+  consumers use `ToJSONLegacy()` for backward compat. (PR #381)
+- `ExitCode()` returns 0 for both PROTECTED and IDLE. (PR #381)
+
+### Schema
+
+```json
+{
+  "schema_version": "1.81.0",
+  "status": "protected|idle|degraded|down",
+  "service_state": { "nftband": "RUNNING|STOPPED|ERROR" },
+  "modules": {
+    "botguard":  { "config", "structural", "runtime", "effective" },
+    "ddos":      { "config", "structural", "effective" },
+    "portscan":  { "config", "structural", "effective" },
+    "loginmon":  { "config", "structural", "runtime", "effective" },
+    "blacklist": { "manual", "feeds", "geoban" }
+  },
+  "consistency": { "kernel_vs_validator": "ok|mismatch" },
+  "findings": [...],
+  "chain_counts": {...},
+  "summary": {...}
+}
+```
+
+### Specs produced (M81-1 through M81-8)
+
+| Spec | Document |
+|---|---|
+| M81-1 Vocabulary | `NFTBAN_VOCABULARY_REFERENCE_v1.81.md` (v1.1) |
+| M81-2 Counter inventory | `METRICS_CATALOG_v1.81.md` |
+| M81-3 Module contracts | 5 module evidence contracts |
+| M81-4 Health derivation | `HEALTH_METRIC_DERIVATION_v1.81.md` |
+| M81-5 CLI output | `CLI_OUTPUT_SPEC_v1.81.md` |
+| M81-6 JSON schema | `JSON_SCHEMA_SPEC_v1.81.md` |
+| M81-7 Shadowing detection | `SHADOWING_DETECTION_SPEC_v1.81.md` |
+| M81-8 Glossary | `METRICS_GLOSSARY_AND_TROUBLESHOOTING_v1.81.md` |
+
+### Known limitations
+
+- **Set-element counting not implemented.** `countSetElements()` returns 0.
+  BotGuard ENFORCING/OBSERVING and blacklist PRIMED states are unreachable
+  from the validator. Fix target: v1.82 per-set queries.
+- **Portscan effective evidence is structural-only/idle.** No dedicated
+  kernel counter. Real enforcement evidence requires kernel log parsing.
+- **LoginMon effective evidence not yet integrated.** Journal query outside
+  validator's point-in-time snapshot model. Reports idle by default.
+- **Consistency axis is a stub** (`"ok"` always). Full cross-source
+  checking is v1.82 scope.
+- **Legacy shell CLI contains 24 banned-phrase instances** in health
+  subsystem files. Full CLI vocabulary enforcement is v1.82 scope.
+
+### PRs
+
+| PR | Title |
+|---|---|
+| #377 | Portscan classic log-path collision fix |
+| #381 | M81-4/5/6 health derivation + JSON schema + CLI cleanup + CF fixes |
+
+---
+
 ## [1.80.1] - 2026-04-13
 
 **Hotfix.** Fixes validator semantic issue from v1.80.0: module-scoped helper
 
@@ -1 +1 @@
-1.80.1
+1.81.0
@@ -392,7 +392,7 @@ WHITELIST COMMANDS COMPARISON:
   nftban whitelist list          # Shows IPs from config files (persistent)
   nftban whitelist-system show   # Shows only system auto-detected IPs
 
-TIP: Use 'nftban list whitelist' to see what's currently protecting your IPs.
+TIP: Use 'nftban list whitelist' to see what's currently in the whitelist.
      Use 'nftban whitelist list' to see what's saved in configuration.
 
 EOF
 
@@ -470,11 +470,12 @@ output_brief() {
         esac
     fi
 
+    # M81-5: "healthy" is a banned term. Use "protected" per vocabulary.
     case "$_hs" in
-        OK) health_word="healthy" ;;
+        OK) health_word="protected" ;;
         WARNING*) health_word="info" ;;
         ERROR*|CRITICAL*) health_word="errors" ;;
-        *) health_word="healthy" ;; # Default to healthy if still unknown
+        *) health_word="protected" ;; # Default to protected if still unknown
     esac
 
     # When PROTECTED, health issues are informational not errors
@@ -1636,14 +1637,16 @@ output_json() {
     # Return 0 or query feed config files for count
     echo "    \"feed_ips\": 0,"
 
-    # threats_blocked_24h: Bans in last 24 hours
-    local threats_24h=0
+    # M81-5/M81-6: renamed from threats_blocked_24h to enforcement_events_24h.
+    # "threats blocked" is a banned interpretation per vocabulary.
+    # This counter represents enforcement events (bans issued), not threats mitigated.
+    local enforcement_24h=0
     if command -v nftban_stats_count_bans >/dev/null 2>&1; then
         local since
         since=$(($(date +%s) - 86400))
-        threats_24h=$(nftban_stats_count_bans "$since" 2>/dev/null || echo 0)
+        enforcement_24h=$(nftban_stats_count_bans "$since" 2>/dev/null || echo 0)
     fi
-    echo "    \"threats_blocked_24h\": $threats_24h"
+    echo "    \"enforcement_events_24h\": $enforcement_24h"
     echo "  },"
 
     # Master control
@@ -1719,16 +1722,17 @@ output_json() {
         nftban_health_check_all 0 >/dev/null 2>&1 || health_exit=$?
     fi
 
+    # M81-5: "healthy" is a banned term. Use vocabulary-approved states.
     local health_status="unknown"
     case $health_exit in
-        0) health_status="healthy" ;;
+        0) health_status="protected" ;;
         1) health_status="warnings" ;;
         2) health_status="errors" ;;
     esac
 
     # v1.66.0: JSON health parity — when PROTECTED, health errors are informational
     if [[ "$json_base_state" == "PROTECTED" ]] && [[ "$health_status" == "errors" ]]; then
-        health_status="healthy"
+        health_status="protected"
     fi
 
     # Memory protection state for JSON
 
@@ -1,13 +1,13 @@
 #!/usr/bin/env bash
 # =============================================================================
-# NFTBan v1.80.1 - FHS Specification (GENERATED)
+# NFTBan v1.81.0 - FHS Specification (GENERATED)
 # =============================================================================
 # SPDX-License-Identifier: MPL-2.0
 #
 # meta:name="nftban_fhs_spec"
 # meta:type="core"
 # meta:header="FHS Specification"
-# meta:version="1.80.1"
+# meta:version="1.81.0"
 # meta:owner="Antonios Voulvoulis <contact@nftban.com>"
 # meta:homepage="https://nftban.com"
 #
 
@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MPL-2.0
+# =============================================================================
+# NFTBan v1.81 - M81-5 Banned Phrase Detection
+# =============================================================================
+# meta:name="test_banned_phrases"
+# meta:type="test"
+# meta:version="1.81.0"
+# meta:owner="Antonios Voulvoulis <contact@nftban.com>"
+# meta:description="Detects vocabulary-banned phrases in CLI output code per CLI_OUTPUT_SPEC_v1.81.md"
+# meta:inventory.files="cli/lib/nftban/cli/*.sh"
+# meta:inventory.binaries="bash,grep"
+# meta:inventory.env_vars=""
+# meta:inventory.config_files=""
+# meta:inventory.systemd_units=""
+# meta:inventory.network=""
+# meta:inventory.privileges="none"
+# =============================================================================
+# This test scans CLI shell files for phrases banned by M81-5.
+# It runs as a static analysis pass — no runtime needed.
+#
+# Banned phrases are defined in:
+#   CLI_OUTPUT_SPEC_v1.81.md Section 4
+#   NFTBAN_VOCABULARY_REFERENCE_v1.81.md Section 2
+#
+# Severity levels:
+#   ERROR:   phrase found in user-facing output (echo, printf to stdout)
+#   WARN:    phrase found in internal variable assignments
+#   SKIP:    phrase found in comments, test files, or non-output context
+#
+# This test does NOT block CI in v1.81 (many legacy instances exist).
+# It produces a report for incremental cleanup. Full enforcement is v1.82.
+# =============================================================================
+
+set -Eeuo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+CLI_DIR="$PROJECT_ROOT/cli/lib/nftban/cli"
+
+echo "=========================================================="
+echo "M81-5 Banned Phrase Scan"
+echo "  source: CLI_OUTPUT_SPEC_v1.81.md"
+echo "  target: cli/lib/nftban/cli/*.sh"
+echo "=========================================================="
+echo ""
+
+total_findings=0
+
+scan_phrase() {
+    local phrase="$1"
+    local description="$2"
+    local pattern="$3"
+
+    local hits
+    hits=$(grep -rnI "$pattern" "$CLI_DIR"/*.sh 2>/dev/null \
+        | grep -vE '^\s*#|test_|_test\.|spec\.|SPEC' \
+        | grep -vE 'systemctl|is-active|ActiveState|ActiveEnter' \
+        || true)
+
+    local count
+    count=$(echo "$hits" | grep -c . 2>/dev/null || echo "0")
+
+    if [[ "$count" -gt 0 && -n "$hits" ]]; then
+        echo "  FOUND ($count)  \"$phrase\" — $description"
+        echo "$hits" | head -5 | sed 's/^/    /'
+        if [[ "$count" -gt 5 ]]; then
+            echo "    ... and $((count - 5)) more"
+        fi
+        total_findings=$((total_findings + count))
+    else
+        echo "  CLEAN        \"$phrase\""
+    fi
+    echo ""
+}
+
+echo "[1] Vocabulary-banned terms in CLI output"
+echo ""
+
+scan_phrase "healthy" \
+    "banned: use PROTECTED with evidence" \
+    '"healthy"\|= healthy\|: healthy\|"HEALTHY"'
+
+scan_phrase "working" \
+    "banned: use specific axis state" \
+    '"working"\|is working'
+
+scan_phrase "OK (health)" \
+    "banned in health context: use PROTECTED" \
+    '"OK"\|= "OK"\|="OK"'
+
+scan_phrase "all clear" \
+    "banned: absence of evidence != evidence of absence" \
+    '"all clear"\|all clear'
+
+scan_phrase "no attacks" \
+    "banned: zero is NEUTRAL, not proof of safety" \
+    '"no attacks"\|no attacks detected'
+
+scan_phrase "threats blocked" \
+    "banned: counter interpretation" \
+    'threats.blocked\|attacks.blocked'
+
+scan_phrase "protecting your" \
+    "banned: PRESENT != ENFORCING" \
+    'protecting your\|protects your'
+
+echo "=========================================================="
+echo "Total findings: $total_findings"
+echo ""
+echo "NOTE: This scan is informational for v1.81."
+echo "Full enforcement (CI blocking) is v1.82 scope."
+echo "=========================================================="
+
+# Exit 0 always — informational, not blocking
+exit 0
@@ -30,16 +30,28 @@ func RunValidation(ctx context.Context) (*ValidationResult, error) {
 	return ValidateKernel(ctx)
 }
 
-// ToJSON converts the validation result to JSON.
+// ToJSON converts the validation result to the frozen M81-6 JSON schema.
+// Uses MapToHealthOutput to enforce the schema contract — never serializes
+// the internal ValidationResult directly.
 func (r *ValidationResult) ToJSON() ([]byte, error) {
+	output := MapToHealthOutput(r)
+	return json.MarshalIndent(output, "", "  ")
+}
+
+// ToJSONLegacy serializes the raw ValidationResult for backward compat.
+// Used by rebuild safety checks that parse the old schema.
+// TODO(v1.82): migrate consumers to frozen schema then remove this.
+func (r *ValidationResult) ToJSONLegacy() ([]byte, error) {
 	return json.MarshalIndent(r, "", "  ")
 }
 
-// StatusString returns a human-readable status with emoji.
+// StatusString returns a human-readable status.
 func (r *ValidationResult) StatusString() string {
 	switch r.Status {
 	case StatusProtected:
 		return "PROTECTED"
+	case StatusIdle:
+		return "IDLE"
 	case StatusDegraded:
 		return "DEGRADED"
 	case StatusDown:
@@ -50,10 +62,11 @@ func (r *ValidationResult) StatusString() string {
 }
 
 // ExitCode returns the appropriate exit code for the status.
-// 0 = PROTECTED, 1 = DEGRADED, 2 = DOWN
+// 0 = PROTECTED or IDLE, 1 = DEGRADED, 2 = DOWN
+// Per M81-4: IDLE is exit 0 (not an error).
 func (r *ValidationResult) ExitCode() int {
 	switch r.Status {
-	case StatusProtected:
+	case StatusProtected, StatusIdle:
 		return 0
 	case StatusDegraded:
 		return 1