Skip to content

enterprise-enrollment.md

Latest commit

 

History

History
218 lines (152 loc) · 8.66 KB

enterprise-enrollment.md

File metadata and controls

218 lines (152 loc) · 8.66 KB

Enterprise Enrollment Guide

This guide walks through enrolling a Clawdstrike Desktop Agent with your enterprise infrastructure. Enrollment binds a standalone agent to your organization's tenant, provisioning it with NATS credentials for policy sync, telemetry, and fleet management.

After enrollment, the agent transitions from standalone to connected mode automatically. For background on deployment modes, see Adaptive Architecture.

Prerequisites

Before starting, confirm you have the following:

Requirement Details
Desktop Agent installed Running in standalone mode on the target machine
Enterprise infrastructure NATS cluster, hushd, Control API, and external NATS provisioner service deployed and accessible
Enrollment token A single-use token generated by your enterprise administrator
Network access HTTPS access from the agent machine to the Control API endpoint

Tip: The agent does not need direct access to NATS before enrollment. Enrollment is performed over HTTPS to the Control API. NATS credentials are provisioned as part of the enrollment response.

Step 1: Generate an Enrollment Token (Admin)

Enterprise administrators generate enrollment tokens via the Control API or Control Console. Each token is single-use and expires after 24 hours by default (configurable at creation time).

Via the Control API:

TENANT_ID="00000000-0000-0000-0000-000000000000"
TOKEN="control-api-admin-token"

curl -fsS -X POST \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"expires_in_hours":24}' \
  "https://api.acme.clawdstrike.cloud/api/v1/tenants/${TENANT_ID}/enrollment-tokens" | jq .

Example response:

{
  "enrollment_token": "cset_...",
  "expires_at": "2026-02-28T15:04:05Z"
}

Via the Control Console (if enabled in your deployment):

  1. Navigate to Fleet Management > Agents in the Control Console.
  2. Select Generate Enrollment Token.
  3. Copy the token (format: cset_...).
  4. Deliver the token to the agent operator via a secure channel (email, internal messaging, etc.).

Warning: Enrollment tokens are sensitive credentials. They are single-use, but an attacker with a valid token could enroll an unauthorized agent. Deliver tokens through secure, authenticated channels.

Step 2: Install the Desktop Agent

If the Desktop Agent is not already installed, follow the Desktop Agent Deployment Guide to install and verify it is running in standalone mode.

Confirm the agent is running:

curl -fsS http://127.0.0.1:9878/api/v1/agent/health | jq .

Expected output should show daemon.state as running.

Step 3: Run the Enrollment Command

Use the agent's local API to initiate enrollment:

CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/clawdstrike"
AGENT_TOKEN="$(tr -d '[:space:]' < "${CONFIG_DIR}/agent-local-token")"

curl -fsS -X POST \
  -H "Authorization: Bearer ${AGENT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "enrollment_token": "cset_...",
    "control_api_url": "https://api.acme.clawdstrike.cloud"
  }' \
  http://127.0.0.1:9878/api/v1/enroll | jq .

The enrollment process performs the following steps automatically:

  1. Generates a fresh Ed25519 keypair for the agent (stored at ${XDG_CONFIG_HOME:-$HOME/.config}/clawdstrike/agent.key).
  2. Sends the public key and enrollment token to the Control API.
  3. The Control API validates the token, registers the agent, and provisions NATS credentials.
  4. The agent persists NATS settings (nats_url, subject_prefix, token, agent_id, nats_account) in agent.json.
  5. The agent marks enrollment state (enrolled, agent_uuid, tenant_id) in agent.json.
  6. The API returns restart_required: true so enterprise features initialize on restart.

A successful response looks like:

{
  "status": "enrolled",
  "agent_uuid": "a1b2c3d4-...",
  "tenant_id": "2f9f15f9-...",
  "restart_required": true,
  "message": "Restart the agent to activate enterprise features (policy sync, telemetry, posture commands)"
}

Step 4: Verify Enrollment Success

Check the enrollment status:

