Certificate Lifecycle

Scope

Certificate work is easy to ignore until it becomes a production issue. This guide keeps the operator guidance and removes private collection or automation mechanics.

Step-by-step guides for certificate inventory, renewal configuration, and monitoring.

Related documents: - Architecture: docs/architecture/certificate-lifecycle.md - Functional: docs/functional/certificate-lifecycle.md - Fingerprint baselines: docs/manual/fingerprint-drift.md - Alert management: docs/manual/alerts-monitoring.md

Viewing Certificate Inventory

Status indicators: - valid: >30 days until expiry - expiring_soon: <=30 days until expiry - expiring: <=7 days until expiry - expired: past expiry date

Leaf filtering: Lifecycle alerts fire only for leaf certificates. CA roots and intermediates are shown in inventory but do not trigger expiry alerts.

Manual Certificate Sync

Trigger a manual sync from fingerprint baselines:

This re-extracts certificates from all fingerprint baselines and refreshes expiry status for the synced hosts only. Requires certificates.manage permission.

Setting Up Auto-Renewal

• auto_renew_enabled: true

• renew_before_days: how many days before expiry to start renewal (default 30)

• For ACME (Let’s Encrypt):

• Set acme_account_email

• For AD CS:

• Set ad_cs_template_name (certificate template)

• Set ad_cs_ca_name (CA server name)

• Optional controls:

• require_change_record: if true, creates a CHG ticket requiring approval before renewal
• rollback_on_failure: if true, dispatches rollback job to restore backup cert on failure
• max_concurrent_renewals: limit simultaneous renewals (default 5)
• is_active: toggle the policy on/off

Manual vs None policy modes: - manual: tracking-only policy mode. It does not enable automatic renewal and the Renew Now action will reject it because there is no connector-backed dispatch path. - none: disables renewal dispatch for the covered scope. - The UI now disables Enable automatic renewal for both of these modes. Use acme or ad_cs for actual renewal dispatch.

Triggering Manual Renewal

To manually trigger renewal for a specific certificate:

This resolves the applicable policy via _find_policy_for_cert() (org-specific > account-default) and dispatches the renewal job. Requires certificates.manage permission.

Responses:

Viewing Renewal History

To view the history of renewal attempts for a certificate:

Monitoring Renewals

The certificate expiry loop runs daily: 1. Updates days_until_expiry and status for certificates within the actionable range (expiring within 90 days or recently expired within 30 days), processed in batches 2. Fires event alerts for expiring/expired leaf certificates 3. Catches up certs renewed outside the actionable range (stale status correction) 4. Checks for certificates within the renewal window and dispatches auto-renewals (account-wide concurrency limit, counted once per sweep)

Renewal attempt states: - pending: job dispatched, awaiting agent completion - in_progress: agent executing renewal script - completed: renewal successful, cert updated, alerts resolved - failed: renewal failed, critical alert fired, optional rollback dispatched - rolled_back: rollback job finished successfully after a failed renewal - awaiting_change_approval: gated on change record approval

Handling Renewal Failures

When renewal fails: 1. A critical certificate_renewal_failed alert fires 2. If rollback_on_failure is enabled, a rollback job is dispatched to restore the backup certificate (the rollback script actually restores files via cp -rf) 5. Review the error in the CertificateRenewalAttempt record 6. The next daily sweep will retry renewal once the backoff window has elapsed (creates a new attempt) 7. Rollback completion is not implied when the rollback job is queued. The attempt stays failed until the rollback callback completes, then moves to rolled_back through the shared script callback path.

Exponential backoff schedule (approximate):

Failure #	Wait before retry
1st	1 hour
2nd	2 hours
3rd	4 hours
4th	8 hours
5th+	72 hours (capped)

Change-Gated Renewals

When require_change_record = True: 1. The renewal engine creates a CHG ticket with renewal details 2. The renewal attempt enters awaiting_change_approval state 3. An operator must approve the change record 4. The next renewal sweep detects the approval and dispatches the actual renewal job 5. The renewal proceeds normally from there

How Certificates Are Discovered

Certificates are extracted from fingerprint baseline data automatically: 1. When a fingerprint baseline is captured or updated 2. If the certificates category is enabled in the fingerprint policy 3. sync_certificates_from_baseline() extracts cert data and upserts into the certificates table 4. Stale certificates (no longer in baseline) are removed automatically

No manual certificate registration is required – all discovery happens through the agent’s fingerprint collection.

Using the Certificate UI

The Certificates page has two tabs: Inventory and Policies.

Inventory Tab – Viewing Certificates

Navigate to the Certificates page (defaults to Inventory tab). The tab shows:

1. Dashboard cards – Total, Valid, Expiring Soon, Expiring, Expired, and Hosts with Expiring counts. Click a status card to filter the table.
2. Certificate health bar – Shows the percentage of valid certificates and a “needs attention” count.
3. Status distribution bar – Color-coded horizontal bar showing the proportion of each status (valid=green, expiring soon=yellow, expiring=orange, expired=red). Includes a legend below.
4. Last sync result – After running a manual sync, shows how many certificates were synced from how many hosts. Persisted across page refreshes.
5. Search and filters – Search by subject, issuer, thumbprint, or hostname (300ms debounce). Filter by status dropdown, organization dropdown, and a “Leaf Only” checkbox.
6. Certificate table – Click any row to open the detail panel on the right. Pagination shows accurate totals (“Showing X-Y of Z”, “Page N of M”). CA/root certificates are badged in the table. is_leaf and has_private_key are shown in the detail panel.

