← Back to Home
// Technical Architecture

PortGuardNAC v1.1.12
Architecture

Three-plane separation, mTLS 1.3, Redis event bus — native Ubuntu, no containers.

// 01 — Three Planes

Architecture overview

Each plane is a dedicated systemd service with its own user, isolated privileges, and a single well-defined responsibility.

Browser / Admin UI nginx — Reverse Proxy / TLS Termination Routes to Management Plane · Data Plane · Static Assets MANAGEMENT PLANE Policy & Configuration Python · FastAPI · SQLite JWT Authentication · RBAC Entra ID SAML SSO Isolated system user CONTROL PLANE Auth Decisions Go · FreeRADIUS RADIUS Policy Engine Dynamic VLAN · CoA Elevated privileges DATA PLANE Telemetry & Push Go + Python WebSocket · Prometheus Redis Stream Consumer Isolated system user mTLS 1.3 Redis Event Bus — Internal only
Management Plane

Policy & Config

Python · FastAPI · SQLite
  • REST API for all configuration
  • JWT authentication + RBAC
  • Entra ID SAML SSO
  • License enforcement
  • SHA-256 audit chain
Control Plane

Auth Decisions

Go · FreeRADIUS
  • RADIUS policy engine
  • FreeRADIUS integration
  • Dynamic VLAN assignment
  • CoA / Disconnect dispatch
  • MAC registration & rogue
Data Plane

Telemetry & Push

Go + Python · Redis
  • RADIUS event collector
  • WebSocket real-time push
  • Redis Stream consumer
  • Prometheus metrics
  • Batch event processing
// 02 — Auth Flow

802.1X authentication flow

Device Connects Switch / AP RADIUS Request EAP Identity Identity Resolved Entra ID Policy Checked Group / CVE Access Granted VLAN assigned
// 03 — Services

Native deployment, no containers

portguard.service
Management Plane — FastAPI/uvicorn
Isolated system userAuto-restart on failure
portguard-ctrl.service
Control Plane — Go binary
Elevated privilegesmTLS to Management
portguard-radius-collector.service
Data Plane — RADIUS event collector
Isolated system userBatch event processing
portguard-dashboard-api.service
Data Plane — REST API + WebSocket
Isolated system userPrometheus metrics
portguard-redis.service
Redis instance — internal event bus
Unix socket onlyMemory limited
freeradius.service
FreeRADIUS — 802.1X / EAP auth server
UDP auth/accountingIsolated user
// 04 — Security Design

Built with security first

🔒

mTLS 1.3

All inter-plane communication is encrypted with mutual TLS 1.3. No plane can communicate without a valid certificate.

👤

Privilege Separation

Each service runs as a dedicated system user with only the permissions it needs. The web process cannot touch RADIUS config.

📋

Tamper-Evident Audit

Every configuration change and auth decision is logged with a SHA-256 chain. Any modification is immediately detectable.

🔐

JWT + Refresh Rotation

Admin sessions use short-lived JWT tokens with rotating refresh tokens. Session invalidation is immediate on logout.

🛡

No External Dependencies

PortGuard operates fully offline. No cloud sync, no call-home, no telemetry. Suitable for air-gapped environments.

🔑

License Cryptography

Licenses are signed with a private key that never leaves our infrastructure. Validation is local — no internet required.

// 05 — Changelog

What's new in v1.1.12

TypeChange
New Package Operations Guard — system updates can no longer fail halfway: every package operation runs in a pristine environment, a preflight check refuses an update that cannot complete (free space on /, /boot and /var, package-manager lock, dpkg state) with an explicit cause and remedy, and dpkg state is repaired and re-verified around each install
Fix Kernel updates no longer fail with "Read-only file system" — an Ubuntu kernel update could abort mid-install and leave the package manager blocked until manual SSH recovery
New Repair Package State — recover a half-finished package manager from Updates › System Updates, or from the console with portguardnac-cli packages; an automatic check every 6 hours repairs it on its own when safe and notifies otherwise
Fix HTTPS — the certificate uploaded in the dashboard is now really served by nginx, with automatic rollback to the previous one if the new pair is rejected (before, the UI said “Saved” while the browser kept getting the old self-signed certificate)
Fix RADIUS — a newly added switch is active immediately: the apply now performs a real service restart (FreeRADIUS does not reload its client list on reload), validated before and health-checked with auto-rollback after
Fix Updates — a stale Python cache no longer aborts an installation, an outdated cached package is never installed silently, and fixes that live in /etc (systemd drop-ins, sudo delegations) now arrive with the update instead of requiring an ISO reinstall
New Complete license lifecycle — expiry email alerts (30/14/7/1 days), a two-stage grace period after expiry (read-only then blocked) and support-window enforcement on version updates; security updates always remain available
New Two-factor authentication is now optional — enable or disable MFA per administrator, with a "Require MFA at login" policy toggle
New In-place Factory Reset — return the appliance to a fresh state from Settings > Maintenance without reinstalling the ISO; optionally keep network settings and license
Fix Reliability — RADIUS sessions auto-close when a device goes silent (no more endpoints stuck online); fixed a rare post-update login lockout; cleaner Recent Auth Events on a fresh install
New Advanced Device Profiling — multi-signal confidence engine (IEEE OUI vendor, auth/EAP method, hostname & user patterns, MAC randomization, VLAN) ranks device types by new detections. Real signals only — no fabricated JA3/DHCP fingerprints
New Live Network State — real-time Live Endpoints (one row per MAC: device type, OS, IP, VLAN, auth method, status) shown alongside device profiling in SOC/NOC
New Accurate authentication-method reporting — EAP-TLS is now distinguished from PEAP and EAP-TTLS (reads the real EAP type and client-certificate CN)
New Endpoint IP detection from RADIUS accounting (Framed-IP-Address) shown per endpoint where the switch supplies it
Change "Policies" renamed to "Access Policies"; RADIUS client terminology aligned to Switch / Devices across the dashboard
Fix More accurate "Unknown Devices" metric on flat L2 networks — counts only unidentified endpoints that actually reached the RADIUS auth layer, not every MAC seen in accounting
New Device profiling with IEEE OUI — every device identified by vendor from the official IEEE registry (~53,000 prefixes, bundled offline)
New Automatic device grouping — Computer, Phone/Tablet, Printer, CCTV, VoIP, IoT and Network, with manual override
New Devices inventory page — live vendor, group, VLAN and last identity per endpoint, with randomized/BYOD MAC detection
New Group-based VLAN enforcement — send every CCTV camera or printer to its own segment with a single policy, no per-MAC rules
New Device-group and SSID policy conditions now enforced live, with dedicated cctv / printer / voip roles and access profiles
New Update guard with automatic rollback — a failed update can no longer block appliance login
New High-quality PDF reports — multi-page exports with proper fonts, pagination and aligned tables
Fix Super admin account is protected — it can never be deleted
Fix RADIUS config rollback — snapshots selectable by clear local date/time
New Client Certificates for 802.1X EAP-TLS — issue and manage user and machine certificates from the dashboard
New Secure update channel on downloads.portguardnac.com — SHA-256 verified packages, optional release signing
New portguardnac-cli — status and diagnostics tool from the appliance console
New SNMP extensions for PRTG / LibreNMS infrastructure monitoring
Perf Component inventory refreshes automatically after system or application updates
Fix SOC/NOC telemetry accuracy — connected devices, identities and top VLANs
Fix Idle session timeout enforced as configured (0 = disabled)
Fix Consistent dd/mm/yyyy HH:MM:SS timestamps across the dashboard