Technical Deep Dive

A platform engineered for control

FreeSDN is a multi-tier platform: client → API gateway → core and modules → plugin and AI layers → adapter registry → physical devices. Every request flows through JWT validation, tenant-context injection, rate limiting, and RBAC permission checks before it ever touches business logic.

Request Flow

React SPAJWT + CORSTenant ContextRBAC CheckService LayerAdapterDevice

System Architecture

Multi-tier platform design

FreeSDN follows a clean layered architecture: Client to API Gateway to Core + Modules to Adapter Registry to Physical Devices. Each request flows through JWT validation, tenant context injection, rate limiting, and permission checking before reaching business logic.

Architecture Layers

Client Layer

React 19 + TypeScript + Vite 8

React 19.2 SPA, Node 24, TypeScript 6. shadcn/ui components, TanStack Query, Zustand stores

API Gateway

FastAPI + Middleware Stack

JWT + CSRF validation, tenant context, rate limiting, CORS, structured logging

Core Platform

Auth · Devices · Discovery · Events · Audit

Always loaded. Pydantic v2 schema layer, event bus, Celery task queue

Module Layer

10 Domain Modules

Hot-pluggable, isolated, per-org enablement, own DB migrations

Plugin Layer

SDK + Marketplace + Governance

Trusted-author Python plugins (cooperative model, not a security sandbox), typed SDK interfaces, manifest validation, SSRF protection

AI / LLM Layer

Multi-Provider + Token Budgets

OpenAI, Anthropic, Ollama. Tool calling, prompt governance, 3-layer policy, audit trails

Adapter Registry

Adapter SDK · maturity tracked

BaseAdapter ABC, capability mixins, connection pooling, retry logic

Infrastructure

PostgreSQL · Valkey · Celery · TimescaleDB

Celery worker + worker-io split, TimescaleDB time-series

Technology Stack

Python 3.14.5

Backend

FastAPI

API Framework

SQLAlchemy 2.0

ORM

Pydantic v2

Validation

PostgreSQL 18.4

Database

TimescaleDB

Metrics / Events

Valkey 8.1

Cache / Broker

Celery 5.6

Task Queue

React 19.2

Frontend

TypeScript 6

Type Safety

Tailwind CSS v4

Styling

shadcn/ui

Components

Vite 8

Build Tool

Node 24.16

JS Runtime

TanStack Query

Data Fetching

Caddy

Edge / Auto-HTTPS

Supported apps & hardware

FreeSDN labels each integration by maturity so you can decide what to test, pilot, or rely on. Vendors that are not built are intentionally omitted.

Vendor / app	Category	Protocol	Maturity	Notes
TP-Link Omada	Network (switch/AP/gateway)	httpx + OAuth2	Fully supported	Reference adapter; deepest coverage.
OPNsense	Firewall / gateway / VPN	httpx + API Key	Fully supported	Feature domains use stage + apply.
pfSense	Firewall / gateway	httpx + API Key	Fully supported	Shares OPNsense plumbing; API-key auth.
MikroTik RouterOS	Router / switch / wireless	httpx + REST API	Fully supported	Full backend; UI covers a subset of domains.
Proxmox VE	Compute / hypervisor	httpx + API Token	Fully supported	VMs, CTs, snapshots, backups, HA, SDN, Ceph.
Hikvision	Cameras / NVR	httpx + Digest (ISAPI)	Fully supported	ISAPI streaming, PTZ, playback, NVR import.
FreePBX / Asterisk	VoIP / PBX	AMI / ARI / REST	Beta	Extensions, trunks, queues, IVR, CDR; limited field testing.
Grandstream	VoIP / SIP phones	aiohttp CGI	Beta	Provisioning, status, and fleet operations.
Ubiquiti UniFi	Network (switch/AP/gateway)	httpx + UniFi API	Beta	Validated by automated tests; not yet field-tested on physical hardware. REST only.
OpenWrt	Router / AP	httpx + ubus / rpcd	Preview	Speaks ubus/UCI; not yet audited. Developer preview.
TrueNAS	Storage	WS JSON-RPC (TLS)	Preview	Read-only health, pool, and disk monitoring.
ONVIF-compatible cameras	Cameras	SOAP over httpx	Preview / generic	Generic fallback shim for Dahua, Axis, Reolink, Amcrest, and similar cameras.

Adapter SDK: add a vendor in one file

Subclass BaseAdapter, implement the typed interface, register in the adapter registry. The platform handles connection pooling, retry logic, caching, and capability detection automatically.

adapters/my_vendor/adapter.py
from app.adapters.base import BaseAdapter
from app.adapters.capabilities import SwitchCapabilityMixin
class MyVendorAdapter(BaseAdapter, SwitchCapabilityMixin):
"""Your vendor, typed and testable."""
async def connect(self) -> None:
self.session = await self._create_session()
async def discover_devices(self) -> list[Device]:
raw = await self.session.get("/api/devices")
return [self._normalize(d) for d in raw]
async def get_ports(self, device_id) -> list[SwitchPort]:
# SwitchCapabilityMixin interface - typed return
return await self._fetch_ports(device_id)

