Agent Communication Security

How the agent communicates securely with the central server.

Transport Security

All agent-to-server communication uses HTTPS/TLS:

  • The agent uses the requests library with verify=True (certificate validation enabled)
  • Request timeout: 15 seconds
  • Self-signed certificates can be used by placing the CA cert in the certs/ directory

Authentication

Every authenticated request includes three headers:

  • X-API-Key — 48-byte URL-safe token (generated during enrollment)
  • X-Device-ID — Device UUID
  • X-Agent-Version — Agent software version

API Key Security

  • Keys are generated using secrets.token_urlsafe(48) (cryptographically secure)
  • The plaintext key is returned to the agent only once during enrollment
  • The server stores a SHA-256 hash — the plaintext is never stored
  • Lost keys cannot be recovered; the device must be re-enrolled
  • Retired devices have their keys invalidated (API returns 403)

Offline Resilience

When the server is unreachable:

  • The agent sets offline_mode = True
  • Policy enforcement continues using the last-known policy.json
  • Alerts are queued to disk in the queue/ directory
  • When connectivity resumes, queued alerts are pushed in batches of up to 50
  • The heartbeat cycle retries every 60 seconds

Request Validation

The server validates on every request:

  1. X-API-Key header is present
  2. X-Device-ID header is present
  3. Device exists in the database
  4. SHA-256 hash of the provided key matches the stored hash
  5. Device status is not retired