opnFocus

command module
v1.0.0-rc1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 1, 2025 License: Apache-2.0 Imports: 5 Imported by: 0

README

opnFocus - OPNsense Configuration Processor

Go Version License Coverage Documentation wakatime

v1.0 Release - Essential CLI Tool for OPNsense Configuration Processing

Overview

A command-line tool designed specifically for network operators and administrators working with OPNsense firewalls. This tool transforms complex XML configuration files into clear, human-readable markdown documentation, making it easier to understand, document, and audit your network configurations.

Built for operators, by operators - with a focus on offline operation, structured data, and intuitive workflows.

v1.0 Release Features

opnFocus v1.0 provides a robust foundation for OPNsense configuration processing:

  • Core XML Processing: Parse and validate OPNsense config.xml files
  • Multi-Format Export: Convert to markdown, JSON, or YAML formats
  • Terminal Display: Rich terminal output with syntax highlighting and themes
  • File Export: Save processed configurations with overwrite protection
  • Offline Operation: Complete offline functionality for airgapped environments
  • Cross-Platform: Native binaries for Linux, macOS, and Windows
  • Comprehensive Error Handling: Detailed validation and error reporting

Features

  • 🔧 Parse OPNsense XML configurations - Process complex configuration files with ease
  • Configuration Validation - Comprehensive validation with detailed error reporting
  • 📝 Convert to Markdown - Generate human-readable documentation from XML configs
  • 💾 Export to Files - Save processed configurations as markdown, JSON, or YAML files
  • 🔌 Offline Operation - Works completely offline, perfect for airgapped environments
  • 🛡️ Security-First - No external dependencies, no telemetry, secure by design
  • ⚡ Fast & Lightweight - Built with Go for performance and reliability
  • 🚀 Streaming Processing - Memory-efficient handling of large configuration files
  • 🔍 Advanced Analysis - Dead rule detection, unused interface analysis, and security scanning
  • 📊 Compliance Checking - Built-in compliance validation with detailed reporting
  • 🎨 Template-Based Reports - Customizable markdown templates for professional documentation
  • 📈 Performance Analysis - Identifies configuration bottlenecks and optimization opportunities
  • 🖥️ Terminal Display - Rich terminal output with syntax highlighting and theme support

Quick Start

Installation

Prerequisites: Go 1.21 or later

# Clone the repository
git clone https://github.com/unclesp1d3r/opnFocus.git
cd opnFocus

# Install dependencies and build
just install
just build
Alternative Installation Methods
# Direct Go installation
go install github.com/unclesp1d3r/opnFocus@latest

# Or build from source
go build -o opnfocus main.go
Pre-built Binaries (Coming Soon)

Pre-built binaries for Linux, macOS, and Windows will be available with the v1.0 release.

Basic Usage
# Convert OPNsense config to markdown (default format)
opnFocus convert config.xml

# Convert to markdown and save to file
opnFocus convert config.xml -o documentation.md

# Convert to markdown format explicitly
opnFocus convert -f markdown config.xml

# Convert to JSON format
opnFocus convert -f json config.xml -o output.json

# Convert to YAML format
opnFocus convert -f yaml config.xml -o output.yaml

# Display configuration in terminal with syntax highlighting
opnFocus display config.xml

# Validate configuration file
opnFocus validate config.xml

# Get help for any command
opnFocus --help
opnFocus convert --help
Configuration

opnFocus uses Viper for layered configuration management with a clear precedence order:

  1. Command-line flags (highest priority)
  2. Environment variables (OPNFOCUS_*)
  3. Configuration file (~/.opnFocus.yaml)
  4. Default values (lowest priority)
Configuration File Example

Create ~/.opnFocus.yaml with your preferred settings:

# ~/.opnFocus.yaml - opnFocus Configuration

# Input/Output settings
input_file: /path/to/default/config.xml
output_file: ./output.md

# Logging configuration
log_level: info       # debug, info, warn, error
log_format: text      # text, json
verbose: false        # Enable debug logging
quiet: false          # Suppress all output except errors
Environment Variables

All configuration options can be set via environment variables:

# Logging options
export OPNFOCUS_VERBOSE=true          # Enable verbose/debug logging
export OPNFOCUS_QUIET=false           # Suppress non-error output
export OPNFOCUS_LOG_LEVEL=debug       # Set log level
export OPNFOCUS_LOG_FORMAT=json       # Use JSON log format

# File paths
export OPNFOCUS_INPUT_FILE="/path/to/config.xml"
export OPNFOCUS_OUTPUT_FILE="./documentation.md"

# Run with environment configuration
opnfocus convert config.xml
CLI Flag Examples
# Basic conversion with verbose logging
opnfocus --verbose convert config.xml -o output.md

