Introduction & Scope#

Project Overview#

Project Description and Purpose: opnDossier is a CLI tool designed to convert OPNsense firewall configuration files (config.xml) into human-readable Markdown documentation. It provides operators with clear visibility into their firewall configurations for documentation, auditing, and troubleshooting purposes.
Project Goals and Objectives:

• Enable offline-first configuration analysis and documentation
• Provide operator-focused design for security professionals
• Support airgapped environments with zero external dependencies
• Generate structured, readable documentation from XML configurations
• Maintain security-first approach with no telemetry or external communication
  Target Audience and Stakeholders: Network security operators and administrators, security auditors and compliance teams, DevOps engineers managing OPNsense firewalls, and documentation teams requiring configuration visibility.
  Project Boundaries and Limitations: Architecture supports multiple device types; currently only OPNsense is supported (others planned). No real-time configuration monitoring or management. No integration with live firewall systems. Offline-only operation with no external API dependencies.

Scope Definition#

In-scope Features and Functionality: XML configuration file parsing and validation, Markdown conversion with syntax highlighting, terminal display with colored output, file export to markdown format, configuration management via YAML files and environment variables, cross-platform CLI interface, and offline operation without external dependencies.
Out-of-scope Items: Real-time firewall configuration management, network connectivity or external API calls, GUI or web interface development, configuration backup or restore functionality, and telemetry or analytics collection.
Planned/Future: Support for additional device types (pfSense, Cisco ASA, etc.) is planned; the ParserFactory is extensible but not yet populated for other platforms.
Success Criteria and Acceptance Criteria:

• Successfully parse valid OPNsense config.xml files
• Generate readable markdown documentation
• Operate completely offline without errors
• Maintain >80% test coverage
• Pass all linting and quality checks
• Support cross-platform compilation and distribution
  Timeline and Milestones:
• Phase 1: Core XML parsing and markdown conversion
• Phase 2: CLI interface and configuration management
• Phase 3: Testing, documentation, and release preparation
• Phase 4: Distribution and package management support

Context and Background#

Business Context and Justification: OPNsense firewalls are widely used in enterprise environments. Configuration documentation is critical for security compliance. Manual documentation is error-prone and time-consuming. Offline tools are essential for airgapped security environments.
Previous Work and Dependencies: Built on Go ecosystem and Charm libraries. Leverages existing OPNsense configuration format. Follows established CLI development patterns. Integrates with existing documentation workflows.
Assumptions and Constraints: Assumes valid OPNsense config.xml file format, requires Go 1.26+ runtime environment, assumes local file system access for input/output, and constrained to offline operation only.
Risk Assessment Overview:

• Low risk: Well-established technology stack
• Medium risk: XML parsing complexity and edge cases
• Low risk: Security concerns (offline operation)
• Medium risk: Cross-platform compatibility challenges

Functional Requirements#

Core Features#

Primary Functionality Requirements:

