CLI Command Reference#

This reference provides technical details about opnDossier's command-line interface, flags, and configuration options. For practical usage examples and workflows, see the Getting Started Guide and Common Workflows.

Quick Links#

• Commands Overview - Complete command list with links to detailed guides
• audit - Run security audit and compliance checks on configurations
• Getting Started - Tutorial for processing your first configuration
• Common Workflows - Practical recipes for documentation, auditing, comparison, and sanitization
• Configuration Guide - Customizing opnDossier behavior

Overview#

opnDossier is a command-line tool for processing, analyzing, and documenting OPNsense and pfSense firewall configuration files. Built on the Cobra framework with Viper for configuration management, opnDossier provides a comprehensive suite of 15 commands that transform XML-based configurations into multiple output formats while offering advanced security analysis and sanitization capabilities.

The tool addresses the challenge of understanding and managing complex firewall configurations by providing semantic-aware parsing that goes beyond simple XML processing. Rather than treating configurations as generic data structures, opnDossier understands platform-specific elements like firewall rules, NAT policies, interfaces, and VPN configurations, enabling intelligent comparison, validation, and documentation generation.

opnDossier's command architecture is organized into three logical categories: primary commands for configuration processing (convert, audit, display, validate, diff, sanitize), configuration management commands for the tool itself (config init/show/validate), and utility commands for developer productivity (completion, man, version). This structure supports workflows ranging from quick configuration previews to comprehensive security audits, with flexible output options including markdown, JSON, YAML, HTML, and plain text formats.

Command Architecture#

The 15 Cobra commands are organized into three functional categories:

Primary Commands:

• convert (alias: conv) - Parse and convert OPNsense and pfSense configurations to multiple formats
• audit - Run security audit and compliance checks on configurations
• display - Render configuration in terminal with syntax highlighting
• validate - Validate firewall configuration structure and content
• diff - Compare configurations with semantic analysis
• sanitize - Redact sensitive data with referential integrity

Configuration Management Commands:

• config - Parent command for opnDossier configuration management
  • config init - Initialize configuration file with defaults
  • config show - Display merged effective configuration
  • config validate - Validate opnDossier configuration file

Utility Commands:

• help - Root command with enhanced help system
• version - Display version and build information
• completion - Generate shell completion scripts (bash/zsh/fish/PowerShell)
• man - Generate Unix manual pages

For detailed documentation on each command, see the Commands Overview page.

Command Quick Reference#

This section provides quick syntax and flag reference for each command. For comprehensive documentation including examples, use cases, and detailed explanations, refer to the individual command guides linked above.

convert Command#

Parse and convert OPNsense and pfSense configuration files to multiple output formats. Use convert when you need a human-readable report or a machine-readable export — not when you need compliance analysis or structural validation. See convert command guide for comprehensive documentation.

Syntax: opndossier convert [flags] <config.xml>

Key Flags:

• --output, -o <path> - Output file path (default: stdout)
• --format, -f <format> - Output format: markdown/md, json, yaml/yml, text/txt, html/htm (default: markdown)
• --force - Overwrite existing files
• --section <sections> - Comma-separated sections to include
• --wrap <width> - Text wrap width: -1=auto, 0=off, 40-200=recommended
• --no-wrap - Disable text wrapping
• --comprehensive - Generate comprehensive reports
• --include-tunables - Include all system tunables in report output (markdown, text, HTML only; JSON/YAML always include all tunables)
• --redact - Redact sensitive fields (SNMP community strings, certificate/CA private keys, passwords, pre-shared keys, API keys, user password hashes)

Audit Flags:

• --audit-mode <mode> - Audit mode: blue (defensive), red (offensive)
• --audit-plugins <plugins> - Compliance plugins: stig, sans, firewall (comma-separated)
• --plugin-dir <path> - Directory containing dynamic .so compliance plugins (fail-fast if explicitly set and missing)

Conversion Warnings: Non-fatal issues detected during conversion (such as empty firewall rule fields, incomplete NAT rules, or missing gateway information) are logged as warnings via structured logging. Warnings are suppressed when --quiet is used.

