Sicherheit

HTTPS für die Weboberfläche und Zwei-Faktor-Anmeldung (TOTP).

HTTPS

Die Installation erzeugt einmalig ein selbstsigniertes Zertifikat für den Hostnamen und die Adressen des Geräts (/appdata/bunkerbox/data/tls/selfsigned.crt und .key, EC P-256, 10 Jahre, nur für root lesbar). HTTPS ist anfangs aus; die Oberfläche läuft auf Port 80.

Zugriff → Sicherheit → HTTPS:

Einstellung	Bedeutung
Weboberfläche über HTTPS anbieten	startet einen zweiten Listener mit derselben Oberfläche
HTTPS-Port	Standard 443; nicht der HTTP-Port
HTTP auf HTTPS umleiten	Port 80 antwortet mit 308 auf die HTTPS-Adresse

• Änderungen gelten sofort, ohne Neustart des Dienstes. Lässt sich die neue Einstellung nicht anwenden (Port belegt, Zertifikat unbrauchbar), bleibt die bisherige aktiv und die Oberfläche zeigt den Grund.
• Port 80 bleibt immer offen. Anfragen vom Gerät selbst (Loopback, z. B. der Health-Check von update.sh) werden auch mit Umleitung über HTTP beantwortet.
• Über HTTPS bekommt das Sitzungs-Cookie zusätzlich Secure. Wer HTTPS ausschaltet, während er über HTTPS verbunden ist, wird gewarnt: die Seite ist danach nur noch über HTTP erreichbar.
• Die Einstellung steht in data/server.json (600) und wird beim Start des Dienstes gelesen.

Zertifikat

Die Karte Zertifikat zeigt Inhaber, Aussteller, Namen, Gültigkeit und den SHA-256-Fingerabdruck. Browser warnen vor selbstsignierten Zertifikaten; vergleiche beim ersten Aufruf den Fingerabdruck im Browser mit dem angezeigten und akzeptiere das Zertifikat dann. 30 Tage vor Ablauf erscheint eine Warnung.

• Zertifikat hochladen: Zertifikat (Serverzertifikat zuerst, danach Zwischenzertifikate) und privater Schlüssel im PEM-Format, als Datei oder eingefügt. Der Schlüssel (RSA oder EC) darf nicht verschlüsselt sein (openssl pkey -in key.pem -out plain.pem). Geprüft wird: lesbar, Schlüssel passt zum Zertifikat, aktuell gültig, höchstens 64 KiB. Gespeichert wird unter data/tls/uploaded.crt und .key (600); der Schlüssel wird nie wieder ausgegeben.
• Neues selbstsigniertes Zertifikat: erzeugt mit openssl einen neuen Schlüssel und ein neues Zertifikat (Hostname, vollständiger Name, localhost, alle Adressen des Geräts) und verwendet es sofort, z. B. nach einer Änderung von Hostname oder Adresse oder um vom hochgeladenen Zertifikat zurückzuwechseln.

Hinter einem Reverse-Proxy (der selbst HTTPS anbietet) bleibt HTTPS hier meist aus; trage den Proxy in BUNKERBOX_TRUSTED_PROXIES ein (siehe Installation).

Zwei-Faktor-Anmeldung

Nach dem Passwort ist zusätzlich ein Code aus einer Authenticator-App nötig (TOTP nach RFC 6238: SHA-1, 6 Ziffern, 30 Sekunden; z. B. Aegis, Google Authenticator, 1Password, Bitwarden).

Einrichten

Zugriff → Sicherheit → Zwei-Faktor-Anmeldung → Einrichten:

1. QR-Code mit der App scannen oder den angezeigten Schlüssel von Hand eingeben. Der QR-Code wird auf dem Gerät selbst erzeugt; der Schlüssel verlässt Bunkerbox nur in Richtung deines Browsers.
2. Den 6-stelligen Code der App eingeben. Erst dann ist die Zwei-Faktor-Anmeldung aktiv. Eine nicht bestätigte Einrichtung verfällt nach 15 Minuten.
3. 10 Wiederherstellungscodes werden genau einmal angezeigt (kopieren oder als Textdatei herunterladen). Jeder gilt einmal anstelle des App-Codes. Gespeichert werden nur ihre Hashes.

Anmelden

