diff

opnDossier diff¶

Compare two OPNsense configuration files.

Synopsis¶

The 'diff' command compares two OPNsense config.xml files and shows meaningful configuration changes in a content-aware, security-focused way.

Unlike a raw XML text diff, this command understands OPNsense semantics: - Firewall rules are matched by UUID and compared structurally - Interfaces are compared by name with field-level change tracking - Static DHCP reservations are tracked by MAC address - Changes are scored by a pattern-based engine (high/medium/low)

OUTPUT FORMATS (--format/-f): terminal - Color-coded terminal output with ±/~ markers (default) markdown - Markdown formatted output for documentation json - JSON structured output for automation html - Self-contained HTML report

DISPLAY MODES (--mode/-m): unified - Standard diff view (default) side-by-side - Two-column comparison (terminal format only)

SECTION FILTERING (--section/-s): Implemented: system, firewall, nat, interfaces, vlans, dhcp, users, routing Placeholders (reject with a helpful error): dns, vpn, certificates

ANALYSIS OPTIONS: --security Show only security-relevant changes --normalize Normalize displayed values (whitespace, IPs, ports) --detect-order Detect rule reordering without content changes

SECURITY IMPACT SCORING: HIGH - Permissive rules (any-any), risky configurations MEDIUM - User changes, NAT modifications, protocol downgrades LOW - Minor modifications with limited security relevance

RELATED: audit - Compliance check on a single config (no comparison) convert - Render a single config to markdown/JSON/YAML

opnDossier diff <old-config.xml> <new-config.xml> [flags]

Examples¶

  # Compare two configs with terminal output (default)
  opnDossier diff old-config.xml new-config.xml

  # Generate a markdown report
  opnDossier diff old-config.xml new-config.xml -f markdown -o changes.md

  # Compare only firewall rules
  opnDossier diff old-config.xml new-config.xml --section firewall

  # Show only security-relevant changes
  opnDossier diff old-config.xml new-config.xml --security

  # Generate JSON for automation
  opnDossier diff old-config.xml new-config.xml -f json | jq '.changes[]'

  # Generate a self-contained HTML report
  opnDossier diff old-config.xml new-config.xml -f html -o report.html

  # Side-by-side terminal comparison
  opnDossier diff old-config.xml new-config.xml -m side-by-side

  # Normalize values and detect reordering
  opnDossier diff old-config.xml new-config.xml --normalize --detect-order

Options¶

  -o, --output string     Output file path (default: print to console)
  -f, --format string     Output format (terminal, markdown, json, html) (default "terminal")
  -m, --mode string       Display mode (unified, side-by-side) (default "unified")
  -s, --section strings   Sections to compare (default: all)
      --security          Show only security-relevant changes
      --normalize         Normalize displayed values (whitespace, IPs, ports)
      --detect-order      Detect rule reordering without content changes
  -h, --help              help for diff

Options inherited from parent commands¶

      --color string         Color output mode (auto, always, never) (default "auto")
      --config string        Configuration file path (default: $HOME/.opnDossier.yaml)
      --debug                Enable debug-level logging (all messages, for troubleshooting)
      --device-type string   Force device type (supported: opnsense, pfsense). Bypasses auto-detection.
      --minimal              Minimal output mode (suppresses progress and verbose messages)
      --no-progress          Disable progress indicators
  -q, --quiet                Suppress all output except errors and critical messages
      --timestamps           Include timestamps in log output
  -v, --verbose              Enable info-level logging (warnings, errors, and informational messages)