System Tunables Behavior: By default, only security-related tunables are included in markdown, text, and HTML output. Use --include-tunables to include all system tunables. JSON and YAML exports always include all tunables regardless of the flag setting.

conv Command#

Alias for the convert command. See convert command guide for full documentation.

Syntax: opndossier conv [flags] <config.xml>

All convert flags apply.

audit Command#

Run security audit and compliance checks on firewall configurations. See audit command guide for comprehensive documentation.

Syntax: opndossier audit [flags] <config.xml> [config2.xml ...]

Audit Flags:

• --mode <mode> - Audit mode: blue, red (default: blue)
• --plugins <plugins> - Compliance plugins: stig, sans, firewall (comma-separated, blue mode only)
• --blackhat - Enable blackhat commentary for red team reports
• --plugin-dir <path> - Directory containing dynamic .so compliance plugins. Plugins run with full process privileges; signatures are not verified. See Dynamic Plugin Security.
• --failures-only - Show only failing controls in blue mode compliance tables (blue mode + markdown format only)

Output Flags:

• --output, -o <path> - Output file path (default: stdout; not allowed with multiple files)
• --format, -f <format> - Output format: markdown/md, json, yaml/yml, text/txt, html/htm (default: markdown)
• --force - Overwrite existing files
• --section <sections> - Comma-separated sections to include
• --wrap <width> - Text wrap width: -1=auto, 0=off, 40-200=recommended
• --no-wrap - Disable text wrapping
• --comprehensive - Generate comprehensive reports
• --include-tunables - Include all system tunables in report output (markdown, text, HTML only; JSON/YAML always include all tunables)
• --redact - Redact sensitive fields (SNMP community strings, certificate/CA private keys, passwords, pre-shared keys, API keys, user password hashes)

Audit Modes:

• blue - Defensive audit with compliance findings and recommendations (default)
• red - Attacker-focused recon highlighting attack surfaces (experimental — analysis methods are placeholder stubs)

Compliance Plugins: (blue mode only)

• stig - Security Technical Implementation Guide checks
• sans - SANS Firewall Baseline checks
• firewall - Firewall Configuration Analysis

When no plugins are specified in blue mode, all available plugins are run. The --plugins flag is rejected for red mode.

Failures-Only Filter:

The --failures-only flag filters blue mode compliance tables to show only non-compliant controls, hiding passing controls from the output. This flag has strict requirements:

• Only works with --mode blue (rejected with red mode or other non-blue modes)
• Only works with --format markdown (rejected with json, yaml, text, html formats)
• When all controls pass, displays "All controls compliant" message instead of an empty table

This restriction ensures JSON/YAML consumers receive complete control status data for client-side filtering without information loss.

Multi-File Behavior: When auditing multiple files, --output cannot be used. Each report is auto-named as <input>-audit.<ext>. Directory paths are encoded in the filename to prevent collisions (e.g., prod/site-a/config.xml produces prod_site-a_config-audit.md).

Terminal Rendering: Markdown output to stdout is rendered through glamour for styled display. File output and non-markdown formats are written raw.

Dynamic Plugin Security: A stderr warning is emitted whenever --plugin-dir is supplied, informing users that plugins run with full process privileges and signatures are not verified. See the audit command guide for the complete trust model and security considerations.

display Command#

Display configuration as styled markdown in terminal with Glamour rendering for a quick, interactive read of a configuration without producing any files. See display command guide for comprehensive documentation.

Syntax: opndossier display [flags] <config.xml>

Key Flags:

• --theme <theme> - Rendering theme: auto, dark, light, none (default: auto)
• --section <sections> - Sections to include
• --wrap <width> - Text wrap width
• --no-wrap - Disable wrapping
• --comprehensive - Comprehensive reports
• --include-tunables - Include all system tunables in report output (markdown, text, HTML only; JSON/YAML always include all tunables)
• --redact - Redact sensitive fields (SNMP community strings, certificate/CA private keys, passwords, pre-shared keys, API keys, user password hashes)

Theme Options:

• auto - Auto-detect terminal background
• light - Light theme (dark text on white)
• dark - Dark theme (light text on dark)
• none - No styling (raw output for piping)