curl -fsS \
  -H "Authorization: Bearer ${AGENT_TOKEN}" \
  http://127.0.0.1:9878/api/v1/enrollment-status | jq .

Expected output:

{
  "enrolled": true,
  "agent_uuid": "a1b2c3d4-...",
  "tenant_id": "2f9f15f9-...",
  "enrollment_in_progress": false
}

Confirm the agent health endpoint is healthy:

curl -fsS http://127.0.0.1:9878/api/v1/agent/health | jq .

The response should show status: "ok" and a live daemon/session block.

Step 5: Test Policy Sync

Verify that the agent is receiving policies from the enterprise:

  1. Check the current policy version in the agent health response (last_policy_version field).
  2. Ask your enterprise administrator to publish a policy update.
  3. Within a few seconds, the agent should reflect the updated policy version.

You can also inspect the local policy cache:

cat "${XDG_CONFIG_HOME:-$HOME/.config}/clawdstrike/policy-cache.yaml"

This file stores the most recently synced policy payload from hushd.

Troubleshooting

Token Expired

Symptom: Enrollment returns an error indicating the token has expired.

Cause: Enrollment tokens expire after 24 hours by default. The token was generated too long ago.

Resolution: Request a new enrollment token from your enterprise administrator. Tokens cannot be renewed; a fresh token must be generated.

Network Unreachable

Symptom: Enrollment fails with a connection error to the Control API.

Cause: The agent cannot reach the enterprise Control API endpoint over HTTPS.

Resolution:

  1. Verify network connectivity: curl -fsS https://api.acme.clawdstrike.cloud/health
  2. Check for firewall rules blocking outbound HTTPS (port 443).
  3. If behind a proxy, configure the HTTPS_PROXY environment variable before enrollment.
  4. Verify the Control API URL is correct (check with your administrator).

Enrollment Fails Mid-Way

Symptom: The enrollment command returns an error after partially completing. The agent may be in an inconsistent state.

Cause: A network interruption or crash occurred between credential provisioning and configuration update.

Resolution: Restart the agent. On startup, the agent performs a consistency check:

  • If NATS credentials exist but the mode is still standalone, the agent attempts to connect with the stored credentials. If successful, it completes the transition to connected mode automatically.
  • If NATS connection fails with an authentication/authorization error (for example revoked or invalid credentials), the agent clears enrollment/NATS state and remains in standalone mode. You can then retry enrollment with a new token.
  • If the failure is a transient network/connectivity error, the agent keeps enrollment settings and retries on next startup.

Agent Shows as Disconnected

Symptom: The enterprise Control Console shows the agent as stale or dead even though it was recently enrolled.

Cause: Heartbeats are not reaching the enterprise. Possible reasons include:

  • NATS connectivity issues (firewall, DNS, or credential problems)
  • The agent process is not running
  • The NATS credentials were revoked

Resolution:

  1. Check agent health: curl -fsS http://127.0.0.1:9878/api/v1/agent/health | jq .
  2. Verify enrollment state remains enrolled: true via /api/v1/enrollment-status.
  3. Check for NATS connectivity errors in the agent logs.
  4. If credentials were revoked, the agent transitions back to standalone mode. Re-enroll with a new token.

Re-Enrollment

To re-enroll an agent (e.g., after moving to a different tenant or after revocation):

  1. The agent must be in standalone mode. If it is still in connected mode, the enterprise administrator should revoke the agent first, or you can manually reset the configuration:

    # Remove persisted enrollment/NATS fields from the local settings file.
CONFIG_JSON="${XDG_CONFIG_HOME:-$HOME/.config}/clawdstrike/agent.json"
jq '.enrollment = {} | .nats = {}' "${CONFIG_JSON}" > "${CONFIG_JSON}.tmp" && mv "${CONFIG_JSON}.tmp" "${CONFIG_JSON}"

    Then restart the agent -- it will detect the missing credentials and revert to standalone mode.

  2. Obtain a new enrollment token from the target tenant's administrator.

  3. Run the enrollment command again (Step 3 above).

Related