Security Overview

This page provides a comprehensive reference of CoolerControl's security model, covering authentication, session management, transport security, and hardening measures.

Authentication

CoolerControl supports two authentication methods:

Method	Use Case	Header
Session (Basic Auth)	Web UI and interactive use	Authorization: Basic <base64> → session cookie
Bearer Token	Plugins, external services, scripts	Authorization: Bearer cc_<uuid>

Admin User

• Username: CCAdmin (fixed, cannot be changed)
• Login: HTTP Basic Auth to establish a session cookie for subsequent requests

Access Tokens

Access tokens provide stateless authentication for plugins and external services without exposing the admin password. Tokens are created and managed from the UI (Access Protection menu).

• Format: cc_<uuid> (35 characters)
• Hashing: (only hashes are stored, never raw tokens)
• Expiry: Optional expiry date per token
• Usage tracking: last_used timestamp updated on each use
• Scope: Write-access tokens have full API access; Read-only tokens can read data but cannot modify settings
• Management: Token creation, listing, and deletion require session auth (tokens cannot manage other tokens)

The raw token is shown only once at creation. See Access Protection for usage details.

Password Security

• Passwords are hashed using Argon2id, a memory-hard hashing algorithm resistant to GPU and ASIC attacks.
• The default password must be changed on first use. The default password cannot be reused when setting a new password.
• Changing the password requires providing the current password for verification.

To reset the password back to the default:

sudo coolercontrold --reset-password

Session Management

After successful authentication, the daemon issues a session cookie.

Property	Value
Cookie flags	HttpOnly, SameSite=Strict
Session expiry	30 days of inactivity

• All sessions are invalidated when the admin password is changed.

Transport Security (TLS)

CoolerControl uses a dual-protocol design on a single port (default 11987):

• Localhost: Plain HTTP is always allowed.
• Non-localhost: HTTP is redirected to HTTPS via 301 redirect.
• TLS is enabled by default with auto-generated self-signed certificates.

For full TLS configuration details, see SSL/TLS.

Security Headers

The daemon automatically applies the following security headers to all HTTP responses:

Header	Value
X-Content-Type-Options	nosniff
X-Frame-Options	DENY
Referrer-Policy	strict-origin-when-cross-origin
Permissions-Policy	camera=(), microphone=(), geolocation=()
Strict-Transport-Security	max-age=31536000; includeSubDomains (HTTPS only)

These headers protect against common web vulnerabilities including MIME sniffing, clickjacking, and information leakage.

CORS Policy

By default, only localhost origins are allowed to make cross-origin requests to the daemon. This prevents unauthorized web pages from interacting with CoolerControl.

To allow additional origins (e.g., when using a reverse proxy with a custom domain):

[settings]
origins = ["https://coolercontrol.mydomain.com"]

See Reverse Proxy for details.

Security Best Practices

1. Change the default password immediately after installation via Access Protection.
2. Use TLS for any non-localhost access — the self-signed certificate works, but trusted certificates from Let's Encrypt or a reverse proxy are preferred.
3. Restrict network access — Bind to specific interfaces and use firewall rules to limit who can reach the daemon. See TCP Port and Address.
4. Use a VPN or SSH tunnel for remote access over untrusted networks. See Remote Access.
5. Keep CoolerControl updated to receive the latest security fixes.

See Also

• Access Protection - Password management
• SSL/TLS - TLS configuration and certificates
• Reverse Proxy - Reverse proxy setup
• Remote Access - Secure remote access options
• Configuration Files - File locations and backup