rustguac is designed with a security-first approach. This document covers all security features and their implementation.

When a [tls] section is present in the config, rustguac serves HTTPS using rustls (a modern, memory-safe TLS implementation). The install script generates a self-signed certificate by default.

[tls]
cert_path = "/opt/rustguac/tls/cert.pem"
key_path = "/opt/rustguac/tls/key.pem"

Generate a certificate:

rustguac generate-cert --hostname your-hostname.example.com --out-dir /opt/rustguac/tls

The connection between rustguac and guacd can also be encrypted with TLS. When guacd_cert_path is set, rustguac connects to guacd over TLS, trusting the specified certificate. The same self-signed cert can serve both purposes.

[tls]
cert_path = "/opt/rustguac/tls/cert.pem"
key_path = "/opt/rustguac/tls/key.pem"
guacd_cert_path = "/opt/rustguac/tls/cert.pem"

guacd must be started with matching TLS flags:

guacd -b 127.0.0.1 -l 4822 -L info -f -C /opt/rustguac/tls/cert.pem -K /opt/rustguac/tls/key.pem

The install script configures both sides automatically.

All session targets are validated against CIDR allowlists before connections are made. Hostnames are resolved and every returned IP must match at least one allowed CIDR range.

ssh_allowed_networks = ["127.0.0.0/8", "::1/128", "10.0.0.0/8"]
rdp_allowed_networks = ["127.0.0.0/8", "::1/128", "10.0.0.0/8"]
web_allowed_networks = ["127.0.0.0/8", "::1/128"]

Default: localhost only — all three default to ["127.0.0.0/8", "::1/128"], preventing SSRF attacks out of the box.

rustguac supports two parallel authentication paths. See Roles and Access Control for the full role system.

• Keys are 256-bit random values (64 hex characters)
• Stored as SHA-256 hashes in SQLite — the plaintext key is only shown once at creation
• Supported in Authorization: Bearer <key>, X-API-Key: <key> headers, and ?key=<key> query parameter (WebSocket fallback)
• Optional IP allowlist (comma-separated CIDR ranges)
• Optional expiry timestamp (ISO 8601)
• API key admins always have full admin-level access

• Session tokens are 256-bit random values, stored in SQLite with a TTL
• Cookie: rustguac_session with HttpOnly, Secure (when TLS enabled), SameSite=Lax
• Configurable TTL (default: 24 hours)
• PKCE and nonce validation on every login flow
• Works with any OIDC provider (JumpCloud, Okta, Azure AD, Google, Keycloak, etc.)

Per-IP rate limiting is applied to all endpoints using tower_governor:

Rate limiting uses the resolved client IP (honoring trusted_proxies for X-Forwarded-For).

All responses include the following headers:

rustguac logs security-relevant events via the tracing framework:

• Authentication failures (API key and OIDC)
• Session creation, connection, and termination
• WebSocket connect/disconnect events
• Admin operations (user management, key rotation)
• Client IP addresses (resolved via trusted proxies)

• Pending timeout — sessions that don't receive a WebSocket connection within 60 seconds (configurable) are automatically cleaned up
• Maximum duration — active sessions are terminated after 8 hours (configurable) to prevent abandoned sessions
• Session ownership — non-admin users can only terminate their own sessions
• Share tokens — read-only or collaborative access via time-limited share URLs

All database queries use parameterised statements via rusqlite's params! macro. No string concatenation is used in SQL queries.

Recording file access validates filenames to block path traversal (/, \, ..). The Vault address book also validates entry and folder names (alphanumeric, hyphens, underscores, dots only; length 1-64).

The web UI uses DOM API methods (createElement, textContent, appendChild) instead of innerHTML for user-supplied content. Combined with the CSP header, this prevents cross-site scripting.

HTTP request bodies are limited to 64KB to prevent memory exhaustion attacks.

When trusted_proxies is configured, rustguac extracts the real client IP from the X-Forwarded-For header for connections originating from trusted proxy CIDRs. This ensures correct IP-based rate limiting and audit logging behind reverse proxies.

trusted_proxies = ["127.0.0.1/32"]

• Vault credentials — address book entries are read server-side from Vault. Connection passwords and private keys are never sent to the browser.
• API keys — only the SHA-256 hash is stored. The plaintext key is shown once at creation and cannot be retrieved.
• OIDC client secret — can be provided via OIDC_CLIENT_SECRET environment variable instead of the config file.
• LUKS encryption key — stored in Vault, passed to cryptsetup via stdin (never on the command line or on disk).
• Ephemeral SSH keys — the private key exists only in memory during the guacd handshake. It is never stored on disk or returned by the API.