Skip to main content

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.

ModeWhat it doesState
apiHTTP server, REST API, session and JWT.Stateless
workerPulls jobs (issue / renew / distribute / scan) and runs them.Stateless; many replicas OK.
schedulerEnqueues 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.
allAll three in one process. Default for the standalone installer.For small deployments.

Data flow for issuance​

  1. API receives POST /api/v1/projects/:projectId/certificates and writes a pending certificate document plus an issue_certificate job.
  2. Scheduler is uninvolved here — only renewals and scans are scheduler-driven.
  3. 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.
  4. The certificate timeline records cert.issued and one cert.distributed per 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.

Why per-field DEKs?

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​

PortRoleNotes
443HTTPS UI + APInginx termination by default.
18181Internal 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.
27017MongoDBLocal-only by default. Replica set members talk on this port.

See also​