Circuit Breaker v0.3.3 — Release Notes

Target release: July 2026 Previous release: v0.3.1 Branch: dev

Highlights

v0.3.3 is a discovery-and-trust release. It closes out the two-phase Discovery Readiness project — a self-healing capability broker that keeps LAN scanning working without asking users to babysit nmap permissions — and ships a brand-new Privacy & Threat dashboard that scores your network's exposure from real scan data. Alongside those, a from-scratch continuous monitoring polling engine replaces the old sequential monitor loop with independently-scheduled ICMP/TCP/HTTP checks, and the scan progress bar has been rewritten from a Lottie animation into four selectable CSS-driven styles. Ten new database migrations are included; all are additive.

Feature Areas in This Release

Discovery Readiness & Self-Healing (Phases 1 & 2)

Network discovery has historically been the most fragile part of Circuit Breaker — a missing nmap binary, a dropped capability, or a container restart could silently degrade scans to an ARP-only fallback with no visible warning. This release makes discovery fail loudly instead of quietly, then makes it heal itself.

Phase 1 — Reliability & fail-loud: - New capability model and readiness-detection service reports whether nmap is present, whether raw-socket capability (CAP_NET_RAW) is available, and whether ARP is degraded. - GET /discovery/readiness exposes this status to the UI; discovery now logs loudly at startup when capabilities are degraded instead of silently downgrading. - The build pipeline guarantees the nmap binary and its setcap bit are present across dev, bare-metal, and Arch packaging, and the mono Docker container grants CAP_NET_RAW via ambient capabilities.

Phase 2 — cb-helperd broker + self-healing: - A small, stdlib-only root daemon (cb-helperd) now runs on the host (never inside the container) and listens on a Unix socket (/run/circuitbreaker/helper.sock). It exposes a fixed allowlist of actions — get_host_readiness, ensure_nmap, grant_nmap_caps, enable_lan_discovery, disable_lan_discovery — and authenticates callers via SO_PEERCRED against the UID recorded at install time. Circuit Breaker degrades gracefully if the helper isn't installed. - Enabling/disabling LAN (ARP) discovery now generates a Docker Compose override (network_mode: host + CAP_NET_RAW) with automatic health-check verification and rollback if the change breaks the container. - A new self-healing reconciliation loop runs at startup and roughly every 15 minutes: - Class 1 issues (missing nmap, missing raw-socket capability) are auto-healed silently — these should always be true, so drift is repaired without asking. - Class 2 is your LAN-discovery consent: once you toggle it on or off in Settings, the reconciler continuously keeps actual host state converged with your choice — re-applying it after a reboot or drift, tearing it down if you turn it off — but it never expands consent on its own. - Repeated failures on a capability drop retry cadence to hourly and surface as "needs attention" rather than failing silently forever. - A new Readiness panel in Discovery Settings shows live capability status and the LAN-discovery toggle, backed by a TTL-cached useDiscoveryReadiness hook with a safe fallback if the helper is unreachable. - Reconciler actions are now logged as queryable audit entries (entity_name on log_worker_audit), and the readiness API exposes per-capability auto-heal metadata plus whether the helper is installed at all.

Why it matters: you make the LAN-discovery decision once. Circuit Breaker keeps it working — or tells you clearly when it can't — instead of leaving scans silently degraded.

Privacy & Threat Dashboard

A new Privacy page (under the Security nav) turns your existing scan data into an ongoing exposure score instead of a one-time report.

  • Score gauge and grade (A–F) with a 30-day trend line, computed from device-level and network-level checks — starts at 100 and subtracts points per finding, clamped 0–100.
  • Network status checks: captive portal detection, DNS tampering, and DNS filtering — any critical network-level finding clamps the network score to at most 55, since a compromised network make device-level findings less trustworthy.
  • Device checks: flags devices with telnet open, ftp open, legacy SMB/NetBIOS exposed, or UPnP exposed.
  • Pluggable threat feed: cross-references discovered devices against free public blocklists (Redis-cached), surfaced as flagged devices with remediation guidance.
  • Findings-over-time and findings-by-category charts, a collapsible "Key Findings" list with remediate/ignore actions, and a Flagged Devices table.
  • Attack Surface table: lists open ports for every device that's had a deep scan, so you can see actual exposed surface area per host.
  • Score recomputes automatically when a scan finishes, plus on a periodic background schedule, so the dashboard stays current without manual refresh.

A note on naming: this feature was built under the internal codename "Windscribe." That name had leaked into a couple of user-facing spots (a Settings toggle labeled "Windscribe Integration" and related hint text implying a live Windscribe/ControlD API); the copy has been renamed to "Network Threat Intelligence" / "Threat Intelligence Feed" ahead of this release. The actual implementation is Circuit Breaker's own scoring engine plus free public blocklists (Hagezi, OISD, ControlD's free list) — there is no real Windscribe account, API key, or partnership involved. Internal identifiers (settings field names, the /windscribe API route, module names) still use the codename and are unaffected — only user-visible copy changed.

Continuous Monitoring — Polling Engine Rewrite

