Security

HTTPS for the web interface and two-factor login (TOTP).

HTTPS

The installation creates a self-signed certificate once for the host name and the addresses of the machine (/appdata/bunkerbox/data/tls/selfsigned.crt and .key, EC P-256, 10 years, readable by root only). HTTPS is off at first; the interface runs on port 80.

Access → Security → HTTPS:

Setting	Meaning
Serve the web interface over HTTPS	starts a second listener with the same interface
HTTPS port	default 443; not the HTTP port
Redirect HTTP to HTTPS	port 80 answers with 308 to the HTTPS address

• Changes apply immediately, without restarting the service. If the new setting cannot be applied (port in use, unusable certificate), the previous one stays active and the interface shows the reason.
• Port 80 always stays open. Requests from the machine itself (loopback, e.g. the health check of update.sh) are served over HTTP even with the redirect.
• Over HTTPS the session cookie additionally gets Secure. Switching HTTPS off while connected over HTTPS shows a warning: the page is only reachable over HTTP afterwards.
• The setting is stored in data/server.json (600) and read when the service starts.

Certificate

The Certificate card shows subject, issuer, names, validity and the SHA-256 fingerprint. Browsers warn about self-signed certificates; on the first visit compare the fingerprint shown by the browser with the one shown here, then accept the certificate. A warning appears 30 days before expiry.

• Upload certificate: certificate (server certificate first, then intermediate certificates) and private key in PEM format, as file or pasted. The key (RSA or EC) must not be encrypted (openssl pkey -in key.pem -out plain.pem). Checked: readable, key matches the certificate, currently valid, at most 64 KiB. Stored as data/tls/uploaded.crt and .key (600); the key is never returned.
• New self-signed certificate: creates a new key and certificate with openssl (host name, full name, localhost, all addresses of the machine) and uses it right away, e.g. after changing the host name or address, or to switch back from an uploaded certificate.

Behind a reverse proxy (that offers HTTPS itself) HTTPS usually stays off here; add the proxy to BUNKERBOX_TRUSTED_PROXIES (see Installation).

Two-factor login

After the password a code from an authenticator app is required as well (TOTP per RFC 6238: SHA-1, 6 digits, 30 seconds; e.g. Aegis, Google Authenticator, 1Password, Bitwarden).

Set up

Access → Security → Two-factor login → Set up:

1. Scan the QR code with the app or enter the key shown manually. The QR code is generated on the machine itself; the key only travels to your browser.
2. Enter the 6-digit code of the app. Only then is two-factor login active. An unconfirmed setup expires after 15 minutes.
3. 10 recovery codes are shown exactly once (copy them or download them as a text file). Each works once instead of the app code. Only their hashes are stored.

Log in

After the password the login page asks for the code; Use a recovery code accepts a recovery code instead. Until then the session reaches nothing but this step (no API, no terminal).

• The current, the previous and the next code are accepted (clock drift up to 30 seconds). Each code works only once.
• After 5 wrong codes for an account further attempts are locked for 15 minutes.
• Different account cancels the step and logs out.

Manage

• New recovery codes (with a valid code): the previous ones become invalid. With 3 or fewer left the interface points that out.
• Switch off (own account, with a valid code).
• Require for all administrators: only possible when your own account uses two-factor login. Administrators without it have to set it up on their next login right after the password. While required, it cannot be switched off.
• Reset (table Administrators): another administrator can reset the two-factor login of an account after typing its user name, e.g. after the phone and the recovery codes were lost.

Every step is recorded in the audit log.

All factors lost

If the only administrator lost the phone and the recovery codes, as root on the console or via SSH:

nano /appdata/bunkerbox/data/security-state.json   # delete the account under "twoFactor", if needed set "enforceForAdmins": false
systemctl restart bunkerbox

Notification about a new address

Bunkerbox remembers the last 20 addresses of successful logins per administrator. When an administrator logs in from an address not seen before, the event Login from a new address is raised (e-mail if enabled under Notifications). The very first login of an account raises nothing.

Storage

data/security-state.json (600): TOTP keys (needed to check codes), hashes of the recovery codes, last used time step (replay protection), the requirement for all admins and the known addresses.

API

Method	Path	Description
GET	/api/security	SecurityOverview (HTTPS and two-factor)
GET/PUT	/api/security/https	HttpsSettings / UpdateHttpsRequest (enabled, port, redirectHttp)
POST	/api/security/https/certificate	UploadCertificateRequest (certificatePem, privateKeyPem) -> HttpsSettings; 422 for an invalid pair
POST	/api/security/https/selfsigned	new self-signed certificate -> HttpsSettings
GET	/api/security/2fa	TwoFactorOverview (requirement, all admins)
PUT	/api/security/2fa/policy	{ enforceForAdmins }; 409 without own two-factor login
POST	/api/security/2fa/enroll	TwoFactorEnrollment (secret, otpauthUri, qrSvg) for the own account
POST	/api/security/2fa/confirm	{ code } -> RecoveryCodes
POST	/api/security/2fa/disable	{ code } (own account)
POST	/api/security/2fa/recovery-codes	{ code } -> new RecoveryCodes
DELETE	/api/security/2fa/users/[user]	reset the two-factor login of another admin
GET	/api/auth/2fa	pending session: SecondFactorChallenge (verify or enroll)
POST	/api/auth/2fa/verify	{ code } (TOTP or recovery code) -> MeResponse; 403 wrong code, 429 locked
POST	/api/auth/2fa/enroll, /api/auth/2fa/confirm	setup during login when required; confirm -> { me, codes }