OPNsense Central

A self-hosted, read-only central dashboard for viewing OPNsense firewall configuration data across multiple firewalls.

OPNsense Central is designed to look and feel familiar to OPNsense administrators while remaining a separate, read-only dashboard. It does not run or embed the upstream OPNsense PHP/Volt web interface.

Read-only guarantee

Firewall detail pages use OPNsense as a live data source by calling:

GET /api/core/backup/download/this

The returned backup XML is parsed in memory for the current request. Opening a firewall detail page does not create a snapshot unless snapshot storage has been explicitly enabled for sync workflows.

This app does not implement restore, reboot, halt, save, apply, reconfigure, or any other firewall write-back operation. Local UI actions such as adding, editing, or removing a firewall only change this dashboard's own inventory database.

The backup endpoint behavior was checked against upstream OPNsense BackupController::downloadAction, which serves backup XML from the local backup provider.

Features

• Firewall inventory with name, base URL, API key/secret, TLS verification, tags, and location.
• Encrypted-at-rest API secrets using Fernet.
• Live, non-persistent firewall detail view backed by the current OPNsense backup XML.
• OPNsense-style read-only configuration interface with sidebar menu groups.
• Collapsible sidebar navigation with only one expanded group at a time; all groups can also be collapsed.
• Full major OPNsense menu/submenu tree represented in the sidebar, with unimplemented items clearly marked.
• Parsed summaries for system settings, interfaces, VLANs, gateways, routes, aliases, firewall rules, NAT, DHCP, DNS, VPN, certificates, users, and groups.
• Read-only System > Firmware: Status page using upstream OPNsense firmware API endpoints.
• Redacted UI display for sensitive fields.
• Optional manual and scheduled snapshot history when STORE_SNAPSHOTS=true.
• Duplicate snapshot avoidance by SHA-256 checksum.
• Snapshot history and redacted XML diff view when snapshots are enabled.
• Cross-firewall search across parsed snapshots.
• Basic drift indicators: disabled rules, duplicate aliases, and expired certificates when dates are parseable.
• Demo mode with sample XML.

Current UI model

The firewall detail view is an OPNsense-inspired, read-only renderer. Sidebar items tagged Live are backed by parsed data from the current firewall backup XML. Items tagged Partial, Optional, Disabled, or Not implemented are visible placeholders so the complete menu tree is present before every page is fully implemented.

The implementation is intentionally progressive: new menu pages should be wired with read-only live data over time, preferably using documented OPNsense API endpoints where available and the backup XML when it is the safest complete source.

System > Firmware: Status is implemented with read-only GET calls to:

GET /api/core/firmware/info
GET /api/core/firmware/status

OPNsense firmware write/action endpoints such as update, upgrade, reboot, install, remove, lock, unlock, and audit/check POST actions are intentionally not called by this dashboard.

Upstream OPNsense reference workflow

Before changing behavior that mirrors OPNsense menus, APIs, configuration sections, labels, or page structure, check the upstream project:

https://github.com/opnsense/core

Use upstream as the reference for current menu organization, controller names, API endpoints, and configuration model structure. If upstream behavior has changed, prefer matching the current upstream read-only structure rather than hardcoding older assumptions.

This project should not copy large upstream UI files into the dashboard unless that is deliberately reviewed for license, maintenance, and compatibility impact. Prefer small, documented references and original dashboard code.

Security notes

OPNsense configuration backups are sensitive. They can include secrets, password hashes, private keys, VPN material, and internal network topology.

Redacted fields in UI

The parser redacts field names containing:

• password, passwd, hash
• apikey, api_key, secret, token
• private-key, privatekey, privkey
• pre-shared-key, psk
• caref, crt, prv

Raw XML is stored only when snapshot storage is enabled and a sync is run. If you enable snapshots, protect the database volume like a backup vault.

Secrets at rest

API secrets are encrypted with Fernet. Set a stable ENCRYPTION_KEY or a strong APP_SECRET_KEY. If both are lost or changed, stored API secrets cannot be decrypted and must be re-entered.

Deployment guidance

• Use a strong dashboard password.
• Put the app behind an HTTPS reverse proxy such as Caddy, Traefik, or Nginx.
• Set SECURE_COOKIES=true when served over HTTPS.
• Restrict network access to trusted administrators.
• Back up the /data volume securely if you store inventory or snapshots.
• Do not expose this dashboard publicly without additional controls.

