Skip to content
Open
Show file tree
Hide file tree
Changes from 20 commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
a616caa
fix(parser): read dnsmasq host and domain overrides as OPNsense write…
intigenesis Nov 13, 2026
6f06a24
fix(parser): report dnsmasq DHCP ranges and reservations as DHCP scopes
intigenesis Nov 13, 2026
c41e117
fix(audit): pass FIREWALL-058 when dnsmasq resolves with DNSSEC on
intigenesis Nov 13, 2026
f106dcd
fix(diff): key DHCP scopes by server and interface
intigenesis Nov 13, 2026
4be3650
fix(stig): count only enabled DHCP scopes for V-206690
intigenesis Nov 13, 2026
fbc8f15
docs: describe FIREWALL-058, FIREWALL-062 and V-206690 with dnsmasq
intigenesis Nov 13, 2026
274616d
fix(parser): drop dnsmasq placeholders and pool-less ranges from scopes
intigenesis Nov 13, 2026
41e5889
docs: leave the V-206690 summary line to the merge
intigenesis Nov 13, 2026
8b7918b
docs: document dnsmasq DHCP, overrides and DNSSEC reading
intigenesis Nov 13, 2026
bb446c1
docs: say V-206690 counts only enabled DHCP scopes
intigenesis Nov 13, 2026
edc8fc8
refactor(parser): list the dnsmasq model versions in one literal
intigenesis Nov 13, 2026
269bafd
docs: describe FIREWALL-063 as the count it reports
intigenesis Nov 13, 2026
2b790d0
fix(stig): count every ISC and Kea scope again for V-206690
intigenesis Nov 13, 2026
33e3603
fix(parser): keep ra-stateless dnsmasq entries as DHCP scopes
intigenesis Nov 13, 2026
12ab1a3
docs: move the dnsmasq V-206690 note to the XML field reference
intigenesis Nov 13, 2026
818096c
docs: say a dnsmasq scope, not a range, counts toward V-206690
intigenesis Nov 13, 2026
6f6d494
fix(parser): place dnsmasq Any ranges and IPv6 reservations by network
intigenesis Nov 14, 2026
8ac3a32
fix(diff): report a changed client id on a static reservation
intigenesis Nov 14, 2026
9695196
test(audit): fail FIREWALL-058 when dnsmasq is disabled
intigenesis Nov 14, 2026
a436271
docs: say opnDossier does not read pfSense dnsmasq DHCP
intigenesis Nov 14, 2026
80fed99
fix(diff): name DHCP scopes without an interface by their range start
intigenesis Nov 14, 2026
eeefe66
fix(parser): place dnsmasq reservations by every address and relayed …
intigenesis Nov 14, 2026
7bffcdb
fix(diff): pair DHCP scopes without an interface by subnet and content
intigenesis Nov 14, 2026
e9a887e
fix(parser): match dnsmasq IPv4 ranges on the network dnsmasq uses
intigenesis Nov 14, 2026
c519f1b
fix(diff): pair a DHCP scope with a unique identity only by that iden…
intigenesis Nov 14, 2026
20d689f
fix(parser): match each dnsmasq range on its own mask or prefix
intigenesis Nov 14, 2026
4547592
fix(diff): leave reservations out of similarity within a shared key
intigenesis Nov 14, 2026
5def2df
fix(parser): leave dnsmasq ranges on dynamic interfaces and short con…
intigenesis Nov 14, 2026
54d3728
fix(diff): count reservations at most 1 between scopes sharing a key
intigenesis Nov 14, 2026
1756ad1
fix(parser): match dnsmasq ranges on dynamic interfaces and IPv6 pref…
intigenesis Nov 14, 2026
9cf0bea
fix(diff): let any shared field outrank reservations within a shared key
intigenesis Nov 14, 2026
f01d969
fix(parser): treat masked dnsmasq ranges on dynamic interfaces as local
intigenesis Nov 14, 2026
128b9c7
test(parser): pin the reservation cap and the dnsmasq range tiers
intigenesis Nov 14, 2026
155aa3c
fix(parser): read a dnsmasq IPv6 host part by its value, not its spel…
intigenesis Nov 14, 2026
d928594
test(parser): pin the dnsmasq lines Codecov reported untested
intigenesis Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions GOTCHAS.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,7 @@ When an XML element appears multiple times (e.g., `<priv>a</priv><priv>b</priv>`
- **Known instance (fixed):** `<dnsserver>` repeats once per resolver in both `<system>` and each `<dhcpd><interface>` scope. `pfsense.System.DNSServers` was already `[]string`, but `DHCPInterface.Dnsserver` was a scalar on both vendors, so every DHCP scope silently reported only its last resolver — including in `testdata/pfsense/config-pfSense.xml`, which configures two on `lan`, `opt1` and `opt5`. This reached the JSON/YAML export. `common.DHCPScope` gained `DNSServers` (`dhcp[].dnsServers`, an array); the old scalar `DNSServer` is retained and deprecated per the public-API deprecation policy, and `SetDNSServers` keeps it mirroring the first entry so the two cannot drift. `TestParser_ConfigPfSense_DHCPScopesKeepEveryDNSServer` guards the parse, `TestDHCPScope_SetDNSServers` the invariant.
- **The two schemas drift apart, and the pfSense side is usually right.** `pkg/schema/pfsense` modelled `Group.Member`, `Group.Priv` and `User.Priv` as `[]string` while `pkg/schema/opnsense` had the first two as `string` and omitted the third entirely, so the same three-member group read as one member on OPNsense and three on pfSense. When you touch a repeated element in one schema, diff it against its sibling: an asymmetry is either a real vendor difference or a bug, and it is nearly always a bug.
- **Known instance (fixed): the parent path can be wrong too.** OPNsense stores port forwards as `<rule>` directly under `<nat>`, with the redirect address in `<target>`, at every release checked from 15.1 to 26.7. `Nat.Inbound` was bound as `xml:"inbound>rule"` and read `<internalip>`, a shape no release writes, so every OPNsense port forward was dropped: the report said none were configured, the red audit and FIREWALL-054 had nothing to check, and `diff` never saw one change (#877). The pfSense schema bound the right path all along, and its comments named the OPNsense shape as the difference. No OPNsense fixture had a port forward, and the converter tests built `schema.InboundRule` by hand, so nothing decoded through `<nat>`. `testdata/opnsense-port-forwards.xml` and `testdata/opnsense-legacy-port-forwards.xml` carry both generations of the rule body, and `TestInboundRule_BindsEveryFixtureElement` fails on an element the schema does not bind.
- **An MVC `ArrayField` has no container element.** The model writes each item as the field's own name, repeated directly under its parent: `<dnsmasq><hosts uuid="...">...</hosts><hosts uuid="...">...</hosts>`. The legacy pages wrote the same shape. `DNSMasq.Hosts` and `DomainOverrides` were bound as `hosts>host` and `domainoverrides>domainoverride`, so each host override decoded as one empty `{}` entry (the `<host>` text child matched the item binding) and no domain override was ever read. Read the model XML for `type="ArrayField"` before choosing a binding: the field name is the item tag. The same model also keeps dnsmasq's DHCP ranges and reservations, which reach `CommonDevice.DHCP` as scopes with `Source` `dnsmasq`; the 26.7.9 factory default serves LAN DHCP this way and has no `<dhcpd>`. Once the last entry is deleted the legacy pages leave a self-closing `<hosts/>` or `<domainoverrides/>`, which the four dnsmasq item types drop through `IsPlaceholder` (see 3.4); a uuid alone does not make an item real, since the model loader skips any item without child elements.
- **A slice is not automatically safe — check what element it is bound to.** `Sysctl []SysctlItem` with `xml:"sysctl"` tells `encoding/xml` that `<sysctl>` itself repeats. The vendor instead writes one `<sysctl>` container holding repeated `<item>` children, so every tunable in the file collapsed into a single entry with empty `Tunable` and `Value` — 287 tunables across the shipped fixtures reduced to one blank row per file, and a config with no tunables decoded identically to a config with two hundred. Either bind through the container (`xml:"sysctl>item"`) or give the slice its own `UnmarshalXML`, as `SysctlItems` does, when both the container and a legacy flat shape must decode. Watch for a scalar field that exists only to absorb the mis-parse: it is a sign the binding is wrong, not that the vendor writes a scalar there. `SysctlItem.Item` was exactly that, and was deleted once the binding was corrected — nothing could populate it any more, and leaving it would have kept the evidence of the bug in the public shape.
- **Writing an `UnmarshalXML`? Check whether its siblings pair one.** Every other custom container in `pkg/schema/opnsense` — `Dhcpd`, `Interfaces`, `InterfaceList` — defines `MarshalXML` alongside. `SysctlItems` shipped without one, so the encoder fell back to the default and emitted one `<sysctl>` element per tunable in the legacy flat shape instead of one container of `<item>` children. Nothing failed: the values round-tripped, because the unmarshaler accepts both shapes. The document simply stopped being what the vendor writes, and `pkg/parser/opnsense/roundtrip_test.go` does not touch sysctl, so nothing noticed. A one-directional custom codec is worth a second look on its own — but the cheaper signal is the neighbours, since an unpaired type in a package where every sibling pairs is a stronger smell than the asymmetry read cold. `Gateways` and `GatewayModelItem` are unpaired on purpose: their `UnmarshalXML` decodes what the default decoder would and adds only `Gateway.HasChildElement`, which is tagged `xml:"-"`, so the default encoder still writes the fields the vendor wrote. `TestGateway_HasChildElement_BothStores` marshals with the field set and cleared to keep it that way. It cannot keep an item whose only children are empty or unbound, such as `<name/>` or `<priority>`: the encoder omits them, the item reads back as a placeholder, and a model holding only such items falls back to `<gateways>` on the second read. An alias embedded to reuse the default decoding needs an exported name: encoding/xml takes an embedded struct's `XMLName` without offsetting its index, so it reads the embedded field itself and panics when that field is unexported.
- **The value parsed correctly and still never appeared?** That is a different failure with its own entry — see §3.6. Dumping the schema struct tells the two apart: a value missing from the dump was lost here, one present in the dump but absent from the export was lost at the converter. Reach for the sweep in §3.6 only after this one comes back clean, since a wrong binding hides a converter gap behind it.
Expand Down
10 changes: 5 additions & 5 deletions docs/compliance-standards.md
Original file line number Diff line number Diff line change
Expand Up @@ -248,11 +248,11 @@ The following controls are organized by security domain and represent the full p

##### Service Hardening

| Control ID | Title | Severity | Implementability | Description |
| ------------ | ------------------------------- | -------- | ---------------- | ------------------------------------------------------------------------- |
| FIREWALL-057 | UPnP/NAT-PMP Disabled | High | Partial | UPnP and NAT-PMP disabled (automatic port forwarding is a security risk) |
| FIREWALL-058 | DNSSEC Validation | Medium | Full | Unbound DNS resolver has DNSSEC validation enabled (`DNS.Unbound.DNSSEC`) |
| FIREWALL-059 | DNS Resolver Access Restriction | Medium | Partial | DNS resolver serves only internal networks, not WAN-facing |
| Control ID | Title | Severity | Implementability | Description |
| ------------ | ------------------------------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FIREWALL-057 | UPnP/NAT-PMP Disabled | High | Partial | UPnP and NAT-PMP disabled (automatic port forwarding is a security risk) |
| FIREWALL-058 | DNSSEC Validation | Medium | Full | The DNS resolver has DNSSEC validation enabled: Unbound when it is enabled (`DNS.Unbound.DNSSEC`), otherwise dnsmasq when it answers on port 53 (`DNS.DNSMasq.DNSSEC`) |
| FIREWALL-059 | DNS Resolver Access Restriction | Medium | Partial | DNS resolver serves only internal networks, not WAN-facing |

##### Change Management and Backup

Expand Down
11 changes: 7 additions & 4 deletions docs/data-model/examples/json-export.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,16 +180,19 @@ jq '.nat.inboundRules[] | {
### DHCP

```bash
# List DHCP scopes
# List DHCP scopes, with the server that serves each (isc, kea or dnsmasq)
jq '.dhcp[] | {
interface,
source,
enabled,
range
range,
rangeV6
}' config.json

# Get static DHCP mappings
jq '.dhcp[] | .staticMappings[]? | {
# Get static DHCP leases (a dnsmasq lease can carry a client id instead of a MAC)
jq '.dhcp[] | .staticLeases[]? | {
mac,
cid,
ipAddress,
hostname
}' config.json
Expand Down
9 changes: 5 additions & 4 deletions docs/data-model/examples/yaml-processing.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,11 +135,12 @@ yq '.firewallRules[] | select(.destination.port == "22")' config.yaml
# List DHCP interfaces
yq '[.dhcp[].interface]' config.yaml

# Get DHCP range for a specific interface
yq '.dhcp[] | select(.interface == "lan") | .range' config.yaml
# Get the DHCP range served on a specific interface. An upgraded box can keep a
# disabled ISC scope beside the dnsmasq one, so select the enabled scope.
yq '.dhcp[] | select(.interface == "lan" and .enabled) | .range' config.yaml

# List static mappings
yq '.dhcp[].staticMappings[]' config.yaml
# List static leases
yq '.dhcp[].staticLeases[]' config.yaml
```

### DNS
Expand Down
26 changes: 22 additions & 4 deletions docs/data-model/model-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -306,7 +306,7 @@ The `analysis.unusedObjects` array lists named objects defined in the config but

### DHCPScope

DHCP scopes are a flat array with one entry per interface.
DHCP scopes are a flat array with one entry per DHCP server and interface. A dnsmasq range that names no interface and lies in no interface's network gets an entry of its own with an empty `interface`. An interface can have an ISC and a dnsmasq scope at once, typically a disabled ISC scope left beside the dnsmasq one; `source` tells them apart.

| Field | Type | JSON Key | Description |
| -------------- | ------------------- | --------------------- | ------------------------------- |
Expand All @@ -319,6 +319,8 @@ DHCP scopes are a flat array with one entry per interface.
| `NTPServer` | `string` | `dhcp[].ntpServer` | NTP server for clients |
| `WINSServer` | `string` | `dhcp[].winsServer` | WINS server for clients |
| `StaticLeases` | `[]DHCPStaticLease` | `dhcp[].staticLeases` | Fixed MAC-to-IP mappings |
| `Source` | `DHCPSource` | `dhcp[].source` | `isc`, `kea` or `dnsmasq` |
| `RangeV6` | `*DHCPRange` | `dhcp[].rangeV6` | DHCPv6 range (dnsmasq only) |

### DHCPRange

Expand Down Expand Up @@ -346,9 +348,25 @@ DHCP scopes are a flat array with one entry per interface.

### DNS (dnsmasq)

| Field | Type | JSON Key | Description |
| --------- | ------ | --------------------- | ------------------------ |
| `Enabled` | `bool` | `dns.dnsMasq.enabled` | dnsmasq forwarder active |
The DHCP ranges dnsmasq serves are reported as `dhcp[]` scopes with `source` set to `dnsmasq`.

| Field | Type | JSON Key | Description |
| ----------------- | ------------------ | ----------------------------- | --------------------------------- |
| `Enabled` | `bool` | `dns.dnsMasq.enabled` | dnsmasq forwarder active |
| `DNSSEC` | `bool` | `dns.dnsMasq.dnssec` | DNSSEC validation enabled |
| `Port` | `string` | `dns.dnsMasq.port` | DNS port; empty is 53, `0` is off |
| `Hosts` | `[]DNSMasqHost` | `dns.dnsMasq.hosts` | Host overrides |
| `DomainOverrides` | `[]DomainOverride` | `dns.dnsMasq.domainOverrides` | Per-domain DNS servers |

### DomainOverride

| Field | Type | JSON Key | Description |
| ------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------ |
| `Domain` | `string` | `dns.dnsMasq.domainOverrides[].domain` | Domain forwarded |
| `IP` | `string` | `dns.dnsMasq.domainOverrides[].ip` | DNS server address; on a legacy config as written, `ip#port@srcip` |
| `Description` | `string` | `dns.dnsMasq.domainOverrides[].description` | Description |
| `Port` | `string` | `dns.dnsMasq.domainOverrides[].port` | DNS server port, when not 53 |
| `SourceIP` | `string` | `dns.dnsMasq.domainOverrides[].sourceIp` | Local address queries are sent from |

---

Expand Down
2 changes: 2 additions & 0 deletions docs/development/xml-structure-research.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,8 @@ Element existing = true, absent = false. Content is irrelevant.

**pfSense presence-based enable note:** pfSense correctly parses `Interface` and `DhcpdInterface` `<enable/>` elements as presence-based using BoolFlag types. The public API converts to string `"1"` for backward compatibility.

**OPNsense dnsmasq `<dnssec>` note:** The element changed reading when the Dnsmasq MVC model arrived in 25.1.2. The legacy page tested it with `isset()`, so any `<dnssec>` element turned DNSSEC on; the model's template turns it on only for the value `1`. `DNSMasq.Dnssec` is a `*string`, and the converter reads presence when `<dnsmasq>` has no `version` attribute and the value `1` when it has one.

### 1b. Value-Based Booleans

Element contains `1`, `yes`, or a specific value. Absent or empty = false.
Expand Down
18 changes: 9 additions & 9 deletions docs/firewall-security-controls-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -434,11 +434,11 @@ The following controls are planned for future releases, organized by security do

### Service Hardening

| Control ID | Title | Severity | Description |
| ------------ | ------------------------------- | -------- | ------------------------------------------------------------------- |
| FIREWALL-057 | UPnP/NAT-PMP Disabled | High | UPnP and NAT-PMP disabled (auto port forwarding is a security risk) |
| FIREWALL-058 | DNSSEC Validation | Medium | Unbound DNS resolver has DNSSEC validation enabled |
| FIREWALL-059 | DNS Resolver Access Restriction | Medium | DNS resolver serves only internal networks, not WAN-facing |
| Control ID | Title | Severity | Description |
| ------------ | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| FIREWALL-057 | UPnP/NAT-PMP Disabled | High | UPnP and NAT-PMP disabled (auto port forwarding is a security risk) |
| FIREWALL-058 | DNSSEC Validation | Medium | The DNS resolver has DNSSEC validation enabled: Unbound when it is enabled, otherwise dnsmasq when it answers on port 53 |
| FIREWALL-059 | DNS Resolver Access Restriction | Medium | DNS resolver serves only internal networks, not WAN-facing |

### Change Management

Expand All @@ -454,10 +454,10 @@ The following controls are planned for future releases, organized by security do

### Configuration Inventory

| Control ID | Title | Severity | Description |
| ------------ | ------------------------ | -------- | --------------------------------------------------------------------------------------------- |
| FIREWALL-062 | DHCP Scope Inventory | Info | Reports configured DHCP scopes, covering both ISC DHCP (legacy) and Kea DHCP4 (modern) scopes |
| FIREWALL-063 | Active Interface Summary | Info | Reports enabled interfaces and their types |
| Control ID | Title | Severity | Description |
| ------------ | ------------------------ | -------- | ---------------------------------------------------------------------------------------- |
| FIREWALL-062 | DHCP Scope Inventory | Info | Reports configured DHCP scopes, covering ISC DHCP (legacy), Kea DHCP4 and dnsmasq scopes |
| FIREWALL-063 | Active Interface Summary | Info | Reports how many interfaces are enabled |

**Note:** Configuration inventory controls use `Type: "inventory"` and are excluded from compliance evaluation. They are rendered in a separate "Configuration Notes" section of audit reports and do not affect pass/fail compliance status.

Expand Down
2 changes: 2 additions & 0 deletions docs/user-guide/device-support-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,13 +45,15 @@ If a pfSense feature area is listed as **Not yet supported**, opnDossier warns y
| Cron jobs | Supported | Supported |
| Trust settings | Supported | Not yet supported |
| Kea DHCP | Supported | Not yet supported |
| dnsmasq DHCP | Supported | Not supported |
| Revision history | Supported | Supported |
| Theme settings | Supported | Not yet supported |

**Legend:**

- **Supported** — opnDossier currently includes this area in parsing, reporting, and related analysis when it exists in the source configuration.
- **Not yet supported** — opnDossier does not currently include this area for that platform.
- **Not supported** -- opnDossier does not read this area for that platform and does not warn when it is present. pfSense's DNS Forwarder runs dnsmasq and its settings page offers no DHCP ranges, but its custom options (`<dnsmasq><custom_options>`, base64 encoded) are passed to dnsmasq as command-line options, so a `dhcp-range` there makes it serve DHCP. The pfSense parser reads neither the Forwarder's `<dnsmasq>` element nor those options, so DHCP served that way does not appear in a report.

## What this means in practice

Expand Down
Loading
Loading