• F001: Parse OPNsense XML configuration files using Go's encoding/xml package
• F002: Convert XML configurations to structured Markdown format with hierarchy preservation (comprehensive, summary), using programmatic Go code via builder.MarkdownBuilder (selectable via CLI flag)
• F003: Display processed configurations with syntax highlighting in terminal using Charm Lipgloss (selectable via CLI flag)
• F004: Export processed configurations to markdown files on disk with user-specified paths, as markdown or JSON or YAML (selectable via CLI flag), without special formatting for the terminal
• F005: Support offline operation without external dependencies or network connectivity
• F006: Generate human-readable documentation from XML configuration data (selectable via CLI flag)
• F007: Accept OPNsense config.xml files as input through command-line arguments
• F008: Validate XML structure and provide meaningful error messages for malformed files
• F009: Support multiple themes (light, dark, custom) for terminal display (selectable via CLI flag)
• F010: Support multiple output formats (markdown, json, yaml) for file export (selectable via CLI flag)
• F011: Support multiple output styles (comprehensive, summary) for markdown generation (selectable via CLI flag)
• F012: Support multiple output styles (comprehensive, summary) for terminal display (selectable via CLI flag)
• F013: Support multiple output styles (comprehensive, summary) for file export (selectable via CLI flag)
• F014: Analyze the XML configuration and provide a report of the configuration, containing common security and performance issues, if any are found
• F015: Export files must be valid and parseable by standard tools and libraries (markdown linters, JSON parsers, YAML parsers)
• F016: Support audit report generation in three modes: standard (neutral documentation), blue (defensive analysis with findings and recommendations), and red (attack surface enumeration with optional blackhat commentary)
• F017: Generate Markdown reports using programmatic Go code via builder.MarkdownBuilder with sections for interfaces, firewall rules, NAT rules, DHCP, certificates, VPN config, static routes, and high availability
• F018: Red team mode must highlight WAN-exposed services, weak NAT rules, admin portals, attack surfaces, and provide pivot data (hostnames, static leases, service ports) with optional blackhat commentary
• F019: Blue team mode must include audit findings (insecure SNMP, allow-all rules, expired certs), structured configuration tables, and actionable recommendations with severity ratings
• F020: Standard mode must produce detailed neutral configuration documentation including system metadata, rule counts, interfaces, certificates, DHCP, routes, and high availability
• F021: Use consistent audit finding structure with Title, Severity, Description, Recommendation, Tags (Red mode adds AttackSurface, ExploitNotes)
• F022: Support plugin-based compliance architecture with standardized interfaces, dynamic registration, lifecycle management, metadata tracking, configuration support, dependency management, and statistics reporting for both internal and external plugins
• F023: Support convert mode that processes OPNsense XML configuration files and exports to JSON, YAML, or Markdown files on disk (with error handling, overwrite protection, and smart file naming)
• F024: Support display mode that converts XML configurations to Markdown and renders in terminal with syntax highlighting using Charm Lipgloss (supporting themes from F009 and output styles from F012)
• F025: Support audit mode that runs the compliance audit engine using plugin architecture (F022) and programmatic report generation (F017) with all three modes (F016) and structured findings (F021)
• F026: Support programmatic markdown generation system that creates structured markdown output using Go code rather than templates, providing better performance, maintainability, consistency, testability, and separation of concerns

User Stories and Use Cases#

• Primary Workflow: User obtains OPNsense config.xml file → runs opnDossier convert config.xml → system parses XML, converts to markdown, displays in terminal → user optionally exports to file
• Configuration Workflow: User creates YAML config file with preferred settings → sets environment variables for sensitive options → runs commands with config automatically applied → overrides with CLI flags as needed
• Error Recovery Workflow: System detects invalid XML → provides specific error message with line/column information → user corrects input file → re-runs command successfully
• Plugin Compliance Workflow: User selects compliance plugins → system loads and validates plugins → runs compliance checks against configuration → generates comprehensive compliance report with findings and recommendations

Feature Priority Matrix#

• High Priority: XML parsing, markdown conversion, CLI interface, offline operation, plugin architecture
• Medium Priority: Configuration management, file export, error handling, compliance plugins
• Low Priority: Advanced formatting options, template customization, external plugin support

Performance Requirements#

• Individual tests must complete in <100ms
• CLI startup time should be quick for operator efficiency
• Memory-efficient streaming XML processing for large files
• Concurrent processing using goroutines and channels for I/O operations

User Interface Requirements#

User Experience Specifications: Intuitive command-line interface using Cobra framework, comprehensive help documentation for all commands, usage examples and common workflow guidance, verbose and quiet output modes, progress indicators for long-running operations, and human-friendly file size and processing time information.
Accessibility Requirements: Support for both light and dark terminal themes, consistent output formatting across different terminal environments, clear actionable error messages for all failure scenarios, and tab completion for command-line options where supported.

Data Requirements#

Data Models and Structures: OPNsense XML configuration schema representation, Markdown output format specification, configuration hierarchy preservation, and metadata structures (version, timestamp, generation info).
Data Validation Rules: XML structure validation against OPNsense schema, input file existence and readability checks, output directory creation and write permissions, and configuration file format validation (YAML).
Data Persistence: Temporary processing of XML files in memory, Markdown file output to user-specified locations, configuration file persistence for user preferences. No database or persistent storage required.

Integration Requirements#

All integration categories (external systems, APIs, third-party services, authentication) are N/A — opnDossier is designed for offline-only, local file processing operation.#

Technical Specifications#

Technology Stack#

Language/Runtime Versions#

• Go: 1.26 (toolchain: go1.26.0)
• Python: 3.11+ (development: 3.13.5 for documentation)

Core Libraries and Frameworks#