Inventory Tab – Syncing Certificates from UI

Requires certificates.manage permission. The Sync Certificates button appears in the page header.

1. Click Sync Certificates in the page header.
2. A confirmation modal appears with an organization scope selector.
3. Select “All Organizations” or a specific organization to scope the sync.
4. Click Start Sync.
5. On success: toast shows “Synced N certificate(s) from M host(s)”. The dashboard cards and last sync summary update automatically.
6. On error: toast shows the error message.

Inventory Tab – Triggering Manual Renewal

Requires certificates.manage permission.

1. Select a certificate from the table to open the detail panel.
2. Click the Renew Now button next to the status badge. CA/root certificates do not show this button.
3. A confirmation modal shows the certificate subject, thumbprint, host, and expiry.
4. Click Renew Now to confirm.
5. On success:
6. 200 response: Toast shows “Renewal dispatched (job #N)”.
7. 202 response: Toast shows “Renewal awaiting change approval (attempt #N)”.
8. On failure:
9. 422: Toast shows the specific error (no policy, unsupported method, etc.).
10. If the certificate is in retry backoff, the detail panel shows a “Renewal Retry Scheduled” banner with the next retry timestamp.

Inventory Tab – Viewing Renewal History

1. Select a certificate from the table.
2. Click the Renewal History tab in the detail panel.
3. Each renewal attempt shows:
4. Status badge: pending (yellow), in_progress (blue), completed (green), failed (red), rolled_back (orange), awaiting_change_approval (purple), superseded (grey).
5. Method: acme, ad_cs, or manual. Manual attempts represent tracked/manual-only policy state; they do not imply connector-backed dispatch exists.
6. Started/Completed timestamps.
7. Job ID and Rollback Job ID (if applicable).
8. Old/New Expiry dates (when available).
9. Error message (for failed attempts).

Policies Tab – Managing Renewal Policies

Navigate to the Certificates page and click the Policies tab.

Viewing policies (requires certificates.view): - Policies are shown as cards, each displaying the scope (organization name or “Account Default”), renewal method badge, auto-renew status, and a settings grid with renew-before days, max concurrent renewals, change record requirement, and rollback setting. - ACME policies show the directory URL and account email. AD CS policies show the template name and CA name.

Creating a policy (requires certificates.manage): 1. Click Create Policy. 2. Select a scope: “Account-wide Default” or a specific organization. Scopes that already have a policy are disabled. 3. Choose a renewal method: ACME (Let’s Encrypt), AD Certificate Services, Manual, or None. 4. Toggle Enable automatic renewal if desired. For Manual and None, the toggle is disabled because those modes do not dispatch renewal jobs. 5. Set Renew Before (days) – how many days before expiry to start renewal (default 30). 6. For ACME: fill in Directory URL and Account Email (required when auto-renew is enabled). Select Challenge Type: - DNS-01: certbot creates a DNS TXT record. Required for wildcard certificates (*.example.com). Requires DNS API integration on the host. - TLS-ALPN-01: uses TLS handshake. Requires port 443 with ALPN support. 7. For AD CS: fill in Template Name and CA Name (required when auto-renew is enabled). 8. Configure controls: require change record, rollback on failure, max concurrent renewals, active toggle, failure workflow (optional). Manual keeps lifecycle ownership and failure-workflow intent without enabling automatic or button-triggered dispatch. None disables dispatch for the matched scope entirely. 9. Click Create.

Editing a policy (requires certificates.manage): 1. Click the edit icon on a policy card. 2. The scope selector is disabled (scope cannot be changed – one policy per scope). 3. Modify settings and click Save.

Deleting a policy (requires certificates.manage): 1. Click the delete (trash) icon on a policy card. 2. Confirm deletion in the dialog. 3. The policy is permanently removed. Existing renewal attempts are not affected, but no future auto-renewals will fire for the previously-covered scope until a new policy is created.

Viewing Certificates from Host Detail

Certificates for a specific host are also accessible from the Host Detail page:

1. Navigate to a host’s detail page (e.g., via the Hosts list).
2. Click the Certificates tab in the host detail panel.
3. The tab shows a stats row (total, valid, expiring soon, expiring, expired) and a paginated table of certificates on that host.
4. Click any certificate row to expand/collapse its details (thumbprint, serial number, validity dates, store, SAN entries, is_leaf, has_private_key).
5. To trigger manual renewal: click the Renew Now button on any leaf certificate row. CA/root certificates do not show the button, and backend API calls for non-leaf certs are rejected with 422. When the certificate is in exponential backoff, the expanded row shows a “Renewal Retry Scheduled” banner with the next retry time. Requires certificates.manage permission.

Requires certificates.view permission. If you don’t have this permission, the tab shows a permission denied message.

Exporting the Certificate Inventory

To export the full certificate inventory as CSV (for compliance audits, reporting, or external tooling):

Typical audit use case: download all expiring certs across all orgs to provide evidence for a compliance review.

Permissions Reference

Permission	Grants Access To
certificates.view	List certs, get detail, host certs, dashboard, list policies, renewal history, CSV export
certificates.manage	Upsert policy, delete policy, sync, manual renewal trigger