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 as Authorization: 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, or remember_me_timeout with "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 answers 401 without 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-Options and Referrer-Policy headers.
  • 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 nosniff and 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_unlink and 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.

Next steps#

Last updated: