Agents

Agents

SSL-CLM Agents are lightweight Java services deployed on remote hosts to execute certificate operations locally. They enable secure, distributed lifecycle management for infrastructure that isn’t directly API-accessible from the platform.

Navigation: Sidebar → Infrastructure → Agents

---

Agent List

The main view displays all registered agents:

Column	Description
Name	Agent display name or label
Host	Hostname of the machine running the agent
OS	Operating system and version
Stores	Number of certificate stores managed by this agent
Status	Connection status badge
Last Seen	Time since last heartbeat
Actions	View, Disable, Delete

Filtering

• Search — Filter by name or hostname
• Status Dropdown — Filter by: All Statuses, ONLINE, OFFLINE, BOOTSTRAPPING, DISABLED

---

Agent Statuses

Status	Color	Meaning
ONLINE	Green	Agent is connected, heartbeat active, ready to execute jobs
BOOTSTRAPPING	Blue	Agent recently registered, completing initial setup
OFFLINE	Red	No heartbeat received within timeout threshold
DISABLED	Gray	Manually disabled by administrator — will not receive jobs
EXPIRED	Red	Agent’s mTLS certificate has expired — requires re-bootstrap
SAFE_MODE	Orange	Restricted operation due to auth failure — fail-closed state

---

Registering a New Agent

Step 1 — Generate Bootstrap Token

1. Click + Register Agent
2. Enter the agent hostname
3. Click Generate Token
4. Copy the one-time bootstrap token

Bootstrap tokens are:

• One-time use — Consumed upon first agent registration
• Time-limited — Expire after a configurable window (default: 24 hours)
• Irrevocable — Once used, cannot be reused

Step 2 — Install Agent on Target Host

Download the agent JAR from the platform or obtain it from your deployment package:

ssl-clm-agent-<version>.jar

System requirements:

• Java 21+
• Outbound HTTPS access to the SSL-CLM platform
• No inbound ports required

Step 3 — Start the Agent

Linux:

java -jar ssl-clm-agent.jar \
  --backend.url=https://ssl-clm.example.com:8080 \
  --bootstrap.token=YOUR_BOOTSTRAP_TOKEN

Windows (PowerShell):

$env:API_URL = "https://ssl-clm.example.com:8080"
$env:AGENT_BOOTSTRAP_TOKEN = "YOUR_BOOTSTRAP_TOKEN"
java -jar ssl-clm-agent.jar

Step 4 — Verify Registration

After starting, the agent:

1. Sends the bootstrap token to the platform
2. Receives a unique agent ID and mTLS client certificate
3. Stores credentials locally
4. Begins heartbeat reporting
5. Appears in the Agents list with BOOTSTRAPPING → ONLINE status

---

Agent Detail View

Click any agent row to open its detail page:

Agent Information

Field	Description
Agent ID	Unique identifier
Hostname	Machine hostname
Status	Current connection state
Bootstrap Completed	Whether initial registration completed
Last Heartbeat	Most recent heartbeat timestamp
Created	Registration timestamp

Certificate Information (mTLS)

Field	Description
Fingerprint	SHA-256 fingerprint of the agent’s client certificate
Expires	Expiry date of the mTLS certificate
Days Until Expiration	Remaining validity

Version Information

Field	Description
Version	Agent software version
Build Date	When the agent binary was built
Git Commit	Source commit hash

Capabilities

The agent reports its supported capabilities during registration:

• CA operations (ISSUE_CERT, REVOKE_CERT, CA_REFRESH)
• Store operations (DEPLOY_CERT, DISCOVER_STORE, BIND_CERT)
• Discovery operations (NETWORK_SCAN)

Associated Stores

List of certificate stores that are assigned to this agent.

Recent Jobs

History of jobs executed by this agent with status and timestamps.

---

Communication Model

Pull-Based Architecture

Agents use a pull-based model — they poll the platform for jobs at configurable intervals:

Agent → (HTTPS Poll) → Platform: "Any jobs for me?"
Platform → Agent: Job payload (or empty)
Agent → (executes locally) → Result
Agent → (HTTPS POST) → Platform: Job result

No inbound firewall rules required on the agent host.

Default Intervals

Operation	Default Interval
Heartbeat	30 seconds
Job polling	10 seconds
Health check	5 minutes

mTLS Authentication

After bootstrap, all communication uses mutual TLS:

• Agent authenticates to platform with its client certificate
• Platform authenticates to agent with its server certificate
• All traffic encrypted end-to-end

---

Agent Configuration

Configuration File (agent.properties)

