Skip to content

Admin-security-model.md

Latest commit

 

History

History
93 lines (59 loc) · 5.67 KB

Admin-security-model.md

File metadata and controls

93 lines (59 loc) · 5.67 KB

SentinelGate Admin API Security Model

The Decision

SentinelGate's admin API and dashboard have no authentication. Access control is delegated entirely to the network layer.

This is an intentional architectural decision, not a missing feature.

Why No Admin Authentication

The admin API never had authentication

The original security model was a localhost check: if r.RemoteAddr is 127.0.0.1 or ::1, access is granted unconditionally. No credentials, no tokens, no sessions.

This is not authentication — it's a network-level restriction implemented at the application layer. The security was always delegated to the network (only loopback can reach it).

Docker Desktop breaks the localhost check

Docker Desktop on macOS, Windows, and Linux does not preserve RemoteAddr as localhost during port forwarding. The container sees arbitrary IP addresses (in our testing, even a Google IP 142.250.129.141 caused by Docker Desktop + NordVPN interaction).

This makes the admin API and dashboard completely inaccessible from the host.

Adding authentication would be counterproductive

Adding real admin auth (credentials, login UI, session management, password reset) would:

  • Increase attack surface — login flows, session storage, password hashing, reset mechanisms are all potential vulnerabilities
  • Duplicate what reverse proxies already do — Nginx + basic auth, Traefik + middleware, Caddy + auth all solve this better
  • Complicate onboarding — for zero practical benefit in the vast majority of deployments
  • Add complexity for little benefit — in containerized environments, the network layer (Docker bridge, Kubernetes NetworkPolicy, firewall) already controls who can reach the port

The admin API controls policies, not data

The admin API manages policy rules, identities, the kill switch, and audit logs (which contain tool call metadata and may include tool response content). It does not handle end-user data, PII storage, or payments. In properly configured environments, an attacker who reaches the admin API has already bypassed the network perimeter.

Industry Precedent

This is the standard security model for infrastructure tools:

Tool Admin Auth Security Model
Prometheus Optional basic auth (since v2.24, via web.config.yml) Most deployments rely on network isolation, reverse proxy
Redis Optional (off by default, protected mode since 3.2) Network isolation, firewall
Elasticsearch Enabled by default since 8.0 (free tier) Was network-only in OSS versions; now has built-in auth
Grafana Default admin/admin Most deployments never change it
Portainer Basic auth Often exposed without changing defaults
Traefik Dashboard None by default Middleware for auth

The pattern across infrastructure tools is consistent: even when authentication exists, the primary security boundary is the network. Prometheus added optional basic auth in 2021 but most deployments still rely on network isolation.

The Three Deployment Tiers

Tier 1: Bare Metal / Local Development

  • SENTINEL_GATE_ADMIN_OPEN is not set
  • Admin API is localhost-only (original behavior)
  • No action required

Tier 2: Docker / Kubernetes / Containers

  • SENTINEL_GATE_ADMIN_OPEN=true is set in the container config
  • Admin API accepts connections from any IP that can reach the port
  • Security relies on Docker network isolation (containers are on an internal bridge network)
  • Important: Docker's -p 8080:8080 binds to 0.0.0.0:8080 by default — accessible from all network interfaces, not just localhost. Use -p 127.0.0.1:8080:8080 to restrict to localhost only

Tier 3: Production on Public Servers

  • Same as Tier 2, plus one of:
    • Firewall: restrict port 8080 to trusted IPs
    • Reverse proxy with auth: Nginx/Caddy/Traefik in front of SentinelGate with basic auth or SSO
    • SSH tunnel: ssh -L 8080:localhost:8080 yourserver
    • VPN: access only via private network

Risk Matrix

Environment ADMIN_OPEN Port Exposed Risk Action
Local machine, bare metal not set localhost only None None
Local machine, Docker true 0.0.0.0:8080 by default Low (use -p 127.0.0.1:8080:8080 on shared networks) Bind to localhost if on shared/public WiFi
Private server, Docker true internal port Low Firewall recommended
Public server, Docker true public port HIGH Firewall mandatory or reverse proxy with auth

The SENTINEL_GATE_ALLOWED_HOSTS Variable

Separate from the admin API issue, the MCP proxy endpoint (/mcp) has DNS rebinding protection that validates the Host header. By default, only localhost, 127.0.0.1, and ::1 are accepted.

In Docker/Kubernetes, services connect via hostname (e.g., sentinel-gate, sentinel-gate.default.svc.cluster.local). The SENTINEL_GATE_ALLOWED_HOSTS environment variable (comma-separated) adds these hostnames to the allowlist.

The semantics are additive: localhost is always allowed, custom hosts extend the default set. This prevents the dangerous "replace" behavior where setting custom hosts would accidentally lock out localhost.

Summary

The right layer for admin access control is the network, not the application. SentinelGate provides the tools (SENTINEL_GATE_ADMIN_OPEN, SENTINEL_GATE_ALLOWED_HOSTS) to work correctly in containerized environments while maintaining clear documentation about the security implications. This is consistent with how most infrastructure tooling approaches the problem — even tools that offer optional authentication (Prometheus, Redis) primarily rely on network isolation in practice.