ctcloud: CertSpotter-backed CT cloud-resource monitor

Single stateless Go process that consumes CT logs via embedded (patched)
CertSpotter internals, classifies cloud/database/storage DNS identifiers
in-process with a zero-allocation classifier, enriches via round-robin DNS
resolvers with CNAME following, and batch-writes useful findings to PostgreSQL.

- third_party/certspotter: 2-hunk IdentifierSink patch, no stdout/JSON/files
- internal/classify: AWS/Azure/GCP/Firebase/Cloudflare R2/DigitalOcean/Supabase/OCI
- internal/dns: sharded bounded TTL cache, multi-resolver load balancing + failover
- internal/pipeline: bounded queues, dedup, direct-priority load shedding
- internal/store: pgx batch writer, Postgres CT checkpoints (no cert contents)
- internal/probe: optional non-destructive reachability checks (off by default)
- Docker: distroless non-root, read-only rootfs, no app volume, resource limits
- tests enforce 0 allocs/op on the classifier and sink hot path

third_party/certspotter/man/certspotter-metrics.md

@@ -0,0 +1,128 @@
+# NAME
+
+**certspotter-metrics** - Output Prometheus metrics about certspotter's operation
+
+# SYNOPSIS
+
+**certspotter-metrics** [`-state_dir` *PATH*]
+
+# DESCRIPTION
+
+**certspotter-metrics** reads a certspotter state directory and writes
+Prometheus metrics, in the Prometheus text exposition format, about
+certspotter's progress monitoring each Certificate Transparency log.
+Metrics are written to standard output.
+
+The intended use is to run **certspotter-metrics** periodically (e.g., from
+cron) and expose its output to Prometheus, for example with the
+prometheus-node-exporter(1) textfile collector.
+
+**certspotter-metrics** only reads the state directory; it never modifies it.
+It is safe to run while certspotter is running, and it does not require
+certspotter to be running.
+
+Metrics are output for every log for which certspotter has a state directory
+(`$STATE_DIR/logs/LOG_ID`, where `LOG_ID` is the base64url-encoded log ID).
+A log has a state directory once certspotter has started monitoring it.
+The `log_id` label on each metric is the standard base64 encoding (with
+padding) of the 32-byte log ID defined by RFC 6962. See <https://sslmate.com/app/ctlogs>
+for a list of human-friendly names for each log ID.
+
+**certspotter-metrics** is experimental, and the metrics may change in a future release.
+
+# OPTIONS
+
+-state\_dir *PATH*
+
+:   Directory where certspotter stores state. Defaults to
+    `$CERTSPOTTER_STATE_DIR` if set, or `~/.certspotter` otherwise.
+    This should be the same directory used by **certspotter(8)**.
+
+-version
+
+:   Print version information and exit.
+
+# METRICS
+
+All metrics are gauges with a `log_id` label identifying the log the
+metric pertains to.  If a metric does not pertain to a log (because
+certspotter has not stored the relevant state for the log yet), the log
+does not have a sample for that metric.
+
+certspotter\_log\_max\_sth\_size
+
+:   Tree size of the largest signed tree head (STH) certspotter has observed
+    from the log; in other words, the number of entries in the log.  Absent
+    if certspotter has not yet downloaded an STH from the log.
+
+certspotter\_log\_max\_sth\_timestamp
+
+:   Timestamp, in milliseconds since the Epoch, of the STH reported by
+    certspotter\_log\_max\_sth\_size.
+
+certspotter\_log\_download\_position
+
+:   Number of entries certspotter has downloaded from the log, including
+    entries that have not yet been verified.
+
+certspotter\_log\_verified\_position
+
+:   Number of entries certspotter has downloaded from the log and verified
+    against an STH.
+
+certspotter\_log\_verified\_sth\_timestamp
+
+:   Timestamp, in milliseconds since the Epoch, of the most recent STH
+    certspotter has verified for the log. Absent if certspotter has not
+    verified an STH for the log. The size of this STH is equal to
+    certspotter\_log\_verified\_position.
+
+certspotter\_log\_unverified\_sths
+
+:   Number of unverified STHs certspotter is currently storing for the log.
+
+certspotter\_log\_malformed\_entries
+
+:   Number of malformed entries certspotter has recorded for the log.
+    certspotter records an entry as malformed when it cannot parse the
+    entry. See **certspotter(8)** for more information.
+
+certspotter\_log\_health\_check\_failures
+
+:   Number of failed health checks certspotter has recorded for the log.
+    See **certspotter(8)** for information about health checks.
+
+# EXAMPLES
+
+crontab(5) entry that exposes metrics to the node\_exporter textfile collector
+every five minutes (writing to a temporary file and renaming it
+ensures that node\_exporter never reads a partially-written file):
+
+    */5 * * * * root certspotter-metrics > /var/lib/node_exporter/certspotter.prom.tmp && mv /var/lib/node_exporter/certspotter.prom.tmp /var/lib/node_exporter/certspotter.prom
+
+Prometheus query to determine download backlog (number entries in the
+log that haven't been downloaded yet):
+
+    certspotter_log_max_sth_size-certspotter_log_download_position
+
+# ENVIRONMENT
+
+`CERTSPOTTER_STATE_DIR`
+
+:   Directory for storing state. Overridden by `-state_dir`. Defaults to
+    `~/.certspotter`. This should be the same directory used by
+    **certspotter(8)**.
+
+`STATE_DIRECTORY`
+
+:   Directory for storing state, if set and certspotter-metrics is running
+    under systemd.
+
+# EXIT STATUS
+
+**certspotter-metrics** exits with status 0 on success, 1 on error, or 2 on
+invalid usage.
+
+# SEE ALSO
+
+certspotter(8)