socAdmin docs
deploy Security model

Security model

What socAdmin protects, how, and what stays your responsibility.

Database credentials

  • Stored encrypted at rest with AES-256-GCM, per user.
  • The encryption key is generated on first start and kept in socadmin.db.
  • Never written to logs.

Accounts and sessions

  • Passwords hashed with bcrypt, policy of 10+ characters with mixed case, a digit and a special character.
  • 5 failed sign-ins for the same email and IP block sign-in for 15 minutes.
  • Short-lived access tokens (15 minutes) and refresh tokens (7 days), rotated on use, stored in HttpOnly cookies.
  • Password changes and resets revoke the user’s refresh tokens.
  • Each install gets a random, non-guessable API path.

Requests

  • CSRF protection on every request that changes state.
  • Security headers on every response: Content-Security-Policy, X-Frame-Options: DENY, and HSTS when served over HTTPS.
  • A general limit of 200 API requests per minute per IP.
  • An optional IP whitelist, managed by admins.
  • Proxy headers (X-Forwarded-For, X-Real-IP) are ignored unless the request comes from a TRUSTED_PROXY, so clients can’t spoof their IP.

Network access from socAdmin

socAdmin connects to whatever host a user enters, which could be abused to reach internal services. To limit this:

  • Cloud metadata addresses (169.254.0.0/16) and link-local addresses are always blocked.
  • In Docker, loopback and private ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) are blocked unless ALLOW_PRIVATE_NETWORKS=true.
  • Hostnames such as Compose service names are allowed.

Audit logs

socAdmin writes one line per security-relevant event to standard output: sign-ins and failures, database connections, queries (duration, row count, success), imports, exports, admin and security changes.

Logs never contain passwords, tokens, emails, query text or row data.

2026-10-18T09:12:44Z [AUTH] action=login user_id=1 ip=203.0.113.7
2026-10-18T09:12:51Z [CONNECT] user_id=1 ip=203.0.113.7 type=mysql target=mysql:3306 status=ok

Container

  • Runs as the non-root user socadmin.
  • Works with a read-only root filesystem (read_only: true plus a tmpfs on /tmp).
  • Persistent state only in /data.

Your responsibility

  • Serve socAdmin over HTTPS, and don’t expose it directly to the internet.
  • Give socAdmin database users only the privileges they need.
  • Keep the image up to date.
  • Protect and back up /data.

See Production setup for the configuration.