Quick start

cp .env.example .env
# edit .env and change ADMIN_PASSWORD, APP_SECRET_KEY, and optionally ENCRYPTION_KEY
docker compose up --build

Open http://localhost:8082.

Default .env.example may enable DEMO_MODE=true, which seeds one sample firewall and snapshot for local exploration.

Environment variables

Variable	Default	Purpose
ADMIN_USERNAME	admin	Dashboard login username.
ADMIN_PASSWORD	changeme	Dashboard password if ADMIN_PASSWORD_HASH is unset.
ADMIN_PASSWORD_HASH	unset	SHA-256 hash of the dashboard password.
APP_SECRET_KEY	insecure fallback	Signs sessions and derives encryption key if ENCRYPTION_KEY is unset.
ENCRYPTION_KEY	unset	Optional Fernet key for API secret encryption.
SECURE_COOKIES	false	Set true behind HTTPS.
STORE_SNAPSHOTS	false	Enable persistent snapshot history and sync jobs. Live firewall detail views do not require this.
SYNC_INTERVAL_MINUTES	60	Periodic sync interval when STORE_SNAPSHOTS=true; 0 disables scheduler.
DEMO_MODE	false	Seed sample data on startup.
DATABASE_URL	sqlite:////data/opnsense-central.db	SQLite database path.

Generate a Fernet key:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Generate a SHA-256 password hash:

python -c "import hashlib; print(hashlib.sha256('your-password'.encode()).hexdigest())"

Local development

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
DEMO_MODE=true DATABASE_URL=sqlite:///./dev.db uvicorn app.main:app --reload

Run tests:

PYTHONPATH=. pytest

Validate templates or JavaScript after UI edits:

python -c "from jinja2 import Environment, FileSystemLoader; env=Environment(loader=FileSystemLoader('app/templates')); env.get_template('detail.html'); env.get_template('overview.html'); print('templates OK')"
node --check app/static/app.js

Live configuration view

Opening a firewall detail page calls the OPNsense backup endpoint directly, parses the returned XML in memory, and renders the configuration without storing a new snapshot. GET /api/firewalls/{firewall_id}/parsed uses the same live, non-persistent behavior.

Snapshots are still available for history and diff workflows when STORE_SNAPSHOTS=true and a manual or scheduled sync is run.

REST endpoints

Authenticated endpoints include:

• GET /api/firewalls
• POST /api/firewalls
• PUT /api/firewalls/{firewall_id}
• DELETE /api/firewalls/{firewall_id}
• POST /api/firewalls/{firewall_id}/sync
• GET /api/firewalls/{firewall_id}/snapshots
• GET /api/firewalls/{firewall_id}/parsed live, non-persistent parsed config
• GET /api/firewalls/{firewall_id}/diff?a=<snapshot_id>&b=<snapshot_id>
• GET /api/search?q=<term>

Inventory create/update/delete operations only affect the local dashboard database. They never write to OPNsense. Snapshot sync endpoints are disabled unless STORE_SNAPSHOTS=true; the firewall detail page and parsed API can still read live configuration directly from OPNsense without storing it.

Limitations

• This is not the upstream OPNsense web GUI and does not execute OPNsense UI code.
• SQLite is used for the first version. PostgreSQL can be added later if needed.
• Parser coverage is defensive and broad, but OPNsense plugins vary; unknown sections may need parser extensions.
• Dashboard auth is intentionally simple session auth for a self-hosted MVP.
• Logs, diagnostics, package/plugin management pages, and many plugin pages still need dedicated read-only API integrations.

License

This project is licensed under the BSD 2-Clause License. See LICENSE.

OPNsense itself is distributed under a BSD-style permissive license in opnsense/core. OPNsense Central currently references upstream OPNsense API behavior, configuration concepts, menu organization, and terminology, but does not bundle upstream OPNsense source files or execute the upstream PHP/Volt web interface.

The upstream OPNsense copyright notice, license conditions, and disclaimer are recorded in THIRD_PARTY_NOTICES.md. If code is copied or adapted from opnsense/core in the future, keep those notices with the copied/adapted code and update THIRD_PARTY_NOTICES.md so source and binary redistributions keep the required attribution and disclaimer.

OPNsense Central is an independent dashboard and is not affiliated with, endorsed by, or bundled with OPNsense or Deciso B.V. OPNsense names, logos, and trademarks belong to their respective owners.