Opnsense

---
name: opnsense
description: "Expert coverage of OPNsense across all versions: HardenedBSD security, MVC/API-first architecture, Suricata v8 inline IPS, FRRouting dynamic routing, Unbound DNS with DNSSEC, Zenarmor DPI, plugin ecosystem, WireGuard, CARP HA, and REST API automation. Use for \"OPNsense\", \"HardenedBSD\", \"OPNsense API\", \"Suricata v8\", \"FRR\", \"Zenarmor\", \"Deciso\", \"OPNsense plugin\", \"os-frr\", \"hostwatch\". Do NOT use for cross-vendor comparison, platform selection, or category-wide architecture -- use the `firewall` skill."
license: MIT
---

# OPNsense

This skill covers OPNsense across all supported versions (24.x through 26.1). Areas of expertise include:

- HardenedBSD base OS with SafeStack, ASLR, PIE, CFI, W^X enforcement
- MVC/API-first architecture (PHP/Phalcon, REST API, JSON, structured XML config)
- Suricata v8 inline IPS with FreeBSD divert sockets
- Unbound DNS resolver with DNSSEC, DoT/DoH, blocklists
- FRRouting (FRR) for BGP, OSPF, BFD dynamic routing
- Zenarmor (Sensei) DPI for L7 application identification
- CARP high availability with pfsync state synchronization
- WireGuard kernel-space VPN
- Plugin ecosystem (os-acme-client, os-haproxy, os-nginx, os-freeradius, etc.)
- Full REST API automation with API key authentication

## How to Approach Tasks

1. **Classify** the request:
   - **Troubleshooting** -- Use diagnostics, logs, Suricata alerts, live capture
   - **Policy design** -- Apply MVC-based firewall rules (top-down, first-match on pf)
   - **Architecture** -- Load `references/architecture.md` for HardenedBSD, MVC/API, Suricata, FRR, plugins
   - **API automation** -- REST API with key/secret authentication, JSON format
   - **Dynamic routing** -- FRR plugin for BGP, OSPF, BFD

2. **Identify version** -- Determine OPNsense version (26.1 "Witty Woodpecker" is current). Version matters: Suricata v8 inline requires 26.1+, full firewall MVC/API requires 26.1+.

3. **Load context** -- Read the reference file for deep knowledge.

4. **Analyze** -- Apply OPNsense-specific reasoning. OPNsense is API-first and differs significantly from pfSense in architecture despite shared FreeBSD heritage.

5. **Recommend** -- Provide guidance with GUI paths, API endpoints, and CLI commands.

6. **Verify** -- Suggest validation via API queries, Suricata EVE logs, `pfctl` commands, Unbound diagnostics.

## Core Architecture: HardenedBSD + MVC/API

### HardenedBSD Base
OPNsense uses HardenedBSD (security-hardened FreeBSD fork):

- **SafeStack** -- Compiler-based protection against stack-based control-flow attacks
- **W^X enforcement** -- Memory regions cannot be simultaneously writable and executable
- **ASLR** -- Stronger address space layout randomization than stock FreeBSD
- **PIE** -- All system binaries compiled as position-independent executables
- **CFI (Control Flow Integrity)** -- Forward-edge CFI on key binaries
- **RELRO** -- ELF hardening (relocation read-only)
- Security patches tracked independently; often faster than upstream FreeBSD

### MVC/API Architecture
OPNsense's distinguishing characteristic:

- **Backend** -- PHP 8.x MVC framework with Phalcon
- **Configuration** -- Structured XML (`/conf/config.xml`)
- **REST API** -- Nearly every configuration domain exposed as API endpoints
- **Authentication** -- API key + API secret (HMAC); per-user key generation
- **Format** -- JSON request/response; RESTful HTTP methods

**API Coverage (26.1)**: Firewall rules, NAT, aliases, interfaces, routing, VPN (IPsec, OpenVPN, WireGuard), DHCP, DNS (Unbound), IDS/IPS (Suricata), certificates, users, High Availability.

## Firewall Rules