The old monitor loop polled one fixed cascade of checks per host on a shared cadence. It's been replaced with an item-based poller, similar in spirit to Zabbix-style monitoring items.

  • A MonitorItem is a single polled check — icmp, tcp, or http — against a target, with its own interval and independent scheduling. A single host can now have separately-timed ICMP, TCP, and HTTP checks instead of one shared cascade.
  • Collectors: ICMP now reports packet loss percentage and jitter (mean deltas between consecutive round trips) in addition to latency; TCP and HTTP collectors report availability and latency per check.
  • Atomic claim-and-enqueue scheduler: uses SELECT ... FOR UPDATE SKIP LOCKED to claim due items and advance their next-due time before dispatch, so a scheduler or worker crash can't strand items in a stuck "running" state, and multiple items can be claimed concurrently without double-polling.
  • Telemetry samples now carry an item_id dimension, giving each check its own history/graphing — e.g., a separate packet-loss trend for an ICMP check versus a latency trend for an HTTP check on the same host, where before there was only one combined series per host.
  • Existing hardware_monitors are automatically backfilled into the new monitor_items table on upgrade — no reconfiguration needed.

Scan Progress Bar & Personalization

  • The scan progress bar has been rewritten from a Lottie (dotlottie-react) animation into four CSS-driven styles: Scanline Sweep, Segmented Pulse, Circuit Trace, and Minimal Gradient Glow — all driven by real scan job progress rather than a looping decorative animation.
  • A new style picker with live previews lives under Settings → Personalization, so you can choose the look that fits your dashboard.
  • The animated bar now also applies to the live history-table row during an in-progress scan, not just the scan detail panel.
  • The unused dotlottie-react dependency and its asset file have been removed.

Proxmox Token Helper

  • Proxmox API token permission handling has been hardened, with new test coverage around token permission edge cases (test_proxmox_client_permissions.py).

Bug Fixes

  • Cross-test DB pollution: log_worker_audit test fixtures no longer leak state across tests via a SAVEPOINT-rollback bypass.
  • mypy compliance: type errors resolved in helper_client.py, discovery_readiness.py, and privacy-score deduction/Redis-cache handling (untyped fields coerced, bytes-from-Redis accepted).
  • Fresh-install migrations: WIP privacy/Windscribe migrations are now safe to run on a brand-new database, not just on databases upgrading from an earlier version.
  • telemetry_timeseries hypertable conversion: primary key now includes ts, fixing a failure converting the table to a TimescaleDB hypertable.
  • Docker/nginx logging: nginx log targets now work correctly under the mono image's root-owned supervisord.
  • Migration-phase Postgres: TimescaleDB is now preloaded in the entrypoint's migration-phase Postgres instance, preventing a startup-order failure.
  • Discovery readiness detection: ambient CAP_NET_RAW is now correctly recognized so nmap OS detection isn't needlessly reported as degraded; a dead arp_l2 code path was removed.
  • Scan setting toggles: settings toggle buttons now render as clear on/off switches instead of ambiguous color blobs.

Database Migrations

Ten new migrations apply automatically on upgrade (or via make migrate):

Migration Summary
0081_monitor_items Create monitor_items table for the continuous polling engine
0082_telemetry_item_id Add item_id dimension to telemetry_timeseries for per-check samples
0083_migrate_hardware_monitors Backfill monitor_items from existing hardware_monitors
f61dd2dc9ade_remove_deprecated_features Remove deprecated feature scaffolding
5ed182a77737_create_privacy_scores Create privacy scoring tables
21f5eaea0483_add_windscribe_settings Add privacy/threat-feed settings
7c41a90d55e1_create_network_privacy_snapshots Create network_privacy_snapshots table
ec2fa30c05d1_add_privacy_finding_ignores Track ignored privacy findings
0084_lan_discovery_desired_setting Add lan_discovery_desired toggle to app_settings
abec47e19d13_add_scan_progress_style Add scan_progress_style column to app_settings

All migrations are additive — no columns or tables are dropped, and existing data is preserved.

Upgrade Notes

  • cb-helperd is optional but recommended. Without it, Circuit Breaker still functions — Class 1 auto-heal and LAN-discovery toggling simply won't be available, and the Readiness panel will show the helper as not installed. Install it via the systemd unit shipped in this release, or through the updated deploy scripts (both deploy paths now install and enable it automatically).
  • New settings, defaulted safely: lan_discovery_desired defaults to off; scan_progress_style defaults to circuit (Circuit Trace).
  • Privacy dashboard needs at least one completed scan to populate — it recomputes on scan finalization and on a periodic background job, so scores appear shortly after your next scan.
  • No manual steps required for standard upgrades — migrations apply automatically per your existing CB_AUTO_MIGRATE configuration.
  • Open Discovery → Settings and check the new Readiness panel — confirm nmap and capability status are green, and install cb-helperd if you want self-healing LAN discovery.
  • Visit the new Privacy page under Security after your next scan completes to see your network's exposure score.
  • Open Settings → Personalization and try the new scan progress bar styles.
  • If you rely on monitoring, no action is needed — existing monitors are automatically migrated to the new polling engine on upgrade.