Skip to Content
LYNKORIADocs

ADR 023: TLS between the API and the scanner with a private CA

  • Status: Accepted
  • Owner: Eng lead
  • Date: 2026-11-14

Context

The API sends every attachment to the scanner (apps/scanner) on a private Droplet in the same VPC, with a bearer token in the Authorization header. That traffic was plain HTTP, so anything able to read packets on the VPC (another tenant's compromised Droplet in a shared VPC, a misrouted mirror, a mistaken firewall rule) could read the token and the files, or answer in the scanner's place and mark malware clean. The VPC boundary and a firewall restricted to the App Platform range were the only controls (STATUS P2-05).

Options considered

  1. Private CA, TLS terminated by the scanner's own Node server. An operator-held CA issues the scanner certificate for its private IP; the API pins that CA. No new service, no DNS change, no external provider.
  2. Public certificate on a private DNS name. Needs a public domain, a DNS-01 ACME client with DNS credentials on the scanner host, and it puts the internal hostname in Certificate Transparency logs. Any public CA could then issue a certificate the API would accept.
  3. Accept VPC plus firewall. No work, but leaves the token and files in clear text and gives the API no way to tell the real scanner from an impostor.
  4. A TLS sidecar (Caddy, stunnel) in front of the scanner. Same trust model as option 1 with another container to patch and monitor.

Decision

Option 1.

  • scripts/scanner-pki.sh creates the CA (ECDSA P-256, 10 years, pathlen:0) and issues scanner certificates (397 days, serverAuth only, SANs for the private IP or name plus localhost/127.0.0.1 for the container healthcheck). The CA key stays on an operator machine or in the secret manager, never on the scanner host.
  • The scanner serves HTTPS when SCANNER_TLS_CERT_FILE and SCANNER_TLS_KEY_FILE are set, TLS 1.3 only, and reloads them on SIGHUP, so renewal needs no restart. The production Compose file requires them.
  • The API sets SCANNER_CA_CERT. @lynkoria/scanner-client then connects through node:https with that CA as the only trust anchor (global fetch cannot take a per-request trust store without the undici package), so a certificate from any other CA, public ones included, is refused. A bundle of two CAs is accepted during a CA rotation.
  • Production configuration refuses a plain-HTTP SCANNER_URL unless the scanner is on the same host (loopback), and the deployment always sets an https: URL and the CA.

No mutual TLS: the per-consumer bearer token already authenticates the caller, and TLS now keeps it secret.

Consequences

  • An operator runs the CA: issue a certificate before the first deployment, renew before day 397 (the scanner logs a warning from 30 days before expiry, and an expired certificate makes scans fail closed, which raises AttachmentScansFailing).
  • Tests use the same script: apps/scanner/test/tls.test.ts (pinned CA, wrong CA, no CA, plain HTTP, wrong name, TLS 1.2, CA bundle, reload) and the API's attachment tests run against the scanner over TLS.
  • Other consumers of the scanner (for example FideScript) pass the same CA through createScannerClient({ ca }).
  • Revocation is by reissue: the API pins the CA, so a leaked scanner key is handled by issuing a new certificate and, if the CA key itself is exposed, a new CA (deploy the bundle, switch the scanner, then drop the old CA).

Update (2026-11-16)

Deployments now use OpenTofu (infra/opentofu/platform/secrets.tf). It generates the CA and the scanner certificate with the same properties (ECDSA P-256, 397-day serverAuth certificate) and renews the certificate on any apply in its last 30 days. The certificate names a DNS name (scanner.internal.<domain>, a DNS-only record to the private IP) instead of the IP, because the IP is only known after the Droplet exists. scripts/scanner-pki.sh remains for local and hand-run setups.

On this page