### MVC-Based Rules (26.1)
- Automation rules promoted to new MVC-based GUI
- Full API management of all firewall rules
- Rules evaluated on ingress interface; top-down, first-match (pf engine)
- Stateful by default; return traffic auto-permitted
- **Rule associations removed** (26.1) -- Legacy associated rule links replaced by independent editable rules

### Rule Components
- Source/destination: IP, network, alias, FQDN
- Service: port, port range, alias
- Interface assignment
- Direction: in/out
- Protocol matching
- Schedule support
- Gateway override for policy-based routing

### NAT
- **Destination NAT** -- Renamed from "Port Forwarding" in 26.1 for accuracy
- **Outbound NAT** -- Automatic, Hybrid, Manual modes (same as pf-based systems)
- **1:1 NAT** -- Bidirectional static mapping
- All NAT fully API-manageable in 26.1

## Suricata v8 Inline IPS

OPNsense integrates Suricata v8 as the primary IDS/IPS engine:

### Inline Mode (divert)
- OPNsense 26.1 uses FreeBSD `divert` sockets for true inline operation
- Suricata can drop AND modify packets (not just alert or drop)
- Significantly more efficient than prior NFQUEUE approach
- Per-interface assignment; multiple instances supported

### IDS Mode
- Promiscuous capture; alerts only, no blocking
- Lower performance impact; useful for initial deployment and tuning

### Rule Sources
- Emerging Threats Open/Pro
- OISF Suricata rules
- abuse.ch feeds (malware, botnet, SSL blacklist)
- Custom rules

### EVE JSON Logging
- Structured log output for SIEM integration
- Supports ELK Stack, Graylog, Splunk via syslog
- Flow and file extraction from HTTP/FTP/SMTP

## Unbound DNS

Default DNS resolver with advanced features:

- **DNSSEC validation** -- Enabled by default
- **DNS-over-TLS (DoT)** and **DNS-over-HTTPS (DoH)** for upstream queries
- **Blocklists** -- Category-based DNS blocking; 26.1 adds source selection from GUI
- **Host Overrides** -- Local DNS records for internal hosts
- **Domain Overrides** -- Forward specific domains to internal DNS (split-DNS)
- **DNS64** -- IPv6 transition; synthesize AAAA records for IPv4-only services

## FRRouting (FRR) Plugin

Dynamic routing protocol suite:

- **BGP** -- eBGP and iBGP; route maps, prefix lists, community manipulation
- **OSPF / OSPFv3** -- Internal dynamic routing; area design, redistribution
- **BFD** -- Bidirectional Forwarding Detection for fast failure detection
- **RIP** -- Legacy support
- **EVPN/VXLAN** -- Advanced datacenter routing via FRR bgpd
- Configuration via OPNsense GUI, vtysh CLI, or FRR plugin API endpoints
- Use cases: SD-WAN, multi-site, ISP connectivity, datacenter fabrics

## Zenarmor (Sensei) DPI

Commercial OPNsense plugin for advanced deep packet inspection:

- L7 application identification (1000+ applications) beyond Suricata capabilities
- Web filtering with cloud-based categorization
- Per-user, per-application bandwidth and policy reports
- Threat intelligence feeds (malware, botnet, C2 blocking)
- Free tier available; Pro tier for advanced features
- Complements Suricata (IDS/IPS signatures) with application-layer visibility

## WireGuard

- Native kernel module (HardenedBSD)
- GUI and API managed
- Site-to-site and road warrior configurations
- Kernel-space: significantly faster than userspace implementations
- Multi-peer, IPv4/IPv6 dual-stack
- Killswitch and routing integration for full-tunnel setups

## Host Discovery (hostwatch)

- Passive network traffic monitoring; builds device inventory automatically
- Discovers: MAC address, IP, hostname (reverse DNS), first/last seen
- Enabled by default in 26.1
- Populates Device List in GUI
- Complements DHCP lease tables with visibility into static-IP devices
- Per-interface; can trigger alerts on new unknown hosts

## CARP High Availability

Same CARP/pfsync mechanism as pfSense (shared FreeBSD heritage):

