opnDossier - OPNsense Configuration Processor

Overview

opnDossier is a command-line tool for network operators and security professionals working with OPNsense firewalls. Transform complex XML configuration files into clear, readable documentation and identify security issues, misconfigurations, and optimization opportunities.

Built for offline operation in secure environments - no external dependencies, no telemetry, complete airgapped support.

What It Does

• Security Analysis - Automatically detect vulnerabilities, insecure protocols, weak configurations
• Dead Rule Detection - Find unreachable firewall rules and unused interfaces
• Configuration Validation - Comprehensive checks for misconfigurations and best-practice issues
• Multi-Format Export - Convert to markdown documentation, JSON, or YAML for integration
• Offline Operation - Works completely offline, perfect for airgapped networks

Quick Start

Installation

Download pre-built binaries for Linux, macOS, or Windows from releases, or install from source:

go install github.com/EvilBit-Labs/opnDossier@latest

Basic Usage

# Analyze your config and display in terminal
opnDossier display config.xml

# Generate security report
opnDossier convert config.xml -o security-report.md

# Export to JSON for automation
opnDossier convert -f json config.xml -o output.json

Analysis & Security Features

opnDossier automatically analyzes your OPNsense configuration to identify security issues, misconfigurations, and optimization opportunities.

Security Vulnerability Detection

Identifies common security issues in your firewall configuration:

• Insecure Protocols - Detects HTTP admin interfaces, Telnet, unencrypted SNMP
• Weak Configurations - Finds default community strings, overly permissive rules
• Certificate Issues - Identifies expired certificates, weak key sizes
• Credential Exposure - Detects plaintext passwords or weak authentication

Example output:

SECURITY FINDINGS:
- [HIGH] Admin interface accessible via HTTP (port 80)
- [HIGH] SNMP using default community string 'public'
- [MEDIUM] Firewall rule allows ANY to ANY on port 22
- [MEDIUM] VPN certificate expires in 14 days

Dead Rule Detection

Automatically identifies firewall rules that will never be reached:

• Rules positioned after "block all" rules
• Duplicate rules with identical criteria
• Rules referencing deleted interfaces or aliases

Example output:

DEAD RULES DETECTED:
- Rule #15: Allow SSH from LAN - unreachable (blocked by rule #12)
- Rule #23: Allow HTTPS from DMZ - references deleted interface 'dmz0'
- Rule #31: Block RDP - duplicate of rule #28

Configuration Validation

Comprehensive checks for structural and logical issues:

• Required Fields - Validates hostname, domain, network interfaces
• Data Types - Ensures IP addresses, subnets, ports are valid
• Cross-Field Validation - Checks relationships between configuration elements
• Network Topology - Validates gateway assignments, routing tables, VLAN configurations

Example validation report:

VALIDATION ERRORS:
- opnsense.interfaces.wan.ipaddr: IP address '300.300.300.300' is invalid
- opnsense.system.hostname: hostname is required
- opnsense.firewall.rules: gateway 'WAN_GW' referenced but not defined

Unused Resource Detection

Finds enabled resources not actively used:

• Interfaces enabled but not referenced in rules or services
• Aliases defined but never used in firewall rules
• VPN tunnels configured but disabled
• Services running without corresponding firewall rules

Compliance Checking

Built-in validation against security and operational best practices (planned v2.1). Tracking: #174.

• STIG compliance checks (planned v2.1)
• Industry-standard security baselines (planned v2.1)
• SANS security guidelines (planned v2.1)
• Custom compliance profiles (planned v2.1)

Features

Analysis & Reporting

• Security vulnerability detection - Identify insecure protocols, weak configurations, credential exposure
• Dead rule detection - Find unreachable firewall rules and duplicate rules
• Unused resource analysis - Detect unused interfaces, aliases, and services
• Configuration validation - Comprehensive structural and logical validation
• Compliance checking (planned v2.1) - Industry-standard security baselines and best practices

Output & Export

• Multi-format export - Generate markdown documentation, JSON, or YAML output
• Terminal display - Rich terminal output with syntax highlighting and theme support
• File export - Save processed configurations with overwrite protection
• Template-based reports - Customizable markdown templates (legacy, deprecated v3.0)
• International character support - UTF-8, US-ASCII, ISO-8859-1, and Windows-1252 input encodings

Performance & Architecture

• Streaming processing - Memory-efficient handling of large configuration files
• Fast & lightweight - Built with Go for performance and reliability
• Offline operation - Works completely offline, perfect for airgapped environments
• Cross-platform - Native binaries for Linux, macOS, and Windows

