Project Overview#

Codebase Metrics#

Architecture Overview#

Design Principles#

• Offline-First: Zero external dependencies, complete airgap compatibility
• Operator-Focused: Built for network administrators and security professionals
• Framework-First: Leverages established Go libraries (Cobra, Charm ecosystem)
• Security-First: No telemetry, input validation, secure processing, XXE prevention
• Multi-Device Extensible: Clean separation between XML DTOs and platform-agnostic domain model

Technology Stack#

CLI Commands#

Two-Stage Parsing Architecture#

The core data pipeline separates XML-specific concerns from domain logic, enabling multi-device support through a pluggable registry system. The Factory now uses a DeviceParserRegistry for dispatch instead of hardcoded switch statements.

graph TD
    A["config.xml"] --> B["cfgparser/xml.go"]
    B --> C["schema.OpnSenseDocument<br/>(XML DTOs)"]
    C --> D["ParserFactory<br/>(auto-detect device type)"]
    D --> E["opnsense/converter.go"]
    E --> F["common.CommonDevice<br/>(platform-agnostic)"]
    F --> G["prepareForExport()<br/>(enrichment)"]
    G --> H["JSON / YAML / Markdown<br/>Output"]

Stage 1: XML Parsing#

Package: internal/cfgparser/
The streaming XML parser reads OPNsense config.xml into schema.OpnSenseDocument DTOs. Key features:

• Security protections: XXE prevention, XML bomb protection
• Charset conversion: UTF-8, US-ASCII, ISO-8859-1, Windows-1252
• Streaming processing: Memory-efficient handling of large configurations
• Switch-case routing: Each top-level XML element dispatched by tag name in xml.go

Stage 2: Domain Conversion#

Package: internal/model/opnsense/
The converter transforms XML DTOs into the platform-agnostic CommonDevice model:

• converter.go -- core conversion and system fields
• converter_network.go -- bridges, PPPs, GIFs, GREs, LAGGs, VIPs, interface groups
• converter_security.go -- certificates, CAs, packages
• converter_services.go -- DHCP, DNS, VPN, routing, etc.

ParserFactory#

File: internal/model/factory.go
ParserFactory.CreateDevice() auto-detects the device type by inspecting the root XML element. The --device-type flag bypasses auto-detection. Currently only OPNsense is implemented; the interface is designed for extension.

Data Model Layer#

Three-Layer Architecture#

CommonDevice Structure#

The CommonDevice model organizes data into three categories:
Core Configuration (concrete types, populated during parsing):

• System, Interfaces, VLANs, Bridges, LAGGs, VirtualIPs, GIFs, GREs, PPPs
• Firewall Rules, NAT (inbound + outbound), VPN (OpenVPN, WireGuard, IPsec)
• Routing (gateways, static routes), Services (DHCP, DNS, NTP, SNMP)
• Security (certificates, CAs, IDS/IPS), Users, Groups, Packages
  Optional Features (pointer types for non-universal features):
• IDS/IPS (Suricata), Monit, Netflow/IPFIX, Traffic shaper, Captive portal, Cron, Kea DHCP
  Enrichment Fields (pointer types, populated by prepareForExport()):
• *Statistics, *Analysis, *SecurityAssessment, *PerformanceMetrics, *ComplianceChecks

XML Type Patterns#

Enrichment Pipeline#

File: internal/converter/enrichment.go
The prepareForExport() function is the single gate for all JSON/YAML exports. It enriches a shallow copy of CommonDevice with computed analytics:

graph TD
    A["CommonDevice<br/>(from converter)"] --> B["prepareForExport()"]
    B --> C["computeStatistics()"]
    B --> D["computeAnalysis()"]
    B --> E["computeSecurityAssessment()"]
    B --> F["computePerformanceMetrics()"]
    C --> G["Enriched CommonDevice"]
    D --> G
    E --> G
    F --> G
    G -->|"if redact=true"| H["redactSensitiveFields()"]
    H --> I["Final Export"]
    G -->|"if redact=false"| I

Key design constraints:

• Immutability: Creates shallow copies with selective deep-copying before redaction
• Circular dependency avoidance: Cannot import internal/processor -- analysis logic is mirrored, not shared. This is a deliberate architectural trade-off (package independence over code deduplication)
• Redaction flow: CLI flag -> Options.Redact -> prepareForExport(data, redact) -> conditional redaction
• Statistics synchronization: Adding fields to common.Statistics requires updating three places (struct definition, computeStatistics(), and computeTotalConfigItems())

Compliance Plugin System#

Architecture#

graph TD
    A["CLI audit command"] --> B["PluginManager"]
    B --> C["PluginRegistry<br/>(thread-safe, sync.RWMutex)"]
    C --> D["Firewall Plugin"]
    C --> E["SANS Plugin"]
    C --> F["STIG Plugin"]
    D --> G["RunChecks(*CommonDevice)"]
    E --> G
    F --> G
    G --> H["[]Finding"]
    H --> I["Compliance Report"]

