Control plane & GUI

Configuration partial

The hs-api binary is the control plane: it stores and distributes policy, tails telemetry for the Attack Explorer, manages certificates, handles auth, and serves the GUI (embedded in the binary).

Command-line flags

Flag	Default	Env	Controls
`-listen`	`:8081`	`HS_CP_LISTEN`	Listen address
`-telemetry-file`	—	`HS_TELEMETRY_FILE`	Telemetry JSONL to tail (feeds the explorer)
`-policy-file`	—	`HS_POLICY_FILE`	Policy JSON to manage and distribute
`-sites-file`	—	`HS_SITES_FILE`	Multi-site routing JSON to manage
`-certs-dir`	—	`HS_CERTS_DIR`	TLS cert directory; enables upload + ACME
`-settings-file`	—	`HS_SETTINGS_FILE`	GUI settings (home country for the threat map)
`-learning-file`	—	`HS_LEARNING_FILE`	Offline-ML insight JSON for the Learning tab
`-feed-pending-file`	—	`HS_FEED_PENDING_FILE`	Staged feed rules awaiting approval
`-users-file`	—	`HS_USERS_FILE`	User database JSON (multi-user RBAC)
`-retain`	`20000`	—	In-memory events retained for the explorer

Authentication & authorization

Variable	Purpose
`HS_ADMIN_TOKEN`	Bearer token gating the config-write API; auto-generated and logged if unset
`HS_ADMIN_USER` / `HS_ADMIN_PASSWORD`	Seed admin credentials; a random password is generated and logged if unset
`HS_SESSION_KEY`	Signing key for session cookies
`HS_COOKIE_SECURE`	`true` marks session cookies `Secure`

OIDC / SSO (presence of HS_OIDC_ISSUER enables it):

Variable	Purpose
`HS_OIDC_ISSUER`	Issuer URL — enables OIDC
`HS_OIDC_CLIENT_ID` / `HS_OIDC_CLIENT_SECRET`	Client credentials
`HS_OIDC_REDIRECT_URL`	Redirect URL
`HS_OIDC_SCOPES`	Space-separated scopes
`HS_OIDC_PROVIDER_NAME`	Name shown on the login button (default `SSO`)
`HS_OIDC_USERNAME_CLAIM` / `HS_OIDC_GROUPS_CLAIM`	Claims for username and groups
`HS_OIDC_DEFAULT_ROLE` / `HS_OIDC_ROLE_MAP`	Role assignment when no group matches / static map
`HS_OIDC_ADMIN_GROUP` / `HS_OIDC_OPERATOR_GROUP` / `HS_OIDC_VIEWER_GROUP`	Group → role mapping

Roles are server-enforced: viewer reads the dashboard, operator also edits config and approves rules, admin also manages users.

The GUI

The Svelte GUI is served by hs-api. Its views:

View	What it does
Overview	Read-only dashboard — KPIs (total, flagged, would-block), mitigation counters, a live threat-origin map. Configurable: the home country used for the map.
Explorer	The Attack Explorer — per-request decision, raw → canonical trace, risk breakdown, findings and anomalies. "Flagged only" filter.
Endpoints	Read-only per-endpoint learned baselines (requests, flagged rate, methods, average params / size).
Sites	The multi-site editor: default origin, global overload-shed `max_rps` + burst, and per-site general / policy / access / rules tabs.
Policy	The global/default policy editor: enforce toggle, decision thresholds, engine enable, edge (forwarded headers, PoW routes, response hardening, security.txt), access control.
Rules	Standalone custom-rule editor for the global policy (hot-reloaded).
Certificates	List / upload PEM bundles and issue via Let's Encrypt (ACME HTTP-01) with auto-renew. Enabled when `-certs-dir` is set.
Learning	(Enterprise) SOC briefing and a human-gated suggested-rule approval queue; anomalies and attack clusters.
Users	(admin) Manage users and roles; local + OIDC login.

Policy distribution

Policy edits are written as versioned JSON and hot-reloaded by the data plane via a lock-free atomic swap — no dropped connections, and a monotonic version provides anti-rollback. The control plane and data plane share the same policy files (-policy-file / -sites-file), so "save & distribute" in the GUI is what the engine picks up.

Status

The Explorer API, embedded GUI, versioned file-backed policy store with atomic hot-reload, auth (bearer token + local users/RBAC + OIDC), and certificate management (ACME HTTP-01) are built. A Postgres-backed config store and HAProxy-frontend generation for wildcard/SNI routing are still ahead; today the store is file-backed.