Agent Enrollment

This guide covers the complete agent enrollment process, from generating enrollment tokens in the admin console to verifying successful enrollment and managing agent certificates.

Overview

The Tamandua agent enrollment process uses a secure token-based system:

1. Administrator generates an enrollment token in the admin console
2. Token is used during agent installation
3. Agent exchanges the token for credentials via CSR (Certificate Signing Request)
4. Agent receives a signed certificate and JWT for authentication
5. Agent connects to the backend using mTLS

┌─────────────┐     1. Generate Token      ┌─────────────┐
│   Admin     │ ─────────────────────────► │   Backend   │
│   Console   │ ◄───────────────────────── │   Server    │
└─────────────┘     Token returned         └──────┬──────┘
       │                                          │
       │  2. Provide token to agent               │
       ▼                                          │
┌─────────────┐     3. Token + CSR         ┌──────▼──────┐
│   Agent     │ ─────────────────────────► │  Enrollment │
│   Install   │ ◄───────────────────────── │     API     │
└─────────────┘     JWT + Certificate      └─────────────┘

Generate Enrollment Token

Via Admin Console

1. Log in to the Tamandua admin console
2. Navigate to Settings > Agents > Enrollment
3. Click Generate Token
4. Configure token options:

1. Click Create Token
2. Copy the token securely (displayed only once)

Via API

# Generate enrollment token via API
curl -X POST "https://tamandua.treantlab.org/api/v1/admin/enrollment-tokens" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "expires_in_hours": 24,
        "max_uses": 100,
        "tags": ["production", "datacenter-east"],
        "performance_profile": "balanced"
    }'

# Response:
{
    "token": "tam_enroll_abc123xyz789...",
    "expires_at": "2026-05-10T14:30:00Z",
    "max_uses": 100,
    "uses": 0
}

Token Formats

Enroll Agent

During Installation

The recommended approach is to provide the token during installation:

Windows

# The current MSI installs an unprovisioned agent and rejects token properties
msiexec /i tamandua-agent.msi /qn

# Enroll with the direct binary; token is prompted without echo
tamandua-agent.exe install

Linux

# After package installation; token is prompted without echo
sudo tamandua-agent install

macOS Preview/Experimental

# After preview PKG installation, if available for your release
sudo /Library/Application\ Support/Tamandua/tamandua-agent install \
    --server "wss://agents.tamandua.treantlab.org:8443/socket/agent"

Manual Enrollment

If the agent was installed without a token:

# Enroll; token is prompted without echo
tamandua-agent install

# With custom server URL (self-hosted)
tamandua-agent install \
    --server "wss://your-server.example.com:8443/socket/agent" \
    --enrollment-url "https://your-server.example.com"

Enrollment Options

For unattended enrollment, the launcher must write the token directly to the

agent's standard input and add --token-stdin. Never interpolate it into a

shell command, process argument list, diagnostic bundle, or log.

Verify Enrollment

Check Agent Status

# Windows
sc query TamanduaAgent

# Linux
sudo systemctl status tamandua-agent

# macOS Preview
sudo launchctl list | grep tamandua

Verify Certificate

# Check certificate exists
# Windows
dir "C:\ProgramData\Tamandua\config\cert.pem"

# Linux
ls -la /var/lib/tamandua/config/cert.pem

# macOS Preview
ls -la "/Library/Application Support/Tamandua/config/cert.pem"

# View certificate details
openssl x509 -in /var/lib/tamandua/config/cert.pem -text -noout

Verify in Admin Console

1. Log in to the admin console
2. Navigate to Agents > All Agents
3. Locate the new agent by hostname or agent ID
4. Verify status shows Online

Check Agent Logs

# Windows
Get-Content "C:\ProgramData\Tamandua\logs\agent.log" -Tail 50 | Select-String "enroll"

# Linux
sudo grep -i enroll /var/lib/tamandua/logs/agent.log

# macOS Preview
grep -i enroll "/Library/Application Support/Tamandua/logs/agent.log"

Certificate Management

Certificate Lifecycle

Tamandua uses short-lived certificates with automatic rotation:

Automatic Certificate Renewal

The agent automatically renews certificates before expiration:

1. Agent detects certificate approaching expiration (10 days before)
2. Agent generates new CSR (Certificate Signing Request)
3. CSR sent to enrollment API with existing JWT
4. New certificate issued and stored
5. Connection re-established with new certificate

Manual Certificate Renewal

If automatic renewal fails:

# Force certificate renewal (requires valid JWT)
tamandua-agent renew-certificate

# Or re-enroll; token is prompted without echo
tamandua-agent install

Certificate Files

View Certificate Details

# View certificate
openssl x509 -in /var/lib/tamandua/config/cert.pem -text -noout

# Check expiration
openssl x509 -in /var/lib/tamandua/config/cert.pem -enddate -noout

# Verify certificate chain
openssl verify -CAfile /var/lib/tamandua/config/ca-bundle.pem \
    /var/lib/tamandua/config/cert.pem