Core Components#

Audit Report Modes#

Known Audit Issues (Tracked)#

• #310: calculateSummary severity counting is non-functional -- Finding.Type is always "compliance", not a severity level
• #309: No panic recovery around plugin RunChecks() calls -- dynamic plugins can crash entire audit
• #311: Dynamic plugin load failures are silently swallowed

Report Generation System#

Reports are generated programmatically using builder.MarkdownBuilder (backed by nao1215/markdown). There is no template system -- all markdown is constructed via Go method calls for type safety, performance, and testability.

Builder Architecture#

Sanitizer & Redaction#

The sanitizer uses a rule-based engine for sensitive data redaction:

• Field-pattern rules: Match by field name (e.g., password, secret, otp_seed)
• Value-detector rules: Match by value content (e.g., IP addresses with IsIP detector)
• Deterministic mapping: Fresh RuleEngine creates fresh Mapper -- first private IP always maps to 10.0.0.1, first hostname to host-001.example.com
• --redact** flag**: Opt-in redaction for convert and display commands

Configuration Diff Engine#

Package: internal/diff/
The diff command compares two OPNsense configurations and outputs a structured change report. Uses comparison functions with nil-safe patterns (both-nil -> nil, one-nil -> added/removed) and slices.Equal() for slice fields.

Package Dependency Structure#

The internal packages follow a layered architecture with clear dependency direction:

graph TD
    CMD["cmd/"] --> MODEL["model/"]
    CMD --> PROCESSOR["processor/"]
    CMD --> CONVERTER["converter/"]
    CMD --> CFGPARSER["cfgparser/"]
    CMD --> VALIDATOR["validator/"]
    CMD --> DISPLAY["display/"]
    CMD --> AUDIT["audit/"]
    CMD --> CONFIG["config/"]
    CMD --> SANITIZER["sanitizer/"]
    CMD --> DIFF["diff/"]
    CMD --> PROGRESS["progress/"]
    CMD --> EXPORT["export/"]
    PROCESSOR --> MODEL
    CONVERTER --> MODEL
    CONVERTER --> BUILDER["converter/builder/"]
    AUDIT --> COMPLIANCE["compliance/"]
    AUDIT --> PLUGINS["plugins/"]
    PLUGINS --> COMPLIANCE
    PLUGINS --> MODEL
    CFGPARSER --> SCHEMA["schema/"]
    MODEL --> SCHEMA
    MODEL --> COMMON["model/common/"]
    MODEL --> OPNSENSE["model/opnsense/"]
    OPNSENSE --> SCHEMA
    OPNSENSE --> COMMON

Key constraint: converter/ and processor/ both depend on model/common/ but cannot depend on each other (circular dependency). Analysis logic is deliberately mirrored in both packages.

CI/CD Pipeline#

Quality Gate#

just ci-check runs the full CI-equivalent locally: pre-commit hooks + gofumpt formatting check + golangci-lint + all tests. Tasks are not complete until ci-check passes.

Open Issues & Roadmap#

Priority: Critical (Architecture)#

Priority: High#

Public API Roadmap#

Milestones#

Multi-Device Support Roadmap#

v2.0 Feature Epics#

Recent Development Activity#

Most recent closed issues (as of March 2026):

Known Technical Debt#

Architectural Constraints#

• Circular dependency: converter/enrichment.go and processor/ both need analysis logic but cannot import each other. Analysis is mirrored in both packages. Issue #321 targets extracting a shared internal/analysis/ package.
• Re-export layer: 93 type aliases in internal/model/ re-export types from internal/schema/ and internal/model/common/. Temporary seam for multi-device migration; removal planned in v1.3.0 (issue #282).
• ReportBuilder interface: Currently 18 methods in a single interface. Issue #323 targets splitting into focused interfaces.
• Sequential plugin execution: No concurrent plugin execution; potential bottleneck for large configurations with many compliance checks.

Code Quality Items#

• Global state: Package-level variables in cmd/ (required by Cobra's flag binding) and audit/plugin.go
• Context underutilization: context.Context not fully leveraged in long-running operations
• Finding type duplication: Three similar Finding types across compliance, processor, and audit packages (issue #280)
• Severity type scattered: No shared severity enum; each package defines its own (issue #324)

Schema Gaps#

• ~40+ string fields should be BoolFlag type
• ~9 struct{} fields should be BoolFlag
• Source/Destination missing Address, Not, and Port (Source) fields (issue #255)
• Full inventory documented in docs/development/xml-structure-research.md

Developer Gotchas#

Package Breakdown by Size#

Document Metadata#