Security & Authentication
Relevant source files
The following files were used as context for generating this wiki page:
HX-ProxyGroup implements a multi-layered security model to protect the control plane and managed proxy services. The system enforces authentication for all management operations, utilizes modern cryptographic hashing for credentials, and implements Time-based One-Time Password (TOTP) for sensitive features like the browser terminal.
Security boundaries are strictly defined between the management API, the Mihomo data plane, and public proxy listeners. The control plane operates under a principle of least privilege, specifically in the context of the privileged terminal helper which transitions to root execution only after strict validation.
Sources: SECURITY.md:1-10, AGENTS.md:57-61
Authentication Flow
Authentication follows a structured bootstrap process. An unconfigured instance requires a one-time token found in the admin-setup-token file within the data directory. Once configured, the system enforces session-based authentication using cookies and CSRF protection.
Administrator Login and Session Management
The login process issues an HttpOnly session cookie and a CSRF token. All mutating requests (POST, PUT, DELETE) must carry the X-CSRF-Token header to pass the authentication layer.
Security Layers and Boundaries
The project maintains distinct boundaries for different traffic types and management access.
| Boundary | Default Listener | Authentication Requirement |
|---|---|---|
| Management API | Loopback (127.0.0.1) | Mandatory (Session or API Key) |
| Mihomo Controller | Private Unix Socket | Mandatory (Socket Permissions) |
| Public Listeners | Configurable | Optional (Username/Password recommended) |
| Health Probes | Public | None (Unauthenticated) |
Sources: SECURITY.md:12-23, internal/api/auth_test.go:159-168
API Key Authentication
For automated scripts, the system supports API keys. These keys allow bypass of the CSRF requirement when provided via the Authorization: Bearer <key> or X-API-Key headers. API keys are hashed in the database and the plaintext is only displayed once during creation.
Sources: internal/api/auth_test.go:240-270, web/src/pages/settings-page.tsx:254-266
Browser Terminal Security
The browser terminal represents the most sensitive feature, as it grants command execution. Access requires a "step-up" verification using TOTP.
Terminal Access Requirements
- Authenticated Session: User must be logged in as an administrator.
- TOTP Verification: A recent 2FA verification is mandatory before the WebSocket session opens.
- Session Limits: Absolute limit of two hours and a maximum of two concurrent sessions.
- Privilege Transition: In production, the terminal helper creates a root PTY after validating the peer via
SO_PEERCRED.
Sources: SECURITY.md:32-48, SECURITY.md:65-75, internal/api/system_static_test.go:119-138
Data Protection
The system protects sensitive information through encryption and restricted access:
- Secrets Storage: Passwords use modern hashes. Secrets that must be recoverable (like node passwords) use AEAD encryption.
- Audit Logging: Structured open/close audit records are generated for terminal sessions, though command contents and secrets are excluded from logs.
- File Permissions: The database, master key, and configuration snapshots are restricted to the service account and administrators.
Sources: AGENTS.md:58-61, SECURITY.md:21-23, SECURITY.md:43-46
System Updates & Readiness
Updates involve downloading GitHub Releases and verifying SHA-256 checksums. The update process schedules a fixed upgrade action via the root-owned installer. If the readiness check fails for either the control plane or data plane, the system rolls back to the previous version.
Sources: web/src/pages/about-page.tsx:49-62, SECURITY.md:72-75
Security and authentication in HX-ProxyGroup prioritize the isolation of the management interface and the enforcement of multi-factor authentication for high-risk operations, ensuring system integrity even when exposed to complex network environments.