# Platform connection
backend.url=https://ssl-clm.example.com:8080

# Bootstrap (first run only)
bootstrap.token=CHANGE_ME

# Intervals
agent.heartbeat.fixedDelayMs=30000
agent.jobs.fixedDelayMs=10000

# mTLS (production recommended)
backend.mtls.enabled=true
backend.mtls.client-cert-path=/etc/ssl-clm-agent/client.pem
backend.mtls.client-cert-password=
backend.mtls.ca-cert-path=/etc/ssl-clm-agent/ca.pem

# MSCA Integration (optional)
agent.msca.enabled=false
agent.msca.ca-identifier=

# Logging
logging.level=INFO

Environment Variables

All properties can be set as environment variables:

export BACKEND_URL=https://ssl-clm.example.com:8080
export BOOTSTRAP_TOKEN=your_token
export AGENT_MSCA_ENABLED=true
export AGENT_MSCA_CA_IDENTIFIER=WIN-SERVER\\my-ca

---

Supported Job Types

Job Type	Description	Agent Action
CA_REFRESH	Sync certificate inventory from on-prem CA	Query CA, return certificate list
ISSUE_CERT	Issue a certificate via the CA	Submit CSR, return issued cert
REVOKE_CERT	Revoke a certificate	Execute revocation on CA
DEPLOY_CERT	Deploy certificate to a store	Write files, reload service
DISCOVER_STORE	Scan a local store for certificates	Read store, return cert list
BIND_CERT	Bind certificate to a service	Update service configuration
NETWORK_SCAN	Scan local network for TLS certs	Perform TLS handshakes, return results

---

Running as a System Service

Linux (systemd)

Create /etc/systemd/system/ssl-clm-agent.service:

[Unit]
Description=SSL-CLM Agent
After=network.target

[Service]
Type=simple
User=ssl-clm-agent
ExecStart=/usr/bin/java -jar /opt/ssl-clm-agent/ssl-clm-agent.jar
Restart=always
RestartSec=10
Environment=BACKEND_URL=https://ssl-clm.example.com:8080

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable ssl-clm-agent
sudo systemctl start ssl-clm-agent

Windows (NSSM or SC)

# Using NSSM (Non-Sucking Service Manager)
nssm install SSLCLMAgent "C:\Program Files\Java\jdk-21\bin\java.exe" "-jar C:\ssl-clm-agent\ssl-clm-agent.jar"
nssm set SSLCLMAgent AppEnvironmentExtra "BACKEND_URL=https://ssl-clm.example.com:8080"
nssm start SSLCLMAgent

---

Safe Mode

The agent enters Safe Mode (fail-closed) when:

• mTLS certificate is revoked by the platform
• Agent identity is rejected
• Backend returns persistent authorization failures

In Safe Mode:

• All job execution stops
• Heartbeat stops
• Agent waits for manual re-bootstrap
• No certificates are modified

To recover: generate a new bootstrap token and restart the agent.

---

Agent Certificate Renewal

The agent’s own mTLS client certificate has a validity period. Before it expires:

• The platform monitors agent certificate expiration
• An alert is generated when the agent cert is approaching expiry
• The platform can automatically renew the agent’s certificate (if configured)
• If the certificate expires, the agent enters EXPIRED status and stops functioning

---

Security Model

Principle	Implementation
Zero Trust	mTLS authentication on every request
Least Privilege	Agent only receives jobs for its assigned stores/CAs
One-Time Bootstrap	Token consumed on first use, cannot be replayed
No Inbound Ports	Pull-based model — agent initiates all connections
Fail-Closed	Safe Mode on any auth failure
Audit Trail	All agent actions are logged with actor AGENT:{id}
Secret Isolation	Agent never sends private keys to the platform unless explicitly configured

---

Troubleshooting

Symptom	Possible Cause	Resolution
Agent not appearing after registration	Bootstrap token expired or already used	Generate a new token
Agent shows OFFLINE	Process not running, or network issues	Check agent process, verify HTTPS connectivity to platform
Jobs not executing	Agent disabled, or no jobs pending	Check status, verify store/CA assignments
mTLS errors in logs	Certificate expired or revoked	Re-bootstrap the agent
Agent in SAFE_MODE	Persistent auth failures	Investigate backend logs, re-bootstrap

---

Related Pages

• Certificate Stores — Stores assigned to agents
• Certificate Authorities — Agent-based CA integrations
• Discovery — Agent-based network scanning
• Jobs — Job execution tracking
• Agent Setup Guide — Full installation walkthrough