opnDossier

command module
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Apr 3, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

README

opnDossier - OPNsense and pfSense Configuration Processor

OpenSSF Best Practices Go Version License codecov Documentation wakatime Go Report Card Mergify Status All Contributors

Overview

opnDossier is a command-line tool for network operators and security professionals working with OPNsense and pfSense 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
# Generate configuration documentation
opnDossier convert config.xml -o report.md

# Run security audit (blue mode is default)
opnDossier audit config.xml

# Display config in terminal
opnDossier display config.xml
Example Output
Markdown display output

Terminal screenshot showing opnDossier markdown output with system configuration and firewall rules

Convert to JSON for automation/integration

Screenshot of JSON export showing structured device data for automation and integration

Configuration diff

Screenshot of structured configuration diff showing added interfaces, changed DHCP ranges, and modified firewall rules

Audit findings example

Screenshot of audit compliance findings showing severity levels and remediation recommendations

Analysis & Security Features

opnDossier automatically analyzes your OPNsense or pfSense 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:

Screenshot of security findings with severity indicators and actionable recommendations

Dead Rule Detection

Automatically identifies firewall rules that will never be reached:

  • Rules positioned after "block all" rules on the same interface
  • Duplicate rules with identical criteria (type, protocol, source, destination)

Example output:

DEAD RULES DETECTED:
- Rule #15: Rules after position 12 on interface lan are unreachable due to preceding block-all rule
- Rule #31: Rule at position 31 is duplicate of rule at position 28 on interface wan
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:

Screenshot of configuration validation output showing detected issues and warnings

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.

  • Industry-standard security baselines
  • SANS security guidelines

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 - 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

Download the latest release for your platform:

Extract and run:

tar -xzf opnDossier-*.tar.gz
./opnDossier --help
Install via Go

Prerequisites: Go 1.26 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
# Run blue team defensive audit (default mode)
opnDossier audit config.xml

# Blue team audit with specific compliance plugins
opnDossier audit config.xml --plugins stig,sans

# Red team attack surface analysis
opnDossier audit config.xml --mode red

# Export audit findings to JSON for automation/integration
opnDossier audit -f json config.xml -o findings.json
Configuration Documentation
# Convert OPNsense or pfSense 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 before converting
opnDossier validate config.xml && opnDossier convert 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

GitHub Actions

opnDossier is available as a GitHub Action backed by its Docker image. Use it to audit or document OPNsense and pfSense configurations automatically on every commit, PR, or scheduled run.

Quick Start
name: Audit firewall configuration

on:
  push:
    paths:
      - config.xml
  schedule:
    - cron: 0 6 * * 1   # every Monday at 06:00 UTC

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Audit OPNsense config
        # No release tags exist yet — use @main until v1 is tagged
        uses: EvilBit-Labs/opnDossier@main
        with:
          command: audit
          config-file: config.xml
Inputs
Input Required Default Description
command No audit Sub-command: audit, convert, diff, display, sanitize, validate, or version
config-file Yes — Path to OPNsense or pfSense config.xml relative to the workspace root
format No — Output format for convert/audit: markdown, json, yaml, text, or html
output No — Path to write the output file, relative to the workspace root
args No — Additional arguments split on whitespace (quoted strings with spaces are not preserved)
version No latest Image tag to pull (e.g. v1.2.0); defaults to the latest release
Export findings to JSON
  - name: Export audit findings
  # No release tags exist yet — use @main until v1 is tagged
    uses: EvilBit-Labs/opnDossier@main
    with:
      command: audit
      config-file: firewall/config.xml
      format: json
      output: findings.json

  - name: Upload findings
    uses: actions/upload-artifact@v4
    with:
      name: audit-findings
      path: findings.json
Generate configuration documentation
  - name: Generate firewall documentation
  # No release tags exist yet — use @main until v1 is tagged
    uses: EvilBit-Labs/opnDossier@main
    with:
      command: convert
      config-file: config.xml
      format: markdown
      output: docs/firewall.md
Using the Docker image directly

The Docker image is published to the GitHub Container Registry alongside every release and can be used independently of the Action:

# Pull the latest release
docker pull ghcr.io/evilbit-labs/opndossier:latest

# Run an audit, mounting your config directory
# WORKDIR is /data, so use relative paths after the volume mount
docker run --rm \
  --volume "$(pwd):/data" \
  ghcr.io/evilbit-labs/opndossier:latest \
  audit config.xml