Security & Privacy

• No external dependencies - Operates completely offline
• No telemetry - Zero data collection or external communication
• Secure by design - Input validation, sanitization, and SBOM generation throughout
• Vulnerability scanning - Automated dependency scanning and security checks in CI/CD

Installation

Pre-built Binaries (Recommended)

Download the latest release for your platform:

• Linux (amd64, arm64)
• macOS (Intel, Apple Silicon)
• Windows (amd64)

Extract and run:

tar -xzf opnDossier-*.tar.gz
./opnDossier --help

Install via Go

Prerequisites: Go 1.21 or later

go install github.com/EvilBit-Labs/opnDossier@latest

Build from Source

git clone https://github.com/EvilBit-Labs/opnDossier.git
cd opnDossier
go build -o opnDossier main.go

For development builds with additional tooling, see CONTRIBUTING.md.

Usage Examples

Security Analysis

# Generate comprehensive security report
opnDossier convert config.xml -o security-report.md

# Display configuration with security findings in terminal
opnDossier display config.xml

# Export findings to JSON for automation/integration
opnDossier convert -f json config.xml -o findings.json

Configuration Documentation

# Convert OPNsense config to markdown documentation
opnDossier convert config.xml -o firewall-docs.md

# Generate YAML for configuration management tools
opnDossier convert -f yaml config.xml -o config.yaml

# Display in terminal with custom wrap width
opnDossier display --wrap 100 config.xml

Validation

# Validate configuration file
opnDossier validate config.xml

# Validate and convert in one step
opnDossier convert --validate config.xml -o report.md

Advanced Options

# Include system tunables in report
opnDossier convert config.xml -o comprehensive.md --include-tunables

# Verbose output for troubleshooting
opnDossier --verbose convert config.xml

# Quiet mode - only show errors
opnDossier --quiet convert config.xml -o output.md

Configuration

opnDossier can be configured via command-line flags, environment variables, or a configuration file.

Configuration Options

Setting	CLI Flag	Environment Variable	Config File	Description
Verbose logging	--verbose	OPNDOSSIER_VERBOSE	verbose: true	Enable debug/verbose output
Quiet mode	--quiet	OPNDOSSIER_QUIET	quiet: true	Suppress all non-error output
Input file	(positional)	OPNDOSSIER_INPUT_FILE	input_file: path	Default input configuration file
Output file	-o, --output	OPNDOSSIER_OUTPUT_FILE	output_file: path	Default output file path

For a complete list of all configuration options, see the Configuration Reference.

Configuration File Example

Create ~/.opnDossier.yaml:

# Logging
verbose: false
quiet: false

# File paths
input_file: /path/to/default/config.xml
output_file: ./output.md

Usage Examples

# Using CLI flags
opnDossier --verbose convert config.xml

# Using environment variables
export OPNDOSSIER_VERBOSE=true
opnDossier convert config.xml

# Using config file (automatically loaded from ~/.opnDossier.yaml)
opnDossier convert config.xml

Output Formats

opnDossier supports multiple output formats for different use cases:

• Markdown - Human-readable documentation with formatted tables and sections
• JSON - Machine-readable format for automation and integration
• YAML - Configuration management and structured data export
• Terminal Display - Rich syntax-highlighted output with theme support

Specify format with -f or --format flag:

opnDossier convert -f json config.xml -o output.json
opnDossier convert -f yaml config.xml -o output.yaml
opnDossier convert -f markdown config.xml -o output.md  # default

Documentation

• User Guide - Installation, usage, and configuration
• Security Documentation - Vulnerability scanning and security features
• API Reference - Detailed API documentation
• Examples - Real-world usage examples

For developers:

• Contributing Guide - How to contribute to the project
• Architecture Documentation - System design and architecture

Support

• Issues - GitHub Issues
• Discussions - GitHub Discussions
• Documentation - Full Documentation
• Contributing - Contributing Guide

Troubleshooting

• If you see garbled characters, confirm the XML declaration encoding matches the file's actual encoding.
• Supported input encodings include UTF-8, US-ASCII, ISO-8859-1, and Windows-1252; convert legacy files to UTF-8 if needed.

Security

opnDossier 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 design - Input validation, sanitization, and SBOM generation
• Automated scanning - Daily vulnerability scans and dependency audits in CI/CD

For security vulnerabilities, please see our security policy.

License

Apache License 2.0 - see LICENSE file for details.

Acknowledgements

• Inspired by TKCERT/pfFocus for pfSense configurations
• Built with Charm libraries for terminal UI

---

Built for network operators and security professionals.