Data Model & Integration#

This guide explains how to work with opnDossier's data model for custom integrations, scripting, and automation.

Overview#

opnDossier parses OPNsense and pfSense configuration files (config.xml) and converts them to structured data formats:

Markdown - Human-readable documentation
JSON - Machine-readable, ideal for scripting with jq
YAML - Configuration-friendly, works with yq

The JSON/YAML export uses the CommonDevice model -- a platform-agnostic representation that normalizes XML quirks (presence-based booleans, pointer types, map-keyed collections) into clean types suitable for scripting and integration. Both OPNsense and pfSense configs are normalized to identical CommonDevice structures, enabling unified scripting regardless of device type. opnDossier auto-detects the device type from the XML root element (<opnsense> or <pfsense>).

Quick Start#

Export Configuration#

# Export to JSON for scripting
opndossier convert config.xml --format json -o config.json

# Export to YAML for configuration management
opndossier convert config.xml --format yaml -o config.yaml

# Export to Markdown for documentation
opndossier convert config.xml --format markdown -o config.md

Query Data with jq#

# Get hostname
jq '.system.hostname' config.json

# List all interface names
jq '[.interfaces[].name]' config.json

# Get all enabled firewall rules
jq '.firewallRules[] | select(.disabled | not)' config.json

# Count rules by interface
jq '[.firewallRules[] | .interfaces[]] | group_by(.) | map({interface: .[0], count: length})' config.json

Query Data with yq#

# Get system domain
yq '.system.domain' config.yaml

# List DHCP scopes
yq '[.dhcp[].interface]' config.yaml

Data Model Structure#

The CommonDevice model organizes configuration into logical sections:

CommonDevice (root)
├── system # Hostname, domain, SSH, WebGUI, firmware
├── interfaces[] # Network interface configurations (flat array)
├── vlans[] # VLAN configurations
├── firewallRules[] # Normalized firewall filter rules
├── nat # NAT rules (outboundRules, inboundRules)
├── dhcp[] # DHCP server scopes
├── dns # DNS resolver (unbound, dnsMasq)
├── vpn # VPN (openVpn, wireGuard, ipsec)
├── routing # Gateways, gateway groups, static routes
├── users[] # System user accounts
├── groups[] # System groups
├── certificates[] # TLS/SSL certificates
├── cas[] # Certificate authorities
└── ... # Additional services (syslog, ids, snmp, etc.)

Documentation#

Model Reference - Complete field reference for the CommonDevice export model and internal XML schemas
JSON Export Examples - Common jq queries
YAML Processing Examples - Working with yq

Common Use Cases#

Security Auditing#

# Find rules allowing any source
jq '.firewallRules[] | select(.source.address == "any") | {
  interfaces, description, destination
}' config.json

# List NAT port forwards
jq '.nat.inboundRules[]' config.json

# Check SSH configuration
jq '.system.ssh' config.json

Network Documentation#

# Get all VLANs
jq '.vlans[] | {tag, vlanIf, description}' config.json

# List gateways
jq '.routing.gateways[] | {name, interface, address}' config.json

# Get interface IP addresses
jq '.interfaces[] | {name, ipAddress, subnet}' config.json

Configuration Comparison#

Use the built-in diff command for content-aware, security-scored comparison:

# Compare two configs with security impact scoring
opndossier diff old-config.xml new-config.xml

# Generate JSON diff for automation
opndossier diff old-config.xml new-config.xml -f json

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

Integration Examples#

Ansible#

  - name: Extract OPNsense configuration
    command: opndossier convert {{ config_file }} --format json
    register: opnsense_config

  - name: Parse configuration
    set_fact:
      firewall_rules: '{{ (opnsense_config.stdout | from_json).firewallRules }}'

Python#

import json
import subprocess

result = subprocess.run(
    ["opndossier", "convert", "config.xml", "--format", "json"],
    capture_output=True,
    text=True,
)
config = json.loads(result.stdout)
print(f"Hostname: {config['system']['hostname']}")
print(f"Interfaces: {[iface['name'] for iface in config['interfaces']]}")

Shell Scripting#

#!/bin/bash
CONFIG=$(opndossier convert config.xml --format json)

HOSTNAME=$(echo "$CONFIG" | jq -r '.system.hostname')
RULE_COUNT=$(echo "$CONFIG" | jq '.firewallRules | length')

echo "Firewall: $HOSTNAME"
echo "Rules: $RULE_COUNT"

Programmatic Generation#

opnDossier uses programmatic markdown generation rather than text templates. If you need custom report formats, you can:

Use JSON/YAML exports - Process with your preferred tools
Extend the generator - Add custom report types in Go
Post-process output - Transform markdown with pandoc or similar

See the Architecture Documentation for details on the generator system.

Regenerating Documentation#

The model reference is auto-generated from Go types:

just generate-docs

This ensures documentation stays in sync with the codebase.