Documentation

For developers:

Support

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.

Contributors

See CONTRIBUTORS.md for the full list of contributors.

Acknowledgements

Built for network operators and security professionals.

Documentation

Overview

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

Source Files

View all Source files

Directories

Path Synopsis
Package cmd provides the command-line interface for opnDossier.
 Package cmd provides the command-line interface for opnDossier.
Package internal provides utility functions for walking and processing node structures.
 Package internal provides utility functions for walking and processing node structures.
analysis
Package analysis provides canonical types for security analysis findings and shared analysis functions (detection, statistics, rule comparison) used across the audit, compliance, converter, and processor packages.
 Package analysis provides canonical types for security analysis findings and shared analysis functions (detection, statistics, rule comparison) used across the audit, compliance, converter, and processor packages.
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.
cfgparser
Package cfgparser provides error types and utilities for parsing OPNsense configuration files.
 Package cfgparser provides error types and utilities for parsing OPNsense configuration files.
compliance
Package compliance provides error definitions and interfaces for compliance plugins.
 Package compliance provides error definitions and interfaces for compliance plugins.
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 device configurations to various formats.
 Package converter provides functionality to convert device configurations to various formats.
converter/builder
Package builder provides programmatic report building functionality for device configurations.
 Package builder provides programmatic report building functionality for device configurations.
converter/formatters
Package formatters provides utility functions for formatting data in markdown reports.
 Package formatters provides utility functions for formatting data in markdown reports.
diff
Package diff provides configuration comparison functionality for OPNsense configurations.
 Package diff provides configuration comparison functionality for OPNsense configurations.
diff/analyzers
Package analyzers provides semantic analysis utilities for diff comparisons.
 Package analyzers provides semantic analysis utilities for diff comparisons.
diff/formatters
Package formatters provides output formatting for diff results.
 Package formatters provides output formatting for diff results.
diff/security
Package security provides security impact scoring for configuration changes.
 Package security provides security impact scoring for configuration changes.
display
Package display provides functions for styled terminal output.
 Package display provides functions for styled terminal output.
docgen
Package docgen provides auto-generation of model documentation from Go types.
 Package docgen provides auto-generation of model documentation from Go types.
export
Package export provides functionality to export data to files.
 Package export provides functionality to export data to files.
logging
Package logging provides centralized logging functionality for the opnDossier application.
 Package logging provides centralized logging functionality for the opnDossier application.
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.
pool
Package pool provides memory pooling utilities for efficient buffer reuse.
 Package pool provides memory pooling utilities for efficient buffer reuse.
processor
Package processor provides interfaces and types for processing OPNsense configurations.
 Package processor provides interfaces and types for processing OPNsense configurations.
progress
Package progress provides progress indication for CLI operations.
 Package progress provides progress indication for CLI operations.
sanitizer
Package sanitizer provides functionality to redact sensitive information from OPNsense configuration files.
 Package sanitizer provides functionality to redact sensitive information from OPNsense configuration files.
validator
Package validator provides demo validation functionality for OPNsense configurations.
 Package validator provides demo validation functionality for OPNsense configurations.
pkg
model
Package model provides platform-agnostic domain structs for representing firewall device configurations.
 Package model provides platform-agnostic domain structs for representing firewall device configurations.
parser
Package parser provides the factory for creating device-specific parsers that transform vendor configuration files into the platform-agnostic CommonDevice model.
 Package parser provides the factory for creating device-specific parsers that transform vendor configuration files into the platform-agnostic CommonDevice model.
parser/opnsense
Package opnsense provides an OPNsense-specific parser and converter that transforms schema.OpnSenseDocument into the platform-agnostic CommonDevice.
 Package opnsense provides an OPNsense-specific parser and converter that transforms schema.OpnSenseDocument into the platform-agnostic CommonDevice.
parser/pfsense
Package pfsense provides a pfSense-specific parser and converter that transforms pfsense.Document into the platform-agnostic CommonDevice.
 Package pfsense provides a pfSense-specific parser and converter that transforms pfsense.Document into the platform-agnostic CommonDevice.
schema/opnsense
Package opnsense defines the data structures for OPNsense configurations.
 Package opnsense defines the data structures for OPNsense configurations.
schema/pfsense
Package pfsense defines the data structures for pfSense configurations.
 Package pfsense defines the data structures for pfSense 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.