Architecture
CertAutoPilot is a single Go binary that runs in three modes — API, worker, scheduler — backed by MongoDB. This page describes process boundaries, the encryption envelope, and the audit chain.
The three process modes
The same binary runs different responsibilities depending on the --mode flag.
| Mode | What it does | State |
|---|---|---|
api | HTTP server, REST API, session and JWT. | Stateless |
worker | Pulls jobs (issue / renew / distribute / scan) and runs them. | Stateless; many replicas OK. |
scheduler | Enqueues time-driven jobs: renewal windows, expiry/revocation checks, distribution sweeps, discovery schedules, recovery sweeps. (KEK rotation is started from the CLI and chains its own jobs.) | Leader-elected. Exactly one active. |
all | All three in one process. Default for the standalone installer. | For small deployments. |
Data flow for issuance
- API receives
POST /api/v1/projects/:projectId/certificatesand writes a pending certificate document plus anissue_certificatejob. - Scheduler is uninvolved here — only renewals and scans are scheduler-driven.
- Worker dequeues the job. It loads the ACME account, talks to the CA, publishes the DNS-01 challenge via the zone's credential, polls for validation, finalizes the order, and writes the chain back.
- The certificate timeline records
cert.issuedand onecert.distributedper deployed target as it goes, and the audit log records the action (e.g.CERT_ISSUED); each audit entry is HMAC-chained to the previous one.
Encryption envelope
Every secret field is wrapped in a per-field DEK (data-encryption key). The DEK is itself wrapped by a versioned KEK (key-encryption key). The KEK lives outside MongoDB — in environment variables (on standalone, loaded from a root-only secrets.env file), or in an HSM (PKCS#11 — see supported HSMs for what has actually been validated).
field { // stored as one base64 string
kv: 7, // which KEK version sealed this
edek: AES-256-GCM(KEK_v7, plaintext_dek),
ct: AES-256-GCM(plaintext_dek, plaintext_field),
p: "env", // "env" or "pkcs11"
ab: true // field-bound — optional, off by default
}
Only the ab flag is stored. The binding context itself — the collection and
field the value belongs to — is never written down; it is reconstructed at read
time from where the value was found. Storing it beside the ciphertext would let
anyone moving the value carry the matching context with it, which is precisely
what binding exists to prevent.
This means a KEK rotation proceeds record by record and can be cancelled and resumed — it is never an all-or-nothing re-encryption of the whole database. Each record is decrypted and re-sealed under a fresh data key, so plan the window against how much secret material you hold, not just how many rows.
So that a stolen MongoDB dump alone is useless. Decrypting any one field requires (a) the KEK in memory and (b) the DEK from the same field. Optional field binding (off by default) additionally ties the credential and key material to the field it lives in, so once binding is enabled and your data has been rotated, such a value no longer decrypts if it is moved elsewhere.
Audit chain
Every audit entry has a position seq in its organization's chain and stores the previous entry's checksum as an anchor; its own HMAC signature covers the anchor, the position and the whole entry. A tampered or deleted entry breaks the chain; the verify endpoint (owner-only, rate-limited to one call a minute) reports every break it finds, each with the entry's seq and a reason (checksum_mismatch, anchor_mismatch, missing_predecessor), and pages through long chains with next_seq / from_seq. There is no certautopilot audit CLI command.
The same events are forwarded to a SIEM as RFC 5424, CEF or LEEF over UDP, TCP or TCP+TLS. The forwarder is durable: it works through the audit entries already stored in MongoDB and retries with backoff, so a SIEM outage does not lose events (UDP delivery itself is fire-and-forget).
Multi-tenant RBAC
RBAC is enforced at the API layer with policies declared per route handler. Project-scoped objects also enforce tenancy at the data-access layer — every read and write injects a project filter so an admin in project A literally cannot read project B objects, even with a crafted query.
Network ports
| Port | Role | Notes |
|---|---|---|
| 443 | HTTPS UI + API | nginx termination by default. |
| 18181 | Internal HTTP (standalone) | Backend bound to 127.0.0.1; nginx proxies to it. The built-in default (containers, Helm) is 0.0.0.0:8181. Prometheus /metrics is served on this same listener — there is no separate metrics port. |
| 27017 | MongoDB | Local-only by default. Replica set members talk on this port. |