- **CARP VIPs** -- Shared IPs between active and standby nodes
- **pfsync** -- State table synchronization over dedicated interface
- **Config Sync** -- XMLRPC-based configuration replication
- **Active/Passive** -- Standard HA model
- Design: dedicated sync interface, 3 IPs per interface (node1, node2, VIP)

## Plugin Ecosystem

| Plugin | Function |
|---|---|
| os-acme-client | Let's Encrypt certificate automation |
| os-frr | FRRouting (BGP, OSPF, BFD) |
| os-haproxy | HAProxy load balancer |
| os-nginx | Nginx reverse proxy / WAF |
| os-freeradius | FreeRADIUS 802.1X / RADIUS |
| os-wazuh-agent | Wazuh SIEM agent |
| os-zerotier | ZeroTier overlay network |
| os-telegraf | Metrics to InfluxDB |
| os-netdata | Real-time system monitoring |
| os-git-backup | Config backup to Git |
| os-mdnsrepeater | mDNS across VLANs |
| os-tayga | IPv6 NAT64 |
| os-tinc | Overlay VPN mesh |
| os-clamav | ClamAV antivirus |
| os-cicap | ICAP server |

## REST API

### Authentication
API key + API secret generated per user in System > Access > Users.

### Example Calls
```bash
# List firewall aliases
curl -u "$KEY:$SECRET" https://fw.example.com/api/firewall/alias/searchItem

# Add a firewall rule
curl -X POST -u "$KEY:$SECRET" \
  -H "Content-Type: application/json" \
  -d '{"rule":{"type":"pass","interface":"lan","protocol":"tcp","source":{"net":"10.0.0.0/8"},"destination":{"net":"any"},"destination_port":"443"}}' \
  https://fw.example.com/api/firewall/filter/addRule

# Apply pending changes
curl -X POST -u "$KEY:$SECRET" \
  https://fw.example.com/api/firewall/filter/apply

# Suricata status
curl -u "$KEY:$SECRET" https://fw.example.com/api/ids/service/status
```

### API Design
- RESTful: GET (read), POST (create/action), PUT (update), DELETE (remove)
- JSON response format
- Versioned and documented
- Nearly complete coverage of all configuration domains

## Diagnostics

```bash
# pf rules
pfctl -sr                   # Show active rules
pfctl -ss                   # Show state table
pfctl -si                   # Show pf statistics

# Suricata
suricatasc -c "iface-stat"  # Suricata interface stats
cat /var/log/suricata/eve.json | jq  # EVE JSON log

# Unbound
unbound-control stats_noreset  # DNS resolver statistics
unbound-control dump_cache     # DNS cache dump

# System
top -SH                     # Process CPU/memory
netstat -rn                 # Routing table
ifconfig -a                 # Interface status
```

## Common Pitfalls

1. **API key permissions** -- API keys inherit the user's group permissions. Ensure the user has appropriate privilege set for the API operations needed.

2. **Suricata inline vs IDS mode** -- Inline (divert) mode blocks traffic matching drop rules. If Suricata causes connectivity issues, switch to IDS mode for tuning, then re-enable inline.

3. **FRR and firewall interaction** -- FRR-learned routes are added to the kernel routing table but firewall rules still evaluate on pf. Ensure rules permit traffic for dynamically learned routes.

4. **Plugin version compatibility** -- Plugins are version-tied. After major OPNsense upgrade, verify all plugins are compatible and updated.

5. **Unbound DNSSEC failures** -- DNSSEC validation can break resolution for misconfigured domains. Add problem domains to DNSSEC exclusion list rather than disabling DNSSEC globally.

6. **CARP without dedicated sync** -- Same as pfSense: pfsync over production interfaces risks state corruption. Use dedicated link.

7. **Zenarmor licensing** -- Free tier has limited features. Pro license required for advanced web filtering categories and full reporting.

8. **Config.xml direct editing** -- OPNsense stores all config in XML. Direct editing is possible but risky; use the API instead. Always back up before manual XML changes.

## Reference Files

Load these when you need deep knowledge:

- `references/architecture.md` -- HardenedBSD, MVC/API internals, Suricata v8, FRR, plugins, Zenarmor. Read for "how does X work" questions.