Nach dem Passwort fragt die Anmeldeseite nach dem Code; über Wiederherstellungscode verwenden gilt stattdessen ein Wiederherstellungscode. Bis dahin erreicht die Sitzung nichts außer diesem Schritt (auch keine API und kein Terminal).

• Akzeptiert werden der aktuelle sowie der vorherige und der nächste Code (Uhrabweichung bis 30 Sekunden). Jeder Code gilt nur einmal.
• Nach 5 falschen Codes für ein Konto sind weitere Versuche 15 Minuten gesperrt.
• Anderes Konto bricht den Schritt ab und meldet ab.

Verwalten

• Neue Wiederherstellungscodes (mit einem gültigen Code): die bisherigen werden ungültig. Sind nur noch 3 oder weniger übrig, weist die Oberfläche darauf hin.
• Ausschalten (eigenes Konto, mit einem gültigen Code).
• Für alle Administratoren vorschreiben: nur möglich, wenn das eigene Konto die Zwei-Faktor-Anmeldung nutzt. Administratoren ohne Zwei-Faktor-Anmeldung müssen sie bei der nächsten Anmeldung direkt nach dem Passwort einrichten. Solange die Vorgabe gilt, lässt sie sich nicht ausschalten.
• Zurücksetzen (Tabelle Administratoren): ein anderer Administrator kann die Zwei-Faktor-Anmeldung eines Kontos mit Eingabe des Benutzernamens zurücksetzen, z. B. nach Verlust von Telefon und Wiederherstellungscodes.

Alle Schritte stehen im Audit-Log.

Alle Faktoren verloren

Hat der einzige Administrator Telefon und Wiederherstellungscodes verloren, als root an der Konsole bzw. per SSH:

nano /appdata/bunkerbox/data/security-state.json   # Eintrag des Kontos unter "twoFactor" löschen, ggf. "enforceForAdmins": false
systemctl restart bunkerbox

Benachrichtigung bei neuer Adresse

Bunkerbox merkt sich pro Administrator die letzten 20 Adressen erfolgreicher Anmeldungen. Meldet sich ein Administrator von einer bisher unbekannten Adresse an, wird das Ereignis Anmeldung von neuer Adresse ausgelöst (E-Mail, wenn unter Benachrichtigungen aktiviert). Die allererste Anmeldung eines Kontos löst keine Meldung aus.

Ablage

data/security-state.json (600): TOTP-Schlüssel (für die Prüfung nötig), Hashes der Wiederherstellungscodes, zuletzt verwendeter Zeitschritt (Schutz gegen Wiederverwendung), Vorgabe für alle Admins und bekannte Adressen.

API

Methode	Pfad	Beschreibung
GET	/api/security	SecurityOverview (HTTPS und Zwei-Faktor)
GET/PUT	/api/security/https	HttpsSettings / UpdateHttpsRequest (enabled, port, redirectHttp)
POST	/api/security/https/certificate	UploadCertificateRequest (certificatePem, privateKeyPem) -> HttpsSettings; 422 bei ungültigem Paar
POST	/api/security/https/selfsigned	neues selbstsigniertes Zertifikat -> HttpsSettings
GET	/api/security/2fa	TwoFactorOverview (Vorgabe, alle Admins)
PUT	/api/security/2fa/policy	{ enforceForAdmins }; 409 ohne eigene Zwei-Faktor-Anmeldung
POST	/api/security/2fa/enroll	TwoFactorEnrollment (secret, otpauthUri, qrSvg) für das eigene Konto
POST	/api/security/2fa/confirm	{ code } -> RecoveryCodes
POST	/api/security/2fa/disable	{ code } (eigenes Konto)
POST	/api/security/2fa/recovery-codes	{ code } -> neue RecoveryCodes
DELETE	/api/security/2fa/users/[user]	Zwei-Faktor-Anmeldung eines anderen Admins zurücksetzen
GET	/api/auth/2fa	offene Sitzung: SecondFactorChallenge (verify oder enroll)
POST	/api/auth/2fa/verify	{ code } (TOTP oder Wiederherstellungscode) -> MeResponse; 403 falscher Code, 429 gesperrt
POST	/api/auth/2fa/enroll, /api/auth/2fa/confirm	Einrichtung bei Vorgabe während der Anmeldung; confirm -> { me, codes }