Certificate Lifecycle and Renewal

Agent certificates are renewed automatically. Renewal is triggered after every successful ping when remaining cert validity falls below half the configured cert_days (default: 365 days — renewal begins at approximately 182 days remaining). No operator action is needed during normal operation.

To check cert status:

ctrl-exec ping host-a host-b          # CERT EXPIRY column
sudo ctrl-exec-agent pairing-status   # on the agent host

Renewal failures are logged at ERR and retried on the next ping.

Revoking an Agent Cert

After decommissioning an agent, obtain its cert serial and add it to the revocation list on every agent that host could have reached:

openssl x509 -noout -serial -in /etc/ctrl-exec-agent/agent.crt
echo "serial=DEADBEEF" >> /etc/ctrl-exec-agent/revoked-serials
systemctl reload ctrl-exec-agent

Use ced run to push the append to all remaining agents at once. Then remove the agent from the registry:

ctrl-exec unpair <hostname>

The revocation list is checked on every incoming mTLS connection before any request is processed.

CA Compromise Recovery

If the CA key is suspected compromised, take ctrl-exec offline immediately, generate a new CA and ctrl-exec certificate, and re-pair all agents. The new CA certificate must be distributed to agents out-of-band — ctrl-exec cannot push it since agents no longer trust the new ctrl-exec cert. Back up the compromised CA material before overwriting it.

Auth Hook Hardening

• Use ENVEXEC_ARGS_JSON for argument inspection. ENVEXEC_ARGS is unreliable for arguments containing spaces.
• Pass tokens via the ENVEXEC_TOKEN environment variable, not --token, to prevent them appearing in ps output.
• Tokens are never logged by ctrl-exec or the agent. Do not log environment variables wholesale in hooks.
• Treat ENVEXEC_USERNAME as advisory only — ctrl-exec does not verify it. Validate via token or external authentication service.

Monitoring

Use WARNING and ERR priority for alerting; INFO for audit and request ID correlation.

Security signals to alert on:

Pattern	Response
ACTION=rate-block REASON=volume	Connection flooding — investigate source IP
ACTION=rate-block REASON=probe	TLS probing — investigate source IP
ACTION=serial-reject	Check rotation broadcast — run ced serial-status
ACTION=revoked-cert	Treat as a security event — investigate immediately
ACTION=ip-block	Review allowed_ips — investigate unexpected sources

Rotation signals to alert on:

Pattern	Response
ACTION=serial-stale	Re-pair the agent
ACTION=serial-broadcast-fail (repeated)	Check connectivity
ACTION=cert-rotation-fail	Investigate immediately
All agents ACTION=serial-reject after rotation	Run ced serial-status and ced rotate-cert

Reference Documentation

Full security operations guide — complete monitoring patterns, SIEM alert table, token lifecycle, CA recovery procedure: SECURITY-OPERATIONS