Conversion Warnings: Non-fatal issues detected during conversion are logged as warnings. Warnings are suppressed when --quiet is used.

System Tunables Behavior: By default, only security-related tunables are included in markdown, text, and HTML output. Use --include-tunables to include all system tunables. JSON and YAML exports always include all tunables regardless of the flag setting.

validate Command#

Validate firewall configuration file structure and content. See validate command guide for comprehensive documentation.

Syntax: opndossier validate [flags] <config.xml>

Key Flags:

• --json-output - Output validation errors in JSON format (for machine consumption)

Conversion Warnings: Non-fatal conversion issues (such as incomplete configuration elements) are logged as warnings. Warnings are suppressed when --quiet is used.

diff Command#

Compare two firewall configurations with semantic-aware analysis that understands OPNsense semantics rather than treating them as raw XML. See diff command guide for comprehensive documentation.

Syntax: opndossier diff <old-config.xml> <new-config.xml>

Output Flags:

• -o, --output <path> - Output file path (default: console)
• -f, --format <format> - Output format: terminal, markdown, json, html (default: terminal)
• -m, --mode <mode> - Display mode: unified, side-by-side (default: unified)

Filter Flags:

• -s, --section <sections> - Sections to compare (default: all)
  • Implemented sections: system, firewall, nat, interfaces, vlans, dhcp, users, routing
  • Placeholder sections (reject with error): dns, vpn, certificates
• --security - Show only security-relevant changes

Analysis Flags:

• --normalize - Normalize displayed values (whitespace, IPs, ports)
• --detect-order - Detect rule reordering

Semantic Understanding:

• Firewall rules matched by UUID
• Interfaces compared by name
• Static DHCP reservations tracked by MAC address
• Security-impacting changes scored as high/medium/low

Note: Side-by-side mode only supported with terminal format.

Conversion Warnings: Non-fatal issues detected when parsing both configuration files are logged as warnings. Warnings are not affected by --quiet as they are logged during parsing.

sanitize Command#

Redact sensitive information from firewall configuration files. See sanitize command guide for comprehensive documentation.

Syntax: opndossier sanitize [flags] <config.xml>

Flags:

• -m, --mode <mode> - Sanitization mode: aggressive, moderate, minimal (default: moderate)
• -o, --output <path> - Output file path (default: console)
• --mapping <path> - Output path for mapping file (JSON)
• --force - Force overwrite

Sanitization Modes:

Aggressive (for public sharing):

• Passwords, keys, certificates
• All IPs (public and private)
• MACs, emails, hostnames, usernames, domains
• OTP seeds, WireGuard endpoints, tunnels, subnets

Moderate (for internal sharing, default):

• Passwords, keys, authserver values, public IPs
• MACs, emails
• Preserves: private IPs (RFC 1918), hostnames outside system/authserver (for topology analysis)

Minimal (for trusted environments):

• Passwords, secrets, API keys, PSKs / Private keys, SSH keys / Sensitive system/authserver LDAP values
• Preserves: certificates, most network information (excluding authserver hosts)

Referential integrity maintained: Same original value → same redacted value throughout document.

Mapping Categories:

When --mapping <path> is specified, opnDossier generates a JSON mapping file that records all replacements performed during sanitization. The mapping file is organized by category for easy lookup and includes a dedicated authserver section for system/authserver LDAP field mappings:

{
  "mode": "moderate",
  "timestamp": "2026-04-02T10:30:00Z",
  "mappings": {
    "ip_addresses": {
      "192.168.1.1": "192.168.1.1",
      "203.0.113.5": "198.51.100.1"
    },
    "hostnames": {
      "firewall.corp.example.com": "host-001.example.com"
    },
    "emails": {
      "admin@example.com": "user-001@example.com"
    },
    "authserver": {
      "name": {
        "corp-ldap": "authserver-001"
      },
      "host": {
        "ldap.corp.example.com": "ldap-001.example.invalid"
      },
      "ldap_port": {
        "636": "55001"
      },
      "ldap_bindpw": {
        "supersecret123": "BindPw-001-NotReal!"
      }
    }
  }
}