Re-Enrollment

When to Re-Enroll

• Certificate expired and auto-renewal failed
• Agent moved to different organization
• Security incident requiring credential rotation
• Corruption of agent credentials

Re-Enrollment Process

1. Generate a new enrollment token in the admin console
2. Stop the agent service
3. Remove existing credentials (optional but recommended)
4. Re-run enrollment

# Stop agent
sudo systemctl stop tamandua-agent  # Linux
Stop-Service TamanduaAgent          # Windows

# Remove old credentials (optional)
sudo rm /var/lib/tamandua/config/{cert,key,ca-bundle}.pem

# Re-enroll; token is prompted without echo
sudo tamandua-agent install

# Start agent
sudo systemctl start tamandua-agent

Bulk Re-Enrollment

For re-enrolling multiple agents:

1. Generate a multi-use token with appropriate usage limit
2. Deploy re-enrollment script via your management tool

#!/bin/bash
# The management tool must connect a secret directly to this script's stdin.

# Stop agent
sudo systemctl stop tamandua-agent

# Clear old state
sudo rm -f /var/lib/tamandua/config/{cert,key}.pem

# Re-enroll from redirected stdin; no token argument or environment variable
sudo tamandua-agent install --token-stdin

# Restart
sudo systemctl start tamandua-agent

Token Security

Best Practices

1. Short expiration: Use 24-hour tokens for planned deployments
2. Limited uses: Set max_uses appropriate to your deployment
3. Secure transmission: Never send tokens via email; use secure channels
4. Rotate regularly: Don't reuse tokens across deployments
5. Audit token usage: Review enrollment logs regularly

Token Revocation

If a token is compromised:

1. Navigate to Settings > Agents > Enrollment Tokens
2. Locate the compromised token
3. Click Revoke
4. Review enrolled agents for unauthorized entries

# Revoke token via API
curl -X DELETE "https://tamandua.treantlab.org/api/v1/admin/enrollment-tokens/TOKEN_ID" \
    -H "Authorization: Bearer YOUR_API_KEY"

Troubleshooting

Token Validation Failed

Error: "Invalid or expired enrollment token" Causes:

• Token has expired
• Token has reached usage limit
• Token was revoked
• Network issues reaching enrollment API

Solution:

1. Generate a new token in the admin console
2. Verify network connectivity:

   curl -v https://tamandua.treantlab.org/api/v1/agent/health
   

1. Check system clock is accurate (important for token validation)

Certificate Signing Failed

Error: "CSR signing failed" or "Certificate issuance error" Causes:

• Organization enrollment quota exceeded
• Backend CA service unavailable
• Invalid CSR format

Solution:

1. Check organization quotas in admin console
2. Verify backend services are running
3. Check agent logs for detailed error:

   sudo grep -i "csr\|certificate" /var/lib/tamandua/logs/agent.log
   

Agent Not Appearing in Console

Causes:

• Enrollment succeeded but WebSocket connection failed
• Firewall blocking agent communication
• DNS resolution issues

Solution:

1. Verify enrollment completed:

   ls -la /var/lib/tamandua/config/cert.pem
   

1. Check WebSocket connectivity:

   curl -v https://agents.tamandua.treantlab.org:8443/socket/agent
   

1. Review agent logs for connection errors

Certificate Renewal Failed

Error: "Auto-renewal failed" or "JWT expired" Causes:

• JWT expired before renewal window
• Network outage during renewal
• Backend certificate service unavailable

Solution:

1. Re-enroll with new token
2. If JWT is still valid, force renewal:

   sudo tamandua-agent renew-certificate
   

Permission Denied During Enrollment

Error: "Permission denied" or "Access denied" Causes:

• Not running as administrator/root
• File system permissions incorrect
• SELinux/AppArmor blocking

Solution:

# Run as root; token is prompted without echo
sudo tamandua-agent install

# Check SELinux (RHEL/CentOS)
sudo ausearch -m avc -ts recent | grep tamandua

# Check AppArmor (Ubuntu/Debian)
sudo dmesg | grep apparmor | grep tamandua

Multi-Organization Enrollment (MSSP)

For managed service providers managing multiple organizations:

Generate Multi-Org Token

# Via API with organization scope
curl -X POST "https://tamandua.treantlab.org/api/v1/admin/enrollment-tokens" \
    -H "Authorization: Bearer MSSP_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "organization_id": "customer-org-id",
        "expires_in_hours": 48,
        "max_uses": 50
    }'

Customer-Specific Tokens

Each customer organization should have separate tokens:

1. Navigate to Organizations > [Customer Org] > Enrollment
2. Generate token scoped to that organization
3. Provide token to customer for deployment

Enrollment Segregation

Agents enrolled with organization-scoped tokens:

• Only visible to that organization's users
• Policies and rules are organization-specific
• Telemetry is segregated by organization

Next Steps

• Agent Configuration - Configure agent settings
• Agent Overview - Return to agent overview
• Windows Installation - Platform-specific installation