Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Concepts › Agent-Manager Trust

Agent-Manager Trust

Agent / Manager trust

SharedStatus: SUPPORTED as implemented enrollment/auth behaviorAudience: security engineer, deployment engineer

Purpose

Explain how an Agent becomes trusted enough to sync policy and upload telemetry, without describing exploit internals.

Concept

Trust is explicit admission plus transport verification.

Typical production shape:

  1. Administrator authenticates.
  2. Administrator pre-registers or creates an Agent (POST /api/v1/agents/pre-register, POST /api/v1/agents/create).
  3. Agent presents a one-time bootstrap token (AGENT_TOKEN / AGENT_PRE_TOKEN; YAML server.token stays empty).
  4. Agent calls POST /api/v1/agents/register (rate limited; Enterprise resolves registration client IP).
  5. Subsequent heartbeat and sync use Agent JWT (POST /api/v1/agents/heartbeat, POST /api/v1/agents/token/refresh).

agents.auto_register is false in the example and must remain false in production.

Pre-register security_level: standard (default) or maximum (mTLS). Invalid values return 400. maximum can include CA material so the Agent presents a client certificate. Some Agent routes use mTLS-capable wrappers in Enterprise (heartbeatWithMTLS, classifiedAgentAuthWithMTLS).

Hosting bootstrap unsets AGENT_PRE_TOKEN / AGENT_TOKEN from the process environment after load. Identity persists at ZWALL_AGENT_CREDENTIAL_PATH (Hosting: /var/lib/zwall-hosting/agent.identity).

Administrator API uses Authorization JWT. Browser session uses HttpOnly session_token. Those are not Agent tokens.

Data/control flow

Admin JWT → pre-register (hostname, expected_ip, optional profile/observation_only) → one-time pre-token to the node → Agent register → Agent JWT (TTL example auth.agent_token_ttl: 8h, supported comment range 4h–8h) → refresh when remaining lifetime below auth.agent_refresh_before (example 20m) with heartbeat-only grace auth.agent_expired_grace (example 2m).

Admin revocation: POST /api/v1/agents/:id/revoke-token plus revocation/rotation history GETs.

Register response pattern: token, agent_id, expires_at, is_temporary.

Community: a fourth registration-style enrollment is rejected (3-Agent limit).

Boundaries

  • server.verify_tls: true in example. allow_insecure_remote_tls is break-glass only.
  • Agent tokens are not administrator tokens; Hosting Agents still cannot receive rules after they are trusted.
  • Do not keep steady-state JWTs in YAML.
  • Secret custody for Manager JWT signing is pending final security acceptance.
  • This is not OIDC.

Edition differences

mTLS security_level: maximum wrappers and Hosting profile fields on pre-register are Enterprise. Community shares pre-register/create/register/heartbeat/refresh with the 3-Agent cap.

Common misconceptions

  • “Turning on auto_register is the production enroll path.” Example forbids it.
  • “The login JWT is what the Agent uses.” Different credential.
  • “maximum security_level is Hosting observation.” It is mTLS for Agent transport, not packet policy.
  • “Revoke token uninstalls the unit.” It revokes Agent JWT; systemd still runs until you stop it.