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
- 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.
- 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.
- 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.
- 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.shcreates the CA (ECDSA P-256, 10 years,pathlen:0) and issues scanner certificates (397 days,serverAuthonly, SANs for the private IP or name pluslocalhost/127.0.0.1for 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_FILEandSCANNER_TLS_KEY_FILEare set, TLS 1.3 only, and reloads them onSIGHUP, so renewal needs no restart. The production Compose file requires them. - The API sets
SCANNER_CA_CERT.@lynkoria/scanner-clientthen connects throughnode:httpswith that CA as the only trust anchor (globalfetchcannot take a per-request trust store without theundicipackage), 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_URLunless the scanner is on the same host (loopback), and the deployment always sets anhttps: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.