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.

01The three process modes

The same binary runs different responsibilities depending on the --mode flag.

02Data flow for issuance

1. API receives POST /api/v1/certificates and writes a requested certificate document plus an issue 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. Worker emits cert.requested, cert.issued, and cert.distributed audit events as it goes; each event is HMAC-chained to the previous one.

03Encryption 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 — locally, in a file with restricted permissions, or in an HSM (PKCS#11 — SoftHSM2, AWS CloudHSM, Thales Luna, Fortanix).

field {
  kek_version: 7,
  dek:         AES-256-GCM(KEK_v7, plaintext_dek),
  ciphertext:  AES-256-GCM(plaintext_dek, plaintext_field),
  aad:         sha256(record_id || field_name)
}

This means rotating a KEK never has to re-encrypt the actual ciphertext — only the small DEK wrappers — so rotation is fast and bandwidth-cheap, even for installations with millions of secrets.

04Audit chain

Every audit entry includes prev_hmac — an HMAC over the previous entry, keyed with a per-organization audit secret. A tampered or deleted entry breaks the chain, and certautopilot audit verify reports the first broken link.

The same events are forwarded to a SIEM via RFC 5424 syslog or CEF over TCP/UDP/TLS. The forwarder is durable: events are persisted to disk before TCP send, so a SIEM outage does not lose events.

05Multi-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.

06Network ports