# JSON logging format for structured output
opnfocus --log_format=json convert config.xml

# Quiet mode - only show errors
opnfocus --quiet convert config.xml

# Custom log level
opnfocus --log_level=debug convert config.xml

# Enable validation during conversion
opnfocus convert config.xml --validate

# Configuration precedence: CLI flags override everything
opnfocus --verbose --log_format=json convert config.xml

Note: The CLI uses a layered architecture: Cobra provides command structure and argument parsing, Viper handles layered configuration management (files, env, flags), and Fang adds enhanced UX features like styled help, automatic version flags, and shell completion.

Validation & Error Handling

opnFocus v1.0 includes comprehensive validation capabilities to ensure configuration integrity:

Validation Features
  • Configuration Structure Validation - Validates required fields like hostname, domain, and network interfaces
  • Data Type Validation - Ensures IP addresses, subnet masks, and network configurations are valid
  • Cross-Field Validation - Checks relationships between configuration elements
  • Streaming Processing - Handles large files efficiently with memory-conscious processing
  • XML Schema Validation - Validates against OPNsense configuration schema
Typical Error Output Examples

Parse Error Example:

parse error at line 45, column 12: XML syntax error: expected element name after <

Validation Error Example:

validation error at opnsense.system.hostname: hostname is required
validation error at opnsense.interfaces.wan.ipaddr: IP address '300.300.300.300' must be a valid IP address

Aggregated Validation Report:

validation failed with 3 errors: hostname is required (and 2 more)
  - opnsense.system.hostname: hostname is required
  - opnsense.system.domain: domain is required
  - opnsense.interfaces.lan.subnet: subnet mask '35' must be a valid subnet mask (0-32)
Streaming Processing Limits
  • Memory Efficiency: Processes large XML files without loading entire document into memory
  • Element Streaming: Handles configurations with thousands of rules or large sysctl sections
  • Garbage Collection: Automatic memory cleanup after processing large sections
  • Error Recovery: Continues processing when possible, collecting all validation errors

Architecture

Built with modern Go practices and established libraries:

Component Technology
CLI Framework Cobra
Configuration Viper
CLI Enhancement Charm Fang
Terminal Styling Charm Lipgloss
Markdown Rendering Charm Glamour
XML Processing Go's built-in encoding/xml
Structured Logging Charm Log
Data Model Architecture

opnFocus uses a hierarchical model structure that mirrors the OPNsense XML configuration while organizing functionality into logical domains:

graph TB
    subgraph "Root Configuration"
        ROOT[Opnsense Root]
        META[Metadata & Global Settings]
    end

    subgraph "System Domain"
        SYS[System Configuration]
        USERS[User Management]
        GROUPS[Group Management]
        SYSCFG[System Services Config]
    end

    subgraph "Network Domain"
        NET[Network Configuration]
        IFACES[Interface Management]
        ROUTING[Routing & Gateways]
        VLAN[VLAN Configuration]
    end

    subgraph "Security Domain"
        SEC[Security Configuration]
        FIREWALL[Firewall Rules]
        NAT[NAT Configuration]
        VPN[VPN Services]
        CERTS[Certificate Management]
    end

    subgraph "Services Domain"
        SVC[Services Configuration]
        DNS[DNS Services]
        DHCP[DHCP Services]
        MONITOR[Monitoring Services]
        WEB[Web Services]
    end

    ROOT --> META
    ROOT --> SYS
    ROOT --> NET
    ROOT --> SEC
    ROOT --> SVC

    SYS --> USERS
    SYS --> GROUPS
    SYS --> SYSCFG

    NET --> IFACES
    NET --> ROUTING
    NET --> VLAN

    SEC --> FIREWALL
    SEC --> NAT
    SEC --> VPN
    SEC --> CERTS

    SVC --> DNS
    SVC --> DHCP
    SVC --> MONITOR
    SVC --> WEB

This hierarchical structure provides:

  • Logical Organization: Related configuration grouped by functional domain
  • Maintainability: Easier to locate and modify specific configuration types
  • Extensibility: New features can be added to appropriate domains
  • Validation: Domain-specific validation rules improve data integrity
  • API Evolution: JSON tags enable better REST API integration
Analysis Capabilities

opnFocus provides comprehensive analysis of your OPNsense configurations:

  • Configuration Validation: Ensures all required fields are present and valid
  • Dead Rule Detection: Identifies unreachable firewall rules that come after "block all" rules
  • Unused Interface Analysis: Finds enabled interfaces not used in rules or services
  • Security Analysis: Detects insecure protocols, default SNMP community strings, and overly permissive rules
  • Performance Analysis: Identifies disabled hardware offloading and excessive rule counts
  • Compliance Checking: Validates against security and operational best practices

Development

