DockFlare Security Architecture & Hardening

This document explains how DockFlare secures both the Master node and enrolled Agents in DockFlare 3.0+. It complements the security audit by cataloging the safeguards built into DockFlare and outlining recommended operational practices.

1. Control Plane Trust Model

Master as Source of Truth – The DockFlare Master holds all Cloudflare credentials and policy definitions. Agents never manage API tokens; they execute instructions received over an authenticated channel.
Per-Agent API Keys – Enrolment requires a unique API key minted by the Master. Keys are stored in the encrypted agent_keys.dat store along with metadata (owner, timestamps, status) so they can be rotated or revoked at any time.
Master API Protection – Administrative endpoints (web UI, /api/v2/*) require either a valid session or the master API key. Tokens are redacted from responses and logs and can be rotated without restarting the stack.

2. Encrypted Configuration & Key Management

Encrypted dockflare_config.dat – Cloudflare credentials, UI accounts, tunnel defaults, and the master key are kept in an encrypted blob protected by dockflare.key.
Encrypted Agent Registry – Agent API keys and their audit metadata live in agent_keys.dat, encrypted with the same Fernet key. Sensitive material no longer appears in state.json.
Automatic Restart on Restore – When a backup archive is restored, DockFlare writes the encrypted artefacts, reloads runtime state, drops a restart flag, and exits. Docker’s restart policy brings the container back immediately with the new configuration.
Plain state.json for observability – state.json remains plaintext so operators can inspect rules and agents. Encrypted files remain authoritative for secrets.

3. Backup & Restore Guarantees

Archive Contents – Each backup archive (dockflare_backup_*.zip) contains dockflare_config.dat, dockflare.key, agent_keys.dat, state.json, and a manifest.json with checksums and version metadata. No additional files are required to rebuild a master node.
Automated Restore Flow – Restoring via the setup wizard or the Settings page writes the artefacts, reloads runtime caches, and forces a container restart so the encrypted configuration is applied immediately.
Legacy Compatibility – Uploading a standalone state.json is still supported for troubleshooting or partial migrations. DockFlare imports the runtime state but retains the existing encrypted configuration, avoiding accidental credential resets.

4. Network & Communication Security

Cloudflare Tunnel Transport – Agents expose no inbound ports. All traffic traverses the Cloudflare tunnel managed by the Master, reducing the attack surface on remote hosts.
Authenticated Agent Calls – Agent REST calls include their API key and are bound to their recorded agent ID. Token mismatches or revoked keys are rejected.
Redis Backplane – DockFlare relies on Redis for caching, log streaming, and cross-thread signalling. The recommended compose stack keeps Redis on a dedicated dockflare-internal network so workloads on cloudflare-net cannot reach it directly. Secure external Redis services with auth/TLS if you use them.
Least-privilege runtime – Both the master and agents run as the dockflare user (UID/GID 65532) and talk to Docker exclusively through the bundled socket proxy, keeping the exposed API surface minimal.

5. Authentication & Authorization

Hardened UI Login – The Pre-Flight wizard forces creation of a UI administrator account. Password login can be disabled, but this is strongly discouraged due to Docker network security implications (see warning below).
Session Management – Flask-Login sessions are tied to the encrypted configuration. Restoring a backup or rotating credentials invalidates existing sessions automatically.
Agent ACLs – Each agent record tracks tunnel assignment, heartbeat timestamps, and pending commands. The Master only delivers commands to agents presenting the correct token and enrolled status.

DockFlare includes a "Disable Password Login" setting intended for advanced deployments where DockFlare itself is protected by an external authentication layer (like Cloudflare Access). We strongly advise against using this feature for most deployments.

Security risks when enabled:

All API endpoints become accessible without authentication when this setting is enabled
Docker network exposure: Even if DockFlare is behind Cloudflare Access on the public internet, containers on the same Docker network can bypass external authentication and access DockFlare's API directly
No authentication enforcement: The application assumes external authentication is handling security

Attack vector example:

Internet → Cloudflare Access (Protected) → DockFlare ✅
         ↓
Docker Network → Other Container → DockFlare API (Unprotected) ❌

Recommended approach: Instead of disabling password authentication, use one of these secure options:

Local DockFlare credentials - Simple password authentication built into DockFlare
OAuth/OIDC providers - Configure Google, GitHub, Azure AD, or other identity providers for easy single sign-on without sacrificing security

Both options provide proper authentication while maintaining the convenience of SSO. The OAuth option gives you the single sign-on experience without the security risks of disabled authentication.

Bottom line: Unless you have a very specific, well-understood security architecture with network isolation, keep password login enabled and use OAuth for convenience.

6. Audit & Operational Visibility

Metadata Tracking – Agent keys record created_at, last_used_at, bound_agent_id, status, and revocation events. state.json mirrors agent last-seen timestamps for at-a-glance health checks.
Log Streaming – Real-time logs stream via Redis pub/sub. Sensitive values (tokens, keys) are redacted before reaching the client.
Status APIs – /api/v2/overview consolidates tunnel, agent, and configuration health for monitoring systems or GitOps workflows.

7. Deployment Recommendations

Area	Recommendation
Docker Volumes	Persist `/app/data` (encrypted config, keys, state). Persist `/app/logs` if file logging is enabled, and ensure host mounts are writable by UID/GID 65532 or your overridden build args.
Redis	Run `redis:7-alpine` alongside DockFlare on a private network (`dockflare-internal`) or point `REDIS_URL` to a hardened instance (auth/TLS). Avoid exposing Redis publicly. Use `REDIS_DB_INDEX` to isolate DockFlare data from other containers sharing the same Redis instance.
Backups	Download the `.zip` regularly and store it with `dockflare.key`. Both files are required to decrypt the configuration on restore.
Agents	Treat API keys like credentials. Deploy them with the socket proxy so only required Docker endpoints are exposed, and remember the container runs as the unprivileged `dockflare` user (UID/GID 65532); align host permissions or rebuild with matching `DOCKFLARE_UID/DOCKFLARE_GID`.
Reverse Proxy	Place DockFlare behind Cloudflare Access or another trusted IdP. If you disable password login, ensure upstream authentication is always enforced.
Monitoring	Alert on unexpected restarts, missing agent heartbeats, or new key issuance outside maintenance windows.

8. Future Enhancements (Roadmap)

Optional passphrase protection for the Fernet key at rest.
Automated agent key rotation with grace periods for staging rollout.
Granular agent command scopes to separate read-only and mutating operations.

DockFlare continues to evolve with security in mind. Stay current with release notes for additional hardening improvements and contribute ideas via the issue tracker if you need further controls.

7.9 KiB Raw Blame History Unescape Escape