• CLI Framework: github.com/spf13/cobra v1.8.0
• Configuration Management: spf13/viper for configuration parsing
• CLI Enhancement: charmbracelet/fang for enhanced CLI experience with styled help, errors, and automatic features
• Terminal Styling: charmbracelet/lipgloss for colored output
• Markdown Rendering: charmbracelet/glamour for terminal markdown display
• Markdown Generation: nao1215/markdown for programmatic report building
• Standard Library: encoding/xml, encoding/json, gopkg.in/yaml.v3 for data processing
• Structured Logging: charmbracelet/log for consistent logging

Build Tools and Dependency Management#

• Go Modules: go.mod and go.sum for dependency management
• Task Runner: just (Justfile) for development tasks
• Release Management: GoReleaser v2 for cross-platform builds
• Pre-commit Hooks: pre-commit v5.0.0 for code quality automation

Testing Frameworks#

• Unit Testing: Go's built-in testing package
• Test Organization: Table-driven tests with t.Run() subtests
• Coverage Analysis: go test -cover with >80% coverage target
• Benchmarking: go test -bench for performance testing
• Race Detection: go test -race for concurrency testing
• Integration Tests: Build tags (//go:build integration)

Code Quality and Linting#

• Formatter: gofmt and gofumpt for code formatting
• Linter: golangci-lint with comprehensive rule set
• Static Analysis: go vet for code analysis
• Import Management: goimports for import organization
• Security Scanning: gosec via golangci-lint

CI/CD Expectations#

Automated Quality Checks#

• Pre-commit Hooks (automated on every commit): File format validation (JSON, YAML, XML), Markdown formatting with mdformat, line ending normalization, large file detection
• Commit Message Validation: commitlint for conventional commits
• Continuous Integration: GitHub Actions (implied by GoReleaser config)

Build and Release Pipeline#

• Multi-platform Builds: Linux, macOS, Windows (amd64, arm64)
• Package Formats: tar.gz, zip, deb, rpm, apk, archlinux
• Code Signing: macOS notarization support
• SBOM Generation: Software Bill of Materials for security
• Automated Changelogs: Conventional commit-based

Development Workflow Commands#

just install # Install dependencies and tools
just dev # Run development server
just format # Run formatting fixes
just lint # Run linting and code checks
just test # Run test suite
just check # Run pre-commit checks
just ci-check # Run CI-equivalent checks
just build # Build application

Performance Constraints#

CLI Performance Requirements#

• Test Performance: Individual tests <100ms
• Startup Time: CLI should start quickly for operator efficiency
• Memory Efficiency: Streaming XML processing for large files
• Concurrent Processing: Goroutines and channels for I/O operations

Resource Utilization#

• Zero External Dependencies: Offline-first architecture
• Local Processing: All operations work without internet
• Portable Binaries: Static compilation with CGO_ENABLED=0
• Cross-platform Support: Native binaries for major platforms

Security Requirements#

Code Security#

• No hardcoded secrets — environment variables for sensitive data
• Comprehensive input validation for XML parsing
• Security-first configuration defaults
• gosec static security analysis integration

Operational Security#

• Full airgap compatibility — functionality in isolated environments
• No telemetry — no external data transmission
• Portable data exchange — secure data bundle import/export
• Error message safety — no sensitive information exposure

Dependency Security#

• Minimal dependencies for reduced attack surface
• Automated dependency vulnerability scanning
• Go module checksums and verification for supply chain security
• SBOM generation for dependency transparency

Infrastructure Requirements#

Development Environment#

• Go Toolchain: 1.21.6+ with module support
• Python Environment: 3.11+ for documentation (MkDocs)
• Documentation: MkDocs Material for project documentation
• Version Control: Git with conventional commit workflow

Deployment Architecture#

• Distribution: GitHub Releases with multi-platform binaries
• Package Managers: Support for system package managers
• Container Support: Minimal binary suitable for containers (scratch or alpine base, single binary deployment, multi-stage builds)
• Configuration Management: Environment variables with OPNDOSSIER_ prefix, YAML configuration files, command-line flags for runtime overrides
• Precedence Order: CLI flags > Environment variables > Config file > Defaults

Monitoring and Observability#

• Structured Logging: charmbracelet/log for consistent logging
• Error Handling: Comprehensive error wrapping with context
• Performance Profiling: go tool pprof integration capability
• Health Checks: CLI self-validation commands

Document Metadata#