Skip to content

Security

Jump to bottom
katana edited this page May 15, 2026 · 2 revisions

Security

Encryption

All communication between the server and agents is encrypted with AES-256-GCM.

  • Every message uses a fresh random 12-byte nonce
  • The nonce is prepended to the ciphertext
  • The shared 32-byte key is never transmitted, it must be distributed out of band
  • There is no key exchange protocol; compromise of the key compromises all agent sessions

Agent Authentication

Outbound Go agents connect over QUIC/UDP. The TLS certificate material is derived from the shared key and the client verifies the expected certificate. The agent then sends an HMAC authentication token derived from the same key before registration.

Bind-mode agents use length-prefixed AES-GCM frames over TCP. A bind agent registers only after the server can decrypt valid messages using the shared key.

If authentication or decryption fails, the connection is closed immediately. An attacker without the key cannot register as an agent.

Dashboard Authentication

The web dashboard uses cookie-based sessions.

Mechanism Details
Session cookie tunnel_auth, HTTP-only
CSRF token Required on all state-changing requests, 5-minute expiry
Session timeout 30 minutes of inactivity (configurable)
Login rate limiting Per-IP lockout after repeated failures

API Token Security

REST API tokens use the tun_ prefix followed by 32 random bytes encoded as base64.

  • Tokens are scoped: read, write, or admin
  • Tokens support an optional TTL
  • Tokens are stored in memory only and are lost on server restart
  • Revoke tokens at any time via the dashboard or the token revoke REPL command

Connection Limits

To limit abuse from compromised or rogue agents:

  • Maximum 5 simultaneous connections per source IP
  • Maximum 100 total connected agents
  • Per-IP rate limiting on new agent transport connections

Privilege Separation

  • Agents run without any special privileges. Standard mode needs outbound UDP access to the server agent port, default 2048.
  • The server requires root on Linux/macOS (for iptables and raw sockets) or Administrator on Windows (for WinDivert).

Never run agents with elevated privileges unless your specific use case requires it.

Input Validation

The server validates all user-supplied input at API and REPL boundaries:

Input Validation
Hostnames RFC-compliant hostname check
Port numbers Range check (1-65535)
Subnet CIDRs Valid CIDR notation
Tag strings Length and character restrictions
Keys Must decode to exactly 32 bytes

Key Rotation

Rotate the encryption key at any time from the REPL:

rotate-key

This generates a new random key and applies it immediately. All existing agent connections that were authenticated with the old key will need to reconnect with the new key.

Responsible Use

Rosemary should only be used on systems you own or have explicit written permission to access. Unauthorized use is prohibited.

Use only on systems you own or have explicit written permission to test. Unauthorized use is prohibited.

Clone this wiki locally