Security and Audit
This page summarizes how SelfDocHub protects access and data, and what it records in the audit log. Use it when you review a deployment.
Authentication model#
- Users sign in at
/login. The server returns a signed bearer token that the browser stores and sends asAuthorization: Bearer <token>. Because the token is attached explicitly instead of through a cookie, cross-site request forgery is not a risk for authenticated requests. - There is no server-side session store. Signing out forgets the token on the client. Token lifetime is
session_timeout, orremember_me_timeoutwith "Remember me". - Passwords are stored as bcrypt hashes only. Failed logins return one generic error, and attempts are rate-limited per login and client IP.
- Two-factor authentication (TOTP) and OIDC single sign-on are available. See Users and Two-Factor Auth and Single Sign-On (SSO).
- Every
/api/v1/...route needs a valid token and answers401without one. The page shell itself is served unconditionally, so access control happens at the API. - Service upload tokens are a separate mechanism. Only salted hashes are stored, raw tokens are shown once and never logged.
Secrets at rest#
Two-factor secrets, SSO client secrets and notification secrets are stored encrypted (AES-GCM) with a key derived from session_secret. Secrets are write-only: no API returns them. Changing session_secret makes them unreadable. See Configuration Reference.
HTTP hardening#
- Responses carry
Content-Security-Policy,X-Content-Type-Options,X-Frame-OptionsandReferrer-Policyheaders. - The web interface JavaScript is served from the application itself. No external CDN script is loaded by default.
- Read, write and idle timeouts are configurable.
- Uploaded pictures and export images are checked by content, SVG files are sanitized, and files are served with
nosniffand a policy that forbids scripts.
Try-It limits#
The Try-It proxy limits the request body to 1 MiB and the response to max_tryit_response_bytes, applies per-request timeouts, validates the target URL, never forwards Cookie or Authorization, and returns only allow-listed response headers. The target is chosen by the client, so deploy SelfDocHub where reaching internal hosts from users' Try-It requests is acceptable. See Try-It.
Notification targets#
Notification channels cannot reach loopback, private or link-local addresses unless you turn on notifications_allow_private_targets. See Notifications.
MCP#
MCP tokens are individually scoped, can be limited by IP, and every rejection is logged. Try-It through MCP has additional controls. See MCP Server and Try-It Through MCP.
HTTPS#
Serve SelfDocHub over HTTPS for anything beyond localhost. The copy buttons use the browser clipboard API, which exists only in a secure context. Over plain HTTP they fall back to a legacy method. See Installation.
Audit log#
Audit events are emitted as structured JSON log lines (one object per line, on stderr) for:
- login outcomes;
- spec publishing;
- admin changes to users, services, groups and teams;
- overlay changes, rebuilds and snapshot promotes;
- SSO events such as
sso_login_success,sso_login_denied,sso_link,sso_unlinkand provider changes; - label changes (
service_label_added,service_label_removed); - MCP events (
mcp_request_rejected,mcp_tryit_request,mcp_tryit_rejected,mcp_tryit_selection_saved).
Audit events carry metadata only. Passwords, session tokens, service tokens, MCP secrets, raw request bodies and generated tokens are never logged.
View the log with docker compose logs -f docs-hub.