This project follows comprehensive development standards and uses modern Go tooling:

# Development workflow using Just
just test      # Run tests
just lint      # Run linters
just check     # Run all pre-commit checks
just ci-check  # Run comprehensive CI checks
just dev       # Run in development mode
just docs      # Serve documentation locally
v1.0 Development Status
  • Core Infrastructure: Complete with proper error handling and logging
  • XML Processing: Full parsing and validation capabilities
  • Multi-Format Export: Markdown, JSON, and YAML conversion
  • Terminal Display: Rich output with theme support
  • Configuration Management: YAML files, environment variables, and CLI flags
  • Quality Assurance: Comprehensive testing and linting with GitHub Actions CI/CD
  • Documentation: Complete user and developer guides

Contributing

We welcome contributions! This project follows strict coding standards and development practices.

Before contributing:

  1. Read our development standards
  2. Check existing issues and pull requests
  3. Follow our Git workflow and commit message standards

Development process:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/your-feature
  3. Follow our coding standards (see DEVELOPMENT_STANDARDS.md)
  4. Write tests and ensure >80% coverage: just test
  5. Run all checks: just ci-check
  6. Commit using Conventional Commits
  7. Submit a pull request

Quality standards:

  • All code must pass golangci-lint
  • Tests required for new functionality
  • Documentation updates for user-facing changes
  • Follow Go best practices and project conventions

Documentation

Security

This tool is designed with security as a first-class concern:

  • No external dependencies - Operates completely offline
  • No telemetry - No data collection or external communication
  • Secure by default - Follows security best practices
  • Input validation - All inputs are validated and sanitized

For security issues, please see our security policy.

License

This project is licensed under the Apache License - see the LICENSE file for details.

Acknowledgements

Support

Roadmap

v1.1 - Advanced Analysis & Audit Reports
  • Security-focused audit and compliance reporting
  • Red team recon reports (attack surfaces, WAN exposure)
  • Blue team defensive reports (findings, recommendations)
  • Plugin-based compliance architecture
  • STIG, SANS, CIS compliance checking
v1.2 - Performance & Enterprise Features
  • Production-ready enterprise deployment
  • Concurrent processing for multiple files
  • Performance optimization and benchmarking
  • Advanced plugin ecosystem
  • Batch processing capabilities

Built with ❤️ for network operators everywhere.

Documentation

Overview

Package main is the entry point for the opnFocus CLI tool.

Source Files

View all Source files

Directories

Path Synopsis
Package cmd provides the command-line interface for opnFocus.
 Package cmd provides the command-line interface for opnFocus.
Package internal provides utility functions for walking and processing node structures.
 Package internal provides utility functions for walking and processing node structures.
audit
Package audit provides security audit functionality for OPNsense configurations against industry-standard compliance frameworks through a plugin-based architecture.
 Package audit provides security audit functionality for OPNsense configurations against industry-standard compliance frameworks through a plugin-based architecture.
config
Package config provides application configuration management.
 Package config provides application configuration management.
constants
Package constants defines shared constants used across the application.
 Package constants defines shared constants used across the application.
converter
Package converter provides functionality to convert OPNsense configurations to various formats.
 Package converter provides functionality to convert OPNsense configurations to various formats.
display
Package display provides functions for styled terminal output.
 Package display provides functions for styled terminal output.
export
Package export provides functionality to export data to files.
 Package export provides functionality to export data to files.
log
Package log provides centralized logging functionality for the opnFocus application.
 Package log provides centralized logging functionality for the opnFocus application.
markdown
Package markdown provides advanced formatting and content enrichment for markdown generation.
 Package markdown provides advanced formatting and content enrichment for markdown generation.
model
Package model defines the data structures for OPNsense configurations.
 Package model defines the data structures for OPNsense configurations.
parser
Package parser provides error types and utilities for parsing OPNsense configuration files.
 Package parser provides error types and utilities for parsing OPNsense configuration files.
plugin
Package plugin provides error definitions and interfaces for compliance plugins.
 Package plugin provides error definitions and interfaces for compliance plugins.
plugins/firewall
Package firewall provides a compliance plugin for firewall-specific security checks.
 Package firewall provides a compliance plugin for firewall-specific security checks.
plugins/sans
Package sans provides a compliance plugin for SANS security controls.
 Package sans provides a compliance plugin for SANS security controls.
plugins/stig
Package stig provides a compliance plugin for STIG security controls.
 Package stig provides a compliance plugin for STIG security controls.
processor
Package processor provides interfaces and types for processing OPNsense configurations.
 Package processor provides interfaces and types for processing OPNsense configurations.
validator
Package validator provides demo validation functionality for OPNsense configurations.
 Package validator provides demo validation functionality for OPNsense configurations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.