The authserver category groups field-specific mappings for sensitive system/authserver LDAP values such as name, host, ldap_port, and ldap_bindpw. Each field has its own sub-mapping for consistent pseudonymization across all sanitization modes.

config Commands#

Parent command for managing opnDossier configuration. See config command guide for comprehensive documentation.

config init:
Generate template configuration file.

Syntax: opndossier config init [flags]

Flags: --output <path>, --force

Creates default config at ~/.opnDossier.yaml.

config show:
Display current effective configuration.

Syntax: opndossier config show [flags]

Flags: --json - Output in JSON format

Shows merged result from all configuration sources.

config validate:
Validate opnDossier configuration file.

Syntax: opndossier config validate [flags]

Checks syntax errors, invalid values, constraint violations.

completion Command#

Generate shell completion scripts.

Syntax: opndossier completion [bash|zsh|fish|powershell]

Uses Cobra's built-in completion generation:

• GenBashCompletion() for bash
• GenZshCompletion() for zsh
• GenFishCompletion() for fish (with descriptions)
• GenPowerShellCompletion() for PowerShell

Dynamic Completions:

• --format flag completions are automatically sourced from converter.DefaultRegistry.ValidFormats()
• --device-type flag completions are automatically sourced from parser.DefaultRegistry().List() (currently: "opnsense", "pfsense")

This ensures completions stay synchronized with supported formats and device types as the registries evolve.

Completion script printed to stdout for redirection to shell config files.

man Command#

Generate manual pages for opnDossier and all commands.

Syntax: opndossier man [output-directory]

No command-specific flags. Accepts optional positional argument for output directory.

Uses Cobra's doc.GenManTree() to generate man pages for root and all subcommands.

Default output directory: ./man/

Man pages use section 1 (user commands) with .1 file extension.

Directory created with 0755 permissions if it doesn't exist.

version Command#

Display version information.

Syntax: opndossier --version

Automatically provided by Fang CLI enhancement. Uses lightweight initialization for faster startup.

Global Flags#

Global flags available to all commands:

Mutually Exclusive:

• --verbose and --quiet cannot be used together
• --wrap and --no-wrap cannot be used together

Device Type Flag:

The --device-type flag allows manual override of auto-detection:

• Device type validation is dynamic, using parser.DefaultRegistry().Get() to check validity
• Shell completion suggestions are derived from parser.DefaultRegistry().List() instead of being hardcoded
• Error messages dynamically list available device types from the registry
• Supported device types: "opnsense" and "pfsense"
• The registry architecture enables future device type additions without CLI changes

Configuration System#

Precedence Order#

Configuration loaded with precedence (highest to lowest):

1. CLI Flags - Command-line arguments
2. Environment Variables - OPNDOSSIER_* prefixed
3. Configuration File - ~/.opnDossier.yaml (YAML format)
4. Default Values - Built-in defaults

Configuration Options#

Basic Settings:

Nested Display Settings (display:):

display:
  width: -1 # OPNDOSSIER_DISPLAY_WIDTH
  pager: false # OPNDOSSIER_DISPLAY_PAGER
  syntax_highlighting: true # OPNDOSSIER_DISPLAY_SYNTAX_HIGHLIGHTING

Nested Export Settings (export:):

export:
  format: "markdown" # OPNDOSSIER_EXPORT_FORMAT
  directory: "" # OPNDOSSIER_EXPORT_DIRECTORY
  template: "" # OPNDOSSIER_EXPORT_TEMPLATE
  backup: false # OPNDOSSIER_EXPORT_BACKUP

Nested Logging Settings (logging:):

logging:
  level: "info" # OPNDOSSIER_LOGGING_LEVEL (debug, info, warn, error)
  format: "text" # OPNDOSSIER_LOGGING_FORMAT (text, json)

Nested Validation Settings (validation:):

validation:
  strict: false # OPNDOSSIER_VALIDATION_STRICT
  schema_validation: false # OPNDOSSIER_VALIDATION_SCHEMA_VALIDATION

Configuration File Location#

• Default: ~/.opnDossier.yaml
• Custom: Use --config /path/to/config.yaml

Output Format Options#