Enterprise Security

6-layer security model

Security is built into every layer - from application-layer tenant isolation and staged write gates to signed supply chains and HTTP hardening. FreeSDN uses a defense-in-depth approach for environments that handle network credentials.

This release includes automated tests and internal review, but no third-party security audit, live-exploit penetration test, or compliance certification is claimed.

Authentication

JWT access tokens (15 min) + refresh tokens (7 days), jti revocation blacklist and token_version invalidation. MFA via TOTP (RFC 6238) with backup codes. SSO via OIDC and LDAP (implemented; not yet verified end-to-end against a live identity provider) - SAML gated pending XSW-safe verifier. Account lockout after 5 failures with exponential backoff.

Argon2id · 64 MB / t=3 / p=4TOTP MFA + backup codesOIDC + LDAP SSOJWT HS256 + jti revocation

Authorization

Role-based access control with strict-lower-than assignment that blocks privilege escalation at the API layer. Five assignable roles (super_admin → org_admin → site_admin → operator → viewer); the permission hierarchy adds two internal-only levels (admin, guest) used for comparison logic but not user-assignable. Scoped API keys act as a hard permission ceiling, even for super_admin.

5 assignable rolesPer-module permissionsScoped API key ceilingResource-level checks

Multi-Tenancy

Application-layer org-scoped queries throughout the service layer, combined with per-user site grants enforced across the site-scoped modules. Fail-closed by default - no resource is returned unless the caller's organization is verified.

Org-scoped service layerPer-user site grantsFail-closed enforcementCovered by automated tests

Credential & Data Safety

Fernet AES-128-CBC + HMAC-SHA256 encryption for all stored device credentials and secrets. Central redact_secrets (~120 sensitive keys, camelCase-aware) scrubs adapter reads before any response leaves the API. SSRF-safe HTTP via resolve-once + IP-pin (no redirects, metadata/CGNAT blocked).

Fernet credential encryption~120-key secret redactionSSRF / DNS-rebind guardPath-traversal allow-list

Write Safety & Audit

Staged dual-gate for every adapter write: ADAPTER_READ_ONLY=false AND force=true must both be set; UI-authored writes are staged to the DB and never touch live devices until an explicit operator apply. Every privileged action is logged with user, org, IP, user-agent, resource, and before/after diff.

Staged dual-gate writesExplicit operator applyImmutable audit logBefore/after diffs

Transport & Supply Chain

TLS 1.3 everywhere via Caddy automatic HTTPS. CORS explicit allowlist. Rate limiting per endpoint (429 + Retry-After). CSRF tokens on state-changing requests. Marketplace catalog is Ed25519-signed (unsigned refused by default); agent auto-updates are ECDSA-P256 signed, fail-closed.

TLS 1.3 / Caddy auto-HTTPSCORS + CSRF + CSP/HSTSRate limiting + 429Ed25519 / ECDSA signed supply chain

Role Hierarchy (5 assignable)

Role	Score	Scope	Access Level
`super_admin`	100	Global	Full platform access, all organizations
`admin`	80	Internal	Internal hierarchy level — not user-assignable
`org_admin`	60	Organization	Full access within their organization
`site_admin`	40	Site	Manage assigned sites and devices
`operator`	20	Site	Day-to-day operations, limited config changes
`viewer`	10	Site	Read-only access to dashboards and logs
`guest`	0	Internal	Internal zero-privilege level — not user-assignable

Strict-lower-than role assignment enforced at the API layer - no user can grant a role equal to or higher than their own.

Deployment Tiers

Small

1-50 devices

• Single Docker host
• 4 GB RAM
• All 8 containers
• Dev or home lab

Medium

50-500 devices

• Docker Swarm / K8s
• 8-16 GB RAM
• Horizontal workers
• Multi-site MSP

Large

500+ devices

• Kubernetes cluster
• 32+ GB RAM
• Sharded Celery
• Enterprise / DC

Open Source

Free as in freedom

FreeSDN is fully open-source under the AGPLv3 (AGPL-3.0-only) license. No artificial limitations, no "community edition" crippling, no surprise licensing changes.

AGPL-3.0 Licensed

No vendor lock-in, no per-device fees, no phone-home telemetry. Fork it, extend it, build services on top of it. The source is yours.

No Per-Device Fees

Monitor a small lab or a large fleet. FreeSDN charges nothing per device. Compare that to commercial per-device licensing.

Self-Hosted

By default, your credentials and data stay on your own infrastructure. No cloud dependency, no SaaS outage risk, fully air-gappable.

Community-Driven

Built by network engineers for network engineers. Feature requests, bug reports, and pull requests are all welcome.

Ready to take control of your network?

Join the community managing their multi-vendor infrastructure with a single, open-source platform.

View on GitHub Quick Start Guide Star on GitHub

See it running in your browser

Explore the full FreeSDN dashboard with realistic sample data, no signup, no backend. Then install it in minutes.

Live Demo Read the Docs View on GitHub →