Registry Architecture

Registry Architecture

NFTBan uses a unified registry system to maintain single sources of truth for commands, configuration, and reporting metadata.

Overview

┌──────────────────────────────────────────────────────────────────────────────┐
│                        NFTBan Registry System                                 │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐  │
│  │ commands.registry   │  │ config-registry     │  │ reports-registry    │  │
│  │       .yml          │  │       .json         │  │       .json         │  │
│  │                     │  │                     │  │                     │  │
│  │  76 CLI commands    │  │  24 config files    │  │  18 report types    │  │
│  │  • categories       │  │  • mode activation  │  │  • CLI commands     │  │
│  │  • RBAC/audience    │  │  • runtime checks   │  │  • metrics          │  │
│  │  • capabilities     │  │  • categories       │  │  • API endpoints    │  │
│  │  • examples         │  │                     │  │  • delivery methods │  │
│  └─────────────────────┘  └─────────────────────┘  └─────────────────────┘  │
│                                                                              │
│                     ┌─────────────────────┐                                  │
│                     │ config-schema.json  │                                  │
│                     │                     │                                  │
│                     │  960 config keys    │                                  │
│                     │  • types/defaults   │                                  │
│                     │  • validation rules │                                  │
│                     │  • dependencies     │                                  │
│                     └─────────────────────┘                                  │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

Registry Files

Registry	File	Purpose	Count
CLI Commands	commands.registry.yml	Command definitions, RBAC, capabilities	76 commands
Config Files	cli/lib/nftban/data/config-registry.json	Config file metadata, mode activation	24 files
Config Schema	cli/lib/nftban/data/config-schema.json	Key definitions, types, validation	960 keys
Reports	cli/lib/nftban/data/reports-registry.json	Report types, metrics, delivery	18 reports

Commands Registry (commands.registry.yml)

The commands registry is the single source of truth for all CLI commands.

Schema

command_name:
  category: setup_discovery | immediate_action | active_protection | ...
  description: "Human-readable description"
  risk: core | setup | advanced
  audience: [cli, auditor, panel]
  capability: status_read | stats_read | config_view | enforcement | ...
  mutates: true | false | conditional
  supports_dry_run: true | false
  requires_root: true | false
  panel_expose: true | false
  output_modes: [json, text]
  has_json: true | false
  examples:
    - "nftban command example"
  subcommands:
    subname: {mutates: false, description: "..."}

Categories

Category	Purpose
setup_discovery	Initial setup, health checks, status
immediate_action	Ban/unban, whitelist management
active_protection	Protection modules (DDoS, portscan, etc.)
infrastructure	Feeds, GeoIP, trust management
intelligence_reporting	Stats, analytics, reports
developer_sysadmin	Debug, maintenance tools

Audience Types

• cli: Command-line users (full access)
• auditor: Read-only audit/compliance view
• panel: Hosting panel integration (restricted)

Uses

1. Auto-generated help: nftban help reads from registry
2. Man page generation: tools/generate-man-pages.sh
3. Wiki documentation: Filter by audience for operator/auditor/panel views
4. RBAC enforcement: Check capability before execution
5. Bash completion: Generate completions from command list

Config Registry (config-registry.json)

Defines all configuration files with mode-aware activation rules.

Features

• Mode activation: Rules for when config files are active
• Runtime checks: Suricata detection, panel detection
• Categories: system, paths, features, modules, etc.

Example Entry

{
  "files": {
    "conf.d/ddos/classic.conf": {
      "description": "DDoS Classic mode settings",
      "category": "modules",
      "activation": "ddos_classic",
      "required": false
    }
  }
}

Config Schema (config-schema.json)

Defines all 960 configuration keys with validation rules.

Key Properties

• type: string, integer, boolean, array, etc.
• default: Default value
• validation: Regex, range, enum values
• depends_on: Other keys this depends on
• deprecated: Deprecation info if applicable

Reports Registry (reports-registry.json)

Defines all report types with metrics and delivery options.

Report Types

Report	Category	CLI Command
dashboard	on_demand	nftban stats dashboard
daily	scheduled	nftban report generate daily
weekly	scheduled	nftban report generate weekly
health	health	nftban health
rbl_status	on_demand	nftban rbl status
rbl_watchlist	on_demand	nftban rbl watchlist check

Delivery Methods

• stdout: Terminal output
• filesystem: Save to /var/lib/nftban/reports/
• email: Send via sendmail/SMTP
• api: JSON via REST API
• prometheus: Metrics export

Validation

Production Health Check

# Quick syntax validation
nftban health registries

# JSON output for monitoring
nftban health registries --json

Deep Analysis (Development/CI)

# Full registry validation via nftban-validator
cd nftban-validator
./scripts/validate_registries.sh ../nftban ./output

# Or run all validations
./scripts/run_all.sh

Validation Checks

Check	Description
REG-001	JSON/YAML syntax validation
REG-002	Commands registry required fields
REG-003	Config file existence verification
REG-004	Reports CLI command cross-check
REG-005	Cross-registry consistency
REG-006	Statistics summary

Querying Registries

Commands by Audience

# Panel-exposed commands
grep -B5 "panel_expose: true" commands.registry.yml | grep "^[a-z]"

# Auditor-visible commands
grep -B10 "auditor" commands.registry.yml | grep "^[a-z]"

Config by Module

# RBL config files
jq '.files | to_entries[] | select(.key | startswith("conf.d/rbl"))' \
  cli/lib/nftban/data/config-registry.json

Reports by Category

# Scheduled reports
jq '.report_types | to_entries[] | select(.value.category == "scheduled")' \
  cli/lib/nftban/data/reports-registry.json

Best Practices

1. Single Source of Truth: Always update registry when adding commands
2. Validate Before Commit: Run nftban health registries locally
3. Keep Synchronized: Registry should match actual implementation
4. Document Examples: Include practical examples in registry entries
5. Use Categories: Proper categorization aids discovery and documentation

Related

• CLI-Commands-Reference - Full command documentation
• Configuration-Reference - All configuration keys
• Health-Check-Guide - System diagnostics