opnDossier supports five output formats, managed by the converter.DefaultRegistry as the single source of truth for format metadata, validation, and generation dispatch.

Supported Formats:

• markdown (alias: md) - Default format with syntax highlighting
• json - Structured data format for automation
• yaml (alias: yml) - Human-readable structured format
• text (alias: txt) - Plain text output (markdown with formatting stripped)
• html (alias: htm) - Self-contained HTML format

Format Registry Architecture:

The FormatRegistry centralizes format handling by mapping canonical format names and aliases to FormatHandler implementations. Each handler encapsulates:

• File extension determination (e.g., .md, .json)
• Alias resolution (e.g., md → markdown, yml → yaml)
• Generation dispatch to the appropriate output method

Format validation delegates to converter.DefaultRegistry.Get(), which returns ErrUnsupportedFormat for unknown formats. Aliases are automatically resolved via DefaultRegistry.Canonical() before processing, ensuring consistent behavior across all commands and code paths.

Shell Completion Integration:

Format completions for the --format flag are automatically derived from converter.DefaultRegistry.ValidFormats(), ensuring shell completions stay synchronized with supported formats without manual updates.

Error Messages:

Invalid formats produce errors listing all supported format names and aliases: "unsupported format: <format>, must be one of: html, htm, json, markdown, md, text, txt, yaml, yml"

Text Wrapping#

Wrap width options:

• -1 - Auto-detect terminal width (default)
• 0 - Disable wrapping
• 40-200 - Recommended range (outside triggers warning)
• Positive integers - Specific column width

UTF-8 and ANSI handling: Uses rune-based counting via utf8.RuneCountInString for multi-byte characters and preserves ANSI escape sequences.

Data Model Architecture#

CommonDevice model serves as platform-agnostic device representation:

type CommonDevice struct {
    DeviceType DeviceType // Device platform identifier
    Version string // Configuration version
    System System // System settings
    Interfaces []Interface // Network interfaces
    FirewallRules []FirewallRule // Firewall policies
    NAT NATConfig // NAT configuration
    VPN VPN // VPN settings
    Routing Routing // Routing configuration
    DNS DNSConfig // DNS settings
    DHCP []DHCPScope // DHCP configurations
    Statistics *Statistics // Calculated statistics
    SecurityAssessment *SecurityAssessment // Security analysis
}

Device Type Detection and Parser Registry#

Device type detection is handled by Factory.CreateDevice() using the DeviceParserRegistry:

Registry-Based Parser Lookup:

• Factory uses DeviceParserRegistry for all parser lookups via registry.Get()
• Auto-detection matches the XML root element against registered parsers
• Manual override with --device-type validates against the registry
• Error messages dynamically list all supported device types from registry.List()

Auto-detection Process:

• Parses XML root element from the configuration file
• Looks up corresponding parser in the registry
• Falls back to error if no parser is registered for that root element

Manual Override:

• --device-type flag bypasses auto-detection
• Validates device type exists in registry before parsing
• Useful when XML structure doesn't clearly indicate device type

Validation:

• Optional parameter enables schema validation during parsing
• Return signature: (*CommonDevice, []ConversionWarning, error) - returns device model, non-fatal conversion warnings, and fatal errors

Parser Registration Requirement:

Critical: The CLI requires blank imports in cmd/root.go to ensure parser registration occurs:

import (
    _ "github.com/EvilBit-Labs/opnDossier/pkg/parser/opnsense" // self-registers OPNsense parser via init()
    _ "github.com/EvilBit-Labs/opnDossier/pkg/parser/pfsense" // self-registers pfSense parser via init()
)

Without these imports, the parsers' init() functions never run, leaving the registry empty and causing all parsing operations to fail. This pattern mirrors Go's database/sql driver registration. See GOTCHAS.md section 7.1 for details.

Error Handling#

Error messages provide specific, actionable information:

XML Parse Error:

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

Validation Error:

validation error at opnsense.system.hostname: hostname is required

Aggregated 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 valid (0-32)

Conversion Warnings#

Conversion warnings are non-fatal issues detected during the transformation of firewall configuration XML into the CommonDevice model. Unlike errors (which halt processing), warnings indicate incomplete or potentially problematic configuration elements that can still be processed.

Warning Output#

Warnings are logged via structured logging with the following fields:

• field - Dot-path to the problematic field (e.g., FirewallRules[0].Type)
• value - The problematic value encountered (often empty for missing data)
• message - Human-readable description of the issue
• severity - Importance level: high, medium, or low

Common Warning Scenarios#

Firewall Rules:

• Empty rule type
• Missing source or destination addresses
• No interface assigned

NAT Configuration:

• Inbound NAT rules without internal IP addresses
• Outbound NAT rules without interface assignments

Routing:

• Gateways missing addresses or names

Users & Certificates:

• Users without names or UIDs
• Certificate configuration issues

High Availability:

• Incomplete HA configuration elements

Quiet Mode Behavior#

Warnings respect the --quiet global flag and are suppressed when quiet mode is enabled, consistent with other informational output. This allows scripts and automation to focus on fatal errors only.

Usage Examples#

These examples demonstrate common command usage patterns. For complete workflow examples and automation recipes, see the Common Workflows guide.

Basic Conversion#

# Convert config.xml to markdown
opndossier convert config.xml

# Convert to JSON with output file
opndossier convert --format json --output report.json config.xml

# Convert specific sections only
opndossier convert --section firewall,nat config.xml

Display in Terminal#

# Display with auto theme detection
opndossier display config.xml

# Force dark theme
opndossier display --theme dark config.xml

# Display without wrapping
opndossier display --no-wrap config.xml

Configuration Comparison#

# Basic diff
opndossier diff old-config.xml new-config.xml

# JSON output with security focus
opndossier diff --format json --security old.xml new.xml

# Side-by-side comparison
opndossier diff --mode side-by-side old.xml new.xml

Sanitization#

# Moderate sanitization (default)
opndossier sanitize config.xml

# Aggressive sanitization for public sharing
opndossier sanitize --mode aggressive --output public.xml config.xml

# Save mapping file for reverse lookup
opndossier sanitize --mapping mappings.json config.xml

Audit#

# Run a blue team audit with all compliance plugins (default)
opndossier audit config.xml

# Blue team defensive audit with STIG and SANS compliance
opndossier audit config.xml --plugins stig,sans

# Show only failing controls in blue mode
opndossier audit config.xml --failures-only

# Red team attack surface analysis with blackhat commentary
opndossier audit config.xml --mode red --blackhat

# Export audit report as JSON
opndossier audit config.xml --format json -o audit-report.json

# Run audit on multiple files (auto-named output)
opndossier audit config1.xml config2.xml --mode blue

# Comprehensive audit with redaction for external sharing
opndossier audit config.xml --comprehensive --redact

Configuration Management#

# Initialize configuration file
opndossier config init

# View effective configuration
opndossier config show

# Validate configuration
opndossier config validate ~/.opnDossier.yaml

Shell Completion#

# Generate bash completion
opndossier completion bash > /etc/bash_completion.d/opndossier

# Generate zsh completion
opndossier completion zsh > ~/.zsh/completion/_opndossier

Man Pages#

# Generate man pages to default directory (./man/)
opndossier man

# Generate to custom directory
opndossier man /usr/local/share/man/man1

Best Practices#

1. Use configuration files for persistent settings across sessions
2. Use environment variables for deployment scenarios and CI/CD pipelines
3. Use CLI flags for one-off overrides and testing
4. Always validate with the validate command before processing
5. Check help text with --help for command-specific flag options
6. Use sanitize before sharing configuration files externally
7. Use validate --json-output in scripts for structured error handling
8. Use diff for auditing configuration changes over time

For practical workflow examples, see the Common Workflows guide.

Relevant Code Files#

Command Implementation Files (cmd/)#

Internal Support Packages#

Related Topics#

• Cobra Framework - Command-line interface framework for Go
• Viper Configuration - Configuration management library
• OPNsense - Open source firewall and routing platform
• Configuration Management - Best practices for managing application settings
• Security Auditing - Compliance checking and security assessment
• Data Sanitization - Techniques for protecting sensitive information