diff --git a/.claude/rules/auth-billing.md b/.claude/rules/auth-billing.md index 5e46f61..c71de20 100644 --- a/.claude/rules/auth-billing.md +++ b/.claude/rules/auth-billing.md @@ -64,7 +64,7 @@ docs and success pages. Config: `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, the aggregation SQL behind it. `UsageLogger` buffers on a channel and batch-inserts to `request_log` every 5s or 50 entries; a full channel drops with a warning. `NoopRecorder` discards entries when tracking isn't wanted (tests). `request_log` rows carry per-request -metadata including `domain_count`, `ip_count`, and a per-feature flag per lookup. The `UsageLog()` middleware runs after `c.Next()` and reads the +metadata including `domain_count`, `ip_count`, `host_count`, and a per-feature flag per lookup. The `UsageLog()` middleware runs after `c.Next()` and reads the `lookups_requested`, `cache_hits`, `cache_misses` context keys the handlers set. Two rules a drift test enforces: diff --git a/.claude/rules/http-layer.md b/.claude/rules/http-layer.md index da3ceef..2f369c7 100644 --- a/.claude/rules/http-layer.md +++ b/.claude/rules/http-layer.md @@ -37,7 +37,7 @@ auth (it needs the key) and must be after `c.Next()` so it sees the outcome. ## Metrics — `internal/metrics` One `*metrics.Metrics`, built in `app.go` and passed to the router, the rate limiter -(`RateLimitConfig.Metrics`) and both services. It is a concrete type, not an interface: +(`RateLimitConfig.Metrics`) and the three lookup services. It is a concrete type, not an interface: there is one implementation, and every recording method is a no-op on a nil pointer, so tests pass nil or build their own (each owns its registry; `metricstest` reads one the way a scrape does). Recording is always on. `metrics.enabled` only decides whether diff --git a/.claude/rules/lookups.md b/.claude/rules/lookups.md index a294a35..4247a6f 100644 --- a/.claude/rules/lookups.md +++ b/.claude/rules/lookups.md @@ -4,6 +4,7 @@ paths: - "internal/safenet/**" - "internal/handler/domain.go" - "internal/handler/ip.go" + - "internal/handler/encryption.go" - "internal/handler/fingerprint.go" - "internal/handler/geoip_admin.go" --- @@ -39,6 +40,39 @@ non-globally-routable addresses, and gates `threat_intel` to pro/admin. `ipLooku is a separate table — `whois` is valid for a domain and a 400 for an IP. Keys live under `ip:`, so `threat_intel` on the two endpoints cannot collide. +## Encryption lookups use it too, and the probe has rules of its own + +`/v1/encryption/lookup` takes `hosts` and the same `lookups` array. `encryptionLookupMinPlan` +in `internal/handler/encryption.go` is a third table (all free: the lookups spend no +upstream quota). Hosts go through `normalizeDomain`/`groupDomains` unchanged, so the port a +caller writes is dropped. Keys live under `encryption:`. Types are in +`internal/domain/encryption_model.go`; the catalog is `AllEncryptionLookupNames`. + +The probe is `internal/domain/encryption_probe.go`. Each rule below is a way to return a +wrong answer that would then be cached for hours (`docs/decisions.md`, "The encryption +probe"): + +- **A handshake has three outcomes: accepted, refused, unknown.** Refused (`rejectedError`) + means the TCP connection opened and the handshake then failed. A connect failure or a + timeout is unknown, and unknown fails the lookup. Never record it as a refusal. +- **A lookup where nothing was accepted returns `ErrNoHandshake`**, not a result saying the + host accepts nothing. +- **All handshakes in one lookup go to one address**, picked once in `newSession` after + resolving through `domain.Resolver()`. +- **Port 443 only, hostnames only.** A caller-supplied port makes this a port prober. +- **`InsecureSkipVerify` during the handshake, on purpose**, as in `LookupSSL`. The + `certificate` lookup judges the chain *afterwards* (`trustVerdict`, `hostnameVerdict`) and + reports verdicts. The x509 error is dropped there and must never be returned as the + lookup's error: `IsExpectedError` treats x509 failures as ours and they page. +- **The key exchange probe uses default (ECDHE-only) cipher suites and checks the negotiated + group**; the other two offer every suite so legacy servers still answer, and every group + (`everyGroup()`), because the standard library's default offer leaves some out and a + server requiring one of those would read as refusing TLS. +- Every connection goes through `safenet.SafeDialer`. + +Tests aim a `session` at TLS servers on loopback with an empty trust store; nothing touches +the network. + ## Resolver — never `net.DefaultResolver` `domain.Resolver()` returns the resolver lookups use: the external servers from diff --git a/.claude/rules/service-layer.md b/.claude/rules/service-layer.md index ba3356c..6ef6266 100644 --- a/.claude/rules/service-layer.md +++ b/.claude/rules/service-layer.md @@ -12,11 +12,12 @@ The *why* behind each of these is in `docs/decisions.md` under "Lookups and cach ## Shared runner core — `internal/service/runner.go` -Both `DomainService` and `IPService` run on the same machinery: `lookupRunner`, +`DomainService`, `IPService` and `EncryptionService` run on the same machinery: `lookupRunner`, `fetchResult`, `runState`, the runner constructors, panic recovery, the MGET pre-flight, and the singleflight + SET fan-out. `runState` is target-agnostic — a target string, a field name for logs, and a `keyFor` closure — so the domain service supplies -`lookup::` keys and the IP service supplies `ip::`. Each service +`lookup::` keys, the IP service `ip::`, and the encryption service +`encryption::`. Each service keeps only what is specific to it: which lookups exist, how they are fetched, how the response is assembled. @@ -55,9 +56,10 @@ coalescing anywhere; `service/whole_response.go` is gone and must not come back. ## Cache rules -- Keys are flat: `lookup::` / `ip::` (e.g. - `lookup:example.net:ssl`), built by `cache.LookupKey()` with the `cache.LookupKeyPrefix` - constant. The builder **does not normalize** — that is the handler's job. +- Keys are flat: `lookup::` / `ip::` / `encryption::` + (e.g. `lookup:example.net:ssl`), built by `cache.LookupKey()`, `IPLookupKey()` and + `EncryptionLookupKey()` with their prefix constants. The builders **do not normalize** — + that is the handler's job. - Redis stores the **bare payload only**. Response wrappers embed the payload type and add `cache_hit`, set at assembly time; only the embedded type is ever marshaled. - TTLs come from `cache.default_ttl` + `cache.ttl.` via `config.CacheTTLs()`, which diff --git a/.claude/skills/adding-features/SKILL.md b/.claude/skills/adding-features/SKILL.md index dcf6c04..40f0d51 100644 --- a/.claude/skills/adding-features/SKILL.md +++ b/.claude/skills/adding-features/SKILL.md @@ -31,5 +31,15 @@ surfaces late — usually as a drift test failing in CI or a stale docs surface. 5. Register the route in `RegisterProtectedRoutes()` with `RequireAdmin()` if admin-only 6. Wire the service in `internal/app/app.go` 7. Add a field to `handler.Deps` and set it in `app.go` — existing test call sites need no change, since they name only the dependencies they use -8. Add context keys to `middleware/request_logger.go` if needed +8. Add context keys to `middleware/request_logger.go` if needed. A per-request count such as `host_count` also needs a `UsageEntry` field, a block in `middleware/usage.go`, a `request_log` column, the insert in `usage/logger.go`, the `SUM` and `UsageSummary` field in `usage/query.go`, and the same field in `cmd/sactl/usage.go`, `openapi.yaml` and `docs_account.html` 9. Update `docs/api-reference.md` (endpoint table and a section for the endpoint), api.http, smoke test, integration tests, changelog.yaml + +An endpoint with its own lookup catalog (`AllEncryptionLookupNames` beside `AllLookupNames` and `AllIPLookupNames`) also has to be added everywhere the catalogs are unioned. Nothing fails if one is missed, which is why they are listed: + +- `internal/app/app.go` `lookupNames` — left out, the catalog's `cache.ttl.*` keys are silently ignored and every lookup gets `cache.default_ttl` +- `internal/usage/logger_test.go` `TestLookupColumns_MatchesLookupCatalogs` — left out along with the columns, the drift test passes and protects nothing +- `internal/handler/openapi_contract_test.go` and `openapi_test.go` — the request-schema table and the expected-paths list +- `internal/handler/docs_request_body_test.go` and the hard-coded page lists in `docs_test.go` +- `cmd/sactl/lookup.go` and `interactive.go` — the `lookup` command and menu + +It also needs its own cache key prefix and builder in `internal/cache/cache.go`, its own `LookupMinPlan` table, and, for a docs page, a `docsPages` row plus the topbar nav link in all six templates (`TestDocs_MobileNavReachesEveryPage` fails until every one has it). diff --git a/AGENTS.md b/AGENTS.md index 6c21c71..1810f75 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,8 +4,10 @@ Domain and IP intelligence REST API in Go with Gin. Concurrent WHOIS, DNS, SSL, headers, reputation, email security (SPF/DKIM/DMARC/MTA-STS/TLS-RPT/BIMI), subdomains, certificate transparency, BGP/ASN, technology fingerprinting, threat intelligence, and DNS security (DNSSEC/CAA) for domains, plus an aggregate risk score. IP -lookups: GeoIP, ASN, reverse DNS, RDAP abuse contact, threat intelligence. Results are -cached per lookup in Redis with singleflight coalescing; failures are never cached. Auth is +lookups: GeoIP, ASN, reverse DNS, RDAP abuse contact, threat intelligence. Encryption +lookups for hosts, from TLS handshakes the API makes itself to port 443: accepted TLS +versions, key exchange groups including post-quantum ones, and the certificate chain. +Results are cached per lookup in Redis with singleflight coalescing; failures are never cached. Auth is API-key based with PostgreSQL; customers self-rotate keys and query their own usage. OpenAPI 3.1 at `/docs/openapi.yaml`. diff --git a/README.md b/README.md index 0416dfc..291cd93 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,9 @@ A domain and IP intelligence REST API in Go. One request fans out to concurrent (WHOIS, DNS, TLS, HTTP headers, email security, certificate transparency, BGP/ASN, technology fingerprinting, reputation, threat intelligence, DNSSEC/CAA, GeoIP, reverse DNS, abuse contacts) and returns one JSON document with a per-lookup cache flag and an -optional aggregate risk score. It is a paid, metered service with self-service API keys, +optional aggregate risk score. A third endpoint reports a host's encryption posture from +handshakes it makes itself: accepted TLS versions, post-quantum key exchange, and the +certificate chain. It is a paid, metered service with self-service API keys, Stripe billing, and per-plan rate limits, running in production at ****. diff --git a/api.http b/api.http index d6cc112..e485ad1 100644 --- a/api.http +++ b/api.http @@ -18,6 +18,9 @@ GET {{host}}/docs/domain ### IP Intelligence docs (no auth required) GET {{host}}/docs/ip +### Encryption Posture docs (no auth required) +GET {{host}}/docs/encryption + ### OpenAPI specification (no auth required) GET {{host}}/docs/openapi.yaml @@ -405,6 +408,94 @@ X-API-Key: {{adminKey}} "lookups": ["geo", "asn", "reverse_dns", "abuse_contact"] } +### Encryption lookup - all three lookups (admin key) +POST {{host}}/v1/encryption/lookup +Content-Type: application/json +X-API-Key: {{adminKey}} + +{ + "hosts": ["example.com"], + "lookups": ["protocols", "key_exchange", "certificate"] +} + +### Encryption lookup - every lookup is available on the free plan (free key) +POST {{host}}/v1/encryption/lookup +Content-Type: application/json +X-API-Key: {{freeKey}} + +{ + "hosts": ["github.com"], + "lookups": ["key_exchange"] +} + +### Encryption lookup - URL and port are stripped; the probe always goes to 443 (pro key) +POST {{host}}/v1/encryption/lookup +Content-Type: application/json +X-API-Key: {{proKey}} + +{ + "hosts": ["https://Example.com:8443/path", "example.com", "cloudflare.com"], + "lookups": ["certificate"] +} + +### Encryption lookup - expired certificate is a result, not an error (admin key) +POST {{host}}/v1/encryption/lookup +Content-Type: application/json +X-API-Key: {{adminKey}} + +{ + "hosts": ["expired.badssl.com"], + "lookups": ["certificate"] +} + +### Encryption lookup - should return 400 (lookups missing) +POST {{host}}/v1/encryption/lookup +Content-Type: application/json +X-API-Key: {{adminKey}} + +{ + "hosts": ["example.com"] +} + +### Encryption lookup - should return 400 (ssl is a domain-only lookup) +POST {{host}}/v1/encryption/lookup +Content-Type: application/json +X-API-Key: {{adminKey}} + +{ + "hosts": ["example.com"], + "lookups": ["ssl"] +} + +### Encryption lookup - should return 400 (raw IP) +POST {{host}}/v1/encryption/lookup +Content-Type: application/json +X-API-Key: {{adminKey}} + +{ + "hosts": ["93.184.216.34"], + "lookups": ["certificate"] +} + +### Encryption lookup - should return 400 (free plan allows one host) +POST {{host}}/v1/encryption/lookup +Content-Type: application/json +X-API-Key: {{freeKey}} + +{ + "hosts": ["example.com", "example.org"], + "lookups": ["certificate"] +} + +### Encryption lookup - should return 401 (no key) +POST {{host}}/v1/encryption/lookup +Content-Type: application/json + +{ + "hosts": ["example.com"], + "lookups": ["certificate"] +} + ### My usage (any plan) GET {{host}}/v1/usage X-API-Key: {{lookupKey}} diff --git a/cmd/sactl/interactive.go b/cmd/sactl/interactive.go index 6dda7c4..67591e2 100644 --- a/cmd/sactl/interactive.go +++ b/cmd/sactl/interactive.go @@ -307,6 +307,10 @@ func (s *shell) lookupMenu(ctx context.Context) error { return s.lookupAction(ctx, "IP", "ips", "/v1/ip/lookup", domain.AllIPLookupNames, defaultIPLookups) }}, + {"3", "Encryption posture", func(ctx context.Context) error { + return s.lookupAction(ctx, "host", "hosts", "/v1/encryption/lookup", + domain.AllEncryptionLookupNames, domain.AllEncryptionLookupNames) + }}, }, "b) Back") } diff --git a/cmd/sactl/lookup.go b/cmd/sactl/lookup.go index b6a86b4..9f30b3d 100644 --- a/cmd/sactl/lookup.go +++ b/cmd/sactl/lookup.go @@ -17,10 +17,11 @@ import ( func lookupGroup() group { return group{ name: "lookup", - summary: "run domain and IP intelligence lookups", + summary: "run domain, IP and encryption lookups", commands: []command{ - lookupCommandFor("domain", "domains", "/v1/domain/lookup", domain.AllLookupNames, defaultDomainLookups), - lookupCommandFor("ip", "ips", "/v1/ip/lookup", domain.AllIPLookupNames, defaultIPLookups), + lookupCommandFor("domain", "domain", "domains", "/v1/domain/lookup", domain.AllLookupNames, defaultDomainLookups), + lookupCommandFor("ip", "ip", "ips", "/v1/ip/lookup", domain.AllIPLookupNames, defaultIPLookups), + lookupCommandFor("encryption", "host", "hosts", "/v1/encryption/lookup", domain.AllEncryptionLookupNames, domain.AllEncryptionLookupNames), }, } } @@ -45,11 +46,14 @@ type lookupFlags struct { lookups string } -func lookupCommandFor(name, field, path string, all, defaults []string) command { +// lookupCommandFor builds one `sactl lookup ` command. target is what the +// command takes ("domain", "ip", "host"), which is not always the command's +// name: the encryption endpoint takes hosts. field is the request body key. +func lookupCommandFor(name, target, field, path string, all, defaults []string) command { return command{ name: name, - summary: "look up one or more " + name + "s", - usage: strings.ToUpper(name) + " [" + strings.ToUpper(name) + "...] [--lookups a,b,c]", + summary: "look up one or more " + target + "s", + usage: strings.ToUpper(target) + " [" + strings.ToUpper(target) + "...] [--lookups a,b,c]", flags: func(fs *flag.FlagSet) any { f := &lookupFlags{api: registerAPIFlags(fs)} fs.StringVar(&f.lookups, "lookups", "", fmt.Sprintf( @@ -60,7 +64,7 @@ func lookupCommandFor(name, field, path string, all, defaults []string) command run: func(ctx context.Context, cfg any, args []string) error { f := cfg.(*lookupFlags) if len(args) == 0 { - return fmt.Errorf("give at least one %s, e.g. sactl lookup %s example.com", name, name) + return fmt.Errorf("give at least one %s, e.g. sactl lookup %s example.com", target, name) } names, err := resolveLookupNames(f.lookups, all, defaults) if err != nil { diff --git a/cmd/sactl/usage.go b/cmd/sactl/usage.go index fe5df78..ebe9fd3 100644 --- a/cmd/sactl/usage.go +++ b/cmd/sactl/usage.go @@ -19,6 +19,7 @@ type usageSummary struct { AvgLatencyMs float64 `json:"avg_latency_ms"` TotalDomains int `json:"total_domains"` TotalIPs int `json:"total_ips"` + TotalHosts int `json:"total_hosts"` StatusCodes map[string]int `json:"status_codes"` FeatureUsage map[string]int `json:"feature_usage"` RequestsByPath map[string]int `json:"requests_by_path"` @@ -113,6 +114,7 @@ func renderUsage(s usageSummary, f *usageFlags) { fmt.Printf("\n requests %d\n", s.TotalRequests) fmt.Printf(" domains %d\n", s.TotalDomains) fmt.Printf(" IPs %d\n", s.TotalIPs) + fmt.Printf(" hosts %d\n", s.TotalHosts) fmt.Printf(" latency %.1f ms average\n", s.AvgLatencyMs) // cache_hit_rate already arrives as a percentage (see usage/query.go), not // a fraction — scaling it again here produced "7922.3%". diff --git a/deploy/grafana/intelligence-api.json b/deploy/grafana/intelligence-api.json index f84a94a..628636f 100644 --- a/deploy/grafana/intelligence-api.json +++ b/deploy/grafana/intelligence-api.json @@ -88,11 +88,11 @@ }, { "id": 4, "type": "stat", "title": "Lookup p95", - "description": "95th percentile latency of POST /v1/domain/lookup and POST /v1/ip/lookup, as the caller sees it.", + "description": "95th percentile latency of POST /v1/domain/lookup, POST /v1/ip/lookup and POST /v1/encryption/lookup, as the caller sees it.", "gridPos": { "x": 12, "y": 0, "w": 4, "h": 4 }, "datasource": { "type": "prometheus", "uid": "${datasource}" }, "targets": [ - { "refId": "A", "expr": "histogram_quantile(0.95, sum by (le) (rate(intelligence_api_http_request_duration_seconds_bucket{app=~\"$app\",instance=~\"$instance\",route=~\"/v1/(domain|ip)/lookup\"}[$__rate_interval])))" } + { "refId": "A", "expr": "histogram_quantile(0.95, sum by (le) (rate(intelligence_api_http_request_duration_seconds_bucket{app=~\"$app\",instance=~\"$instance\",route=~\"/v1/(domain|ip|encryption)/lookup\"}[$__rate_interval])))" } ], "fieldConfig": { "defaults": { "unit": "s", "decimals": 2 }, "overrides": [] }, "options": { "colorMode": "none", "graphMode": "area", "reduceOptions": { "calcs": ["lastNotNull"] } } @@ -150,13 +150,13 @@ }, { "id": 12, "type": "timeseries", "title": "Lookup endpoint latency", - "description": "Request latency of the two lookup endpoints, end to end. The per-lookup fetch times are in the Lookups row.", + "description": "Request latency of the three lookup endpoints, end to end. The per-lookup fetch times are in the Lookups row.", "gridPos": { "x": 0, "y": 13, "w": 12, "h": 8 }, "datasource": { "type": "prometheus", "uid": "${datasource}" }, "targets": [ - { "refId": "A", "legendFormat": "p50 {{route}}", "expr": "histogram_quantile(0.50, sum by (le, route) (rate(intelligence_api_http_request_duration_seconds_bucket{app=~\"$app\",instance=~\"$instance\",route=~\"/v1/(domain|ip)/lookup\"}[$__rate_interval])))" }, - { "refId": "B", "legendFormat": "p95 {{route}}", "expr": "histogram_quantile(0.95, sum by (le, route) (rate(intelligence_api_http_request_duration_seconds_bucket{app=~\"$app\",instance=~\"$instance\",route=~\"/v1/(domain|ip)/lookup\"}[$__rate_interval])))" }, - { "refId": "C", "legendFormat": "p99 {{route}}", "expr": "histogram_quantile(0.99, sum by (le, route) (rate(intelligence_api_http_request_duration_seconds_bucket{app=~\"$app\",instance=~\"$instance\",route=~\"/v1/(domain|ip)/lookup\"}[$__rate_interval])))" } + { "refId": "A", "legendFormat": "p50 {{route}}", "expr": "histogram_quantile(0.50, sum by (le, route) (rate(intelligence_api_http_request_duration_seconds_bucket{app=~\"$app\",instance=~\"$instance\",route=~\"/v1/(domain|ip|encryption)/lookup\"}[$__rate_interval])))" }, + { "refId": "B", "legendFormat": "p95 {{route}}", "expr": "histogram_quantile(0.95, sum by (le, route) (rate(intelligence_api_http_request_duration_seconds_bucket{app=~\"$app\",instance=~\"$instance\",route=~\"/v1/(domain|ip|encryption)/lookup\"}[$__rate_interval])))" }, + { "refId": "C", "legendFormat": "p99 {{route}}", "expr": "histogram_quantile(0.99, sum by (le, route) (rate(intelligence_api_http_request_duration_seconds_bucket{app=~\"$app\",instance=~\"$instance\",route=~\"/v1/(domain|ip|encryption)/lookup\"}[$__rate_interval])))" } ], "fieldConfig": { "defaults": { "unit": "s", "min": 0 }, "overrides": [] }, "options": { "legend": { "displayMode": "table", "placement": "bottom", "calcs": ["lastNotNull", "max"] }, "tooltip": { "mode": "multi", "sort": "desc" } } diff --git a/docs/api-reference.md b/docs/api-reference.md index 5b5c4e6..f5c7ebf 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -8,7 +8,7 @@ billing internals) is in [operations.md](operations.md). ## Authentication -Most API endpoints require an API key passed via the `X-API-Key` header. Keys are stored in PostgreSQL as `hex(sha256(key))` and belong to a customer, who has a plan. A customer normally holds one live key, but holds several during a rotation grace window: `POST /v1/keys/rotate` issues a new key and leaves the previous ones authenticating until `auth.rotation_grace` (default 24h) elapses, so deployed clients can be switched over without downtime. The following routes are public (no API key required): `/` (the company home page on the company's hostname, a redirect to `/docs` on the API's), `/docs`, `/docs/domain`, `/docs/ip`, `/docs/account`, `/docs/changelog`, `/docs/openapi.yaml`, `/v1/hello`, `/v1/health`, `/billing/webhook` (Stripe signature), and `/billing/success` (session token). +Most API endpoints require an API key passed via the `X-API-Key` header. Keys are stored in PostgreSQL as `hex(sha256(key))` and belong to a customer, who has a plan. A customer normally holds one live key, but holds several during a rotation grace window: `POST /v1/keys/rotate` issues a new key and leaves the previous ones authenticating until `auth.rotation_grace` (default 24h) elapses, so deployed clients can be switched over without downtime. The following routes are public (no API key required): `/` (the company home page on the company's hostname, a redirect to `/docs` on the API's), `/docs`, `/docs/domain`, `/docs/ip`, `/docs/encryption`, `/docs/account`, `/docs/changelog`, `/docs/openapi.yaml`, `/v1/hello`, `/v1/health`, `/billing/webhook` (Stripe signature), and `/billing/success` (session token). ### Customer Plans @@ -16,11 +16,11 @@ Each customer has a `plan` that controls rate limits, access to premium options, | Plan | Capabilities | |------|-------------| -| `free` | All lookups except `reputation` and `threat_intel`. 1 domain per request. | -| `pro` | All free capabilities + reputation checks + threat intelligence, up to 20 domains per request | +| `free` | All lookups except `reputation` and `threat_intel`. 1 domain, IP or host per request. | +| `pro` | All free capabilities + reputation checks + threat intelligence, up to 20 domains, IPs or hosts per request | | `admin` | All pro capabilities + admin endpoints (info, fingerprint management, cache invalidation) + no rate limit | -The plan is stored in the `customers` table, defaulting to `free`. New customers provisioned via Stripe checkout receive the plan they purchased. An unrecognized plan value is treated as `free` by both the rate limiter and lookup gating, so a bad value fails closed. +The plan is stored in the `customers` table, defaulting to `free`. New customers provisioned via Stripe checkout receive the plan they purchased. An unrecognized plan value is treated as `free` by the rate limiter, lookup gating, and the per-request caps on domains, IPs and hosts, so a bad value fails closed. Requests without a valid key receive `401 Unauthorized`. Requests from non-admin plans to admin-only endpoints receive `403 Forbidden`. Requests naming a lookup outside the caller's plan (`reputation`, `threat_intel` require pro) receive `403 Forbidden`. The `/v1/hello` and `/v1/health` checks require no authentication. Self-service endpoints (`GET /v1/usage`, `POST /v1/keys/rotate`) are available to every plan. @@ -48,6 +48,7 @@ When the limit is exceeded, the API returns `429 Too Many Requests` with a `Retr | GET | `/docs` | None | API documentation landing page | | GET | `/docs/domain` | None | Domain Intelligence API docs | | GET | `/docs/ip` | None | IP Intelligence API docs | +| GET | `/docs/encryption` | None | Encryption Posture API docs | | GET | `/docs/account` | None | Usage statistics and key rotation docs | | GET | `/docs/changelog` | None | Public release notes | | GET | `/docs/openapi.yaml` | None | OpenAPI specification for the public API | @@ -59,6 +60,7 @@ When the limit is exceeded, the API returns `429 Too Many Requests` with a `Retr | GET | `/v1/info` | `admin` | Application and environment info | | POST | `/v1/domain/lookup` | All plans | Domain intelligence lookup | | POST | `/v1/ip/lookup` | All plans | IP intelligence lookup | +| POST | `/v1/encryption/lookup` | All plans | Encryption posture lookup: TLS versions, key exchange, certificate chain | | GET | `/v1/usage` | All plans | Caller's own usage statistics | | POST | `/v1/keys/rotate` | All plans | Rotate the caller's API key (old keys keep working for a grace window) | | POST | `/v1/admin/geoip/refresh` | `admin` | Download and reload the DB-IP GeoIP database | @@ -668,6 +670,126 @@ It reads a local memory-mapped database with no network call, so a Redis round t MaxMind GeoLite2 was used until the switch; its EULA restricts disclosing the data to third parties, which a paid API does. See `docs/decisions.md`. +### POST /v1/encryption/lookup + +Reports how well a host's encryption holds up, checked from the outside. Every answer comes from TLS handshakes this service makes itself to port 443 of the host, so there is no upstream provider behind it. + +**Request:** +```json +{ + "hosts": ["https://Example.com/"], + "lookups": ["key_exchange", "certificate"] +} +``` + +One host, so the example works on every plan: the free plan allows one host per request, and a second entry counts toward that even when it names the same host. + +Both fields are **required**, and the endpoint follows the same contract as the domain and IP lookups: `lookups` must be non-empty, names are trimmed/lowercased/deduplicated before validation, and results come back in a `{"results": [...]}` envelope with per-lookup `cache_hit`. + +#### `hosts` + +An array of hostnames. Each is normalized by the same rules as a domain: scheme, credentials, port, path, and a trailing dot are stripped, and the name is lowercased. **The port is always 443**, whatever was written. Entries that normalize to the same hostname are deduplicated into one result. Plan host limits (`encryption.max_hosts.*`, 1 free / 20 pro) count the entries you submitted, not the unique hostnames. + +IP addresses are rejected: the handshakes need a name to ask for. A host that resolves only to private or reserved addresses is refused at lookup time. + +#### `lookups` + +| Lookup | Plan | Reports | Handshakes | +|--------|------|---------|------------| +| `protocols` | All | Which of TLS 1.0, 1.1, 1.2 and 1.3 the host accepts | 4 | +| `key_exchange` | All | Which of eight key exchange groups it accepts (four post-quantum), which it picks when offered all of them, and a verdict | 9 | +| `certificate` | All | The certificate chain: algorithms, key sizes, the leaf's expiry, whether the chain is publicly trusted, and whether it covers the host | 1 | + +The catalog is separate from the domain and IP ones: asking for `ssl` here returns `400`. `certificate` overlaps the domain endpoint's `ssl` lookup, which reports the leaf only. + +**Response:** +```json +{ + "results": [ + { + "host": "example.com", + "inputs": ["https://Example.com/"], + "key_exchange": { + "cache_hit": false, + "ip": "172.66.147.243", + "probed_at": "2026-11-10T03:54:40.5Z", + "groups": [ + { "name": "X25519MLKEM768", "accepted": true, "post_quantum": true }, + { "name": "x25519", "accepted": true, "post_quantum": false } + ], + "negotiated": "X25519MLKEM768", + "verdict": "post_quantum" + } + } + ] +} +``` + +The example is trimmed: `groups` always lists all eight groups, and `certificate` is omitted. Match results by `host`, not by array position. + +**Fields on every lookup:** + +| Field | Description | +|-------|-------------| +| `cache_hit` | Whether this lookup was served from cache | +| `ip` | The address the handshakes went to. A host with several addresses can be configured differently on each, so one lookup always uses one address: the first public IPv4 address, or the first public IPv6 one when there is no IPv4 | +| `probed_at` | When the handshakes were made. For a cached result this is earlier than the request | + +**`protocols`:** + +| Field | Description | +|-------|-------------| +| `versions` | One entry per version, newest first: `name` (`TLS 1.3` … `TLS 1.0`) and `accepted` | +| `legacy_accepted` | True when the host accepts TLS 1.0 or TLS 1.1, both deprecated by RFC 8996 | + +SSL 3.0 and earlier are not tested. + +**`key_exchange`:** + +| Field | Description | +|-------|-------------| +| `groups` | One entry per group: `name` (the IANA name), `accepted`, `post_quantum` | +| `negotiated` | The group the host chose when offered all of them at once, post-quantum first. Absent if that combined offer was refused | +| `verdict` | `post_quantum` if the host accepts at least one post-quantum group, otherwise `classical` | + +Groups tested: `X25519MLKEM768`, `SecP256r1MLKEM768`, `SecP384r1MLKEM1024`, `MLKEM1024`, `x25519`, `secp256r1`, `secp384r1`, `secp521r1`. + +A `post_quantum` verdict says the host *supports* post-quantum key exchange. It is not a statement about every connection: only a client that negotiates one of those groups gets session keys that hold up if today's traffic is recorded and attacked with a quantum computer later, and a client that offers only classical groups still gets a classical exchange. `negotiated` shows what the host picks when offered everything. The verdict also says nothing about the certificate, which has its own verdicts and is `classical` for almost every host today. + +**`certificate`:** + +| Field | Description | +|-------|-------------| +| `chain` | The certificates the host sent, leaf first. Each has `subject`, `issuer`, `not_before`, `not_after`, `key_algorithm`, `key_bits` (omitted when the algorithm has no single size), `signature_algorithm`, `self_signed` | +| `sans` | The hostnames the leaf covers | +| `days_until_expiry` | Whole days until the leaf expires, as of `probed_at`. Negative once expired | +| `validity_days` | The leaf's total lifetime in days | +| `expiry_verdict` | `valid`, `expired`, or `not_yet_valid` | +| `algorithm_verdict` | `post_quantum`, `classical`, `weak`, or `unknown`: the weakest thing found anywhere in the chain | +| `trust_verdict` | `trusted` or `untrusted`: whether the chain the host sent leads to a root in the public trust store | +| `hostname_verdict` | `match` or `mismatch`: whether the leaf's subject alternative names cover the host asked about | + +`algorithm_verdict` values: `weak` is an RSA key under 2048 bits, an elliptic curve key under 224 bits, a DSA key, or a certificate signed with MD5 or SHA-1; `unknown` is an algorithm the service does not recognize; `classical` is sound today and breakable by a large quantum computer; `post_quantum` means every key and signature in the chain is ML-DSA. A self-signed certificate's own signature is not scored, so an old root signed with SHA-1 does not make a chain `weak`. + +`trust_verdict` is judged against the system root store in the API's container image, using only the certificates the host sent: nothing is fetched to repair a chain, so a host that leaves out an intermediate is `untrusted` even though some browsers would accept it. It is judged apart from the leaf's validity dates, which `expiry_verdict` already covers, so an expired certificate from a public CA reads `expired` and `trusted`, and stays distinguishable from one no public CA issued. + +There is no "expiring soon" verdict. What counts as soon depends on the certificate's lifetime and the caller's renewal process, so callers set their own threshold on `days_until_expiry`. + +**An untrusted, expired, or mismatched certificate is an answer, not an error.** The handshake deliberately skips verification so the certificate can be reported whatever its state; the verdicts carry the judgment. + +#### Failures + +A lookup either returns a complete answer or fails. A handshake has three outcomes: accepted, refused (the connection opened and the handshake then failed), and unknown (the connection never opened, or the handshake timed out). An unknown outcome fails the whole lookup instead of being recorded as a refusal, and failures are never cached, so asking again retries. + +| `errors[].message` | Meaning | +|--------------------|---------| +| `no such host` | The hostname does not resolve | +| `domain resolves to a private/reserved IP address` | Refused. The service only connects to public addresses | +| `connection refused` | Nothing is listening on port 443 | +| `i/o timeout`, `context deadline exceeded` | The connection or a handshake timed out | +| `no TLS handshake succeeded on port 443` | The host answered and refused every offer. This is an error and not a result because it cannot be told apart from a host blocking the probe | +| `invalid hostname`, `raw IP addresses are not accepted; provide a hostname` (lookup `validation`) | The entry is not a hostname. Returned per host only when other hosts in the request were valid; a request whose only host is invalid gets a `400` | + ### `GET /v1/usage` — My Usage (All Plans) Returns aggregated usage statistics for the authenticated customer. The customer filter always comes from the auth context — callers can only ever see their own usage. The response shape matches `GET /v1/admin/usage` below. @@ -726,6 +848,7 @@ Returns aggregated API usage statistics for a configurable time window. "avg_latency_ms": 842.5, "total_domains": 1580, "total_ips": 420, + "total_hosts": 96, "status_codes": {"200": 1190, "400": 32, "403": 15, "429": 10}, "feature_usage": { "whois": 900, "dns": 1100, "ssl": 870, "headers": 640, @@ -742,6 +865,8 @@ Returns aggregated API usage statistics for a configurable time window. `feature_usage` counts requests that **asked for** each lookup, whether or not it was served from cache. A cache hit is still customer demand. +`total_domains`, `total_ips` and `total_hosts` count the entries submitted to the domain, IP and encryption endpoints respectively, duplicates included. + ### `GET /v1/info` — Application Status (Admin Only) Returns application configuration, service status, and live runtime metrics. The response is built from a `StatusSnapshot` populated at startup (static config) plus live data computed per-request. @@ -753,7 +878,7 @@ Returns application configuration, service status, and live runtime metrics. The | `system` | App name, version, mode, session ID, start time, uptime, host, OS, kernel, arch, Go version, server timeouts | | `database` | PostgreSQL host, port, dbname, sslmode, connection pool settings | | `cache` | Redis addr/db, cache TTL, auth cache TTL, plus live: key count, memory used, ping latency (ms), auth cache size | -| `lookups` | Lookup timeout, subdomain/CT log limits, rate limits and max domains per plan | +| `lookups` | Lookup timeout, subdomain/CT log limits, rate limits and max domains, IPs and hosts per plan, encryption lookup and probe timeouts | | `services` | Notifications (enabled + alert config), billing (enabled, Stripe key mode `live`/`test`, config), threat intel (provider names), fingerprint (source + rule count), usage (buffer config), GeoIP (database file), metrics (whether the Prometheus listener is on, and its address) | | `runtime` | Goroutines, heap alloc/inuse (MB), sys memory (MB), GC count | | `postgres_pool` | Connection pool: open, in use, idle, wait count, wait duration | @@ -771,9 +896,10 @@ Lookup results are cached in Redis **per lookup, per domain** — not per respon ``` lookup:: # domain lookups, e.g. lookup:example.net:ssl ip:: # IP lookups, e.g. ip:8.8.8.8:reverse_dns +encryption:: # encryption lookups, e.g. encryption:example.net:certificate ``` -The two namespaces are separate, so `threat_intel` on a domain and on an IP never collide. Keys are built only from the normalized domain and lookup name, so the combination of lookups you request has no effect on cache reuse: a `dns`-only request warms the same `lookup:example.com:dns` entry that a later `dns` + `ssl` request reads from. +The namespaces are separate, so `threat_intel` on a domain and on an IP never collide, and a host on the encryption endpoint never shares an entry with the same name on the domain endpoint. Keys are built only from the normalized domain and lookup name, so the combination of lookups you request has no effect on cache reuse: a `dns`-only request warms the same `lookup:example.com:dns` entry that a later `dns` + `ssl` request reads from. Each lookup object in the response carries its own `cache_hit` flag, so a single result can mix cached and freshly fetched fields. Redis stores the lookup payload and nothing else — no request metadata, no cache flags, no timestamps. @@ -798,6 +924,9 @@ Every lookup has its own TTL, reflecting how fast that data actually changes. An | `abuse_contact` *(IP)* | 24h | | `asn` *(IP)* | 24h | | `geo` *(IP)* | never cached — local database read | +| `protocols` *(encryption)* | 12h | +| `key_exchange` *(encryption)* | 12h | +| `certificate` *(encryption)* | 4h | | *(anything else)* | `cache.default_ttl` (60m) | Override individually with env vars — `CACHE_TTL_WHOIS=48h`, `CACHE_DEFAULT_TTL=30m` — or in the config file under `cache.ttl.*`. diff --git a/docs/decisions.md b/docs/decisions.md index 7e450ba..6b38435 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -74,10 +74,13 @@ structurally impossible rather than merely avoided. ### Cache keys are flat and never re-normalized -**Decision.** Two namespaces, one shape: `lookup::` from `cache.LookupKey()` -and `ip::` from `cache.IPLookupKey()`, with the prefixes as constants beside -them. Neither builder normalizes; normalization is the handler's job. The separate `ip:` -prefix is what keeps `threat_intel` on the two endpoints from colliding. +**Decision.** Three namespaces, one shape: `lookup::` from `cache.LookupKey()`, +`ip::` from `cache.IPLookupKey()`, and `encryption::` from +`cache.EncryptionLookupKey()`, with the prefixes as constants beside them. No builder +normalizes; normalization is the handler's job. The separate `ip:` prefix is what keeps +`threat_intel` on the two endpoints from colliding. The `encryption:` prefix looks +redundant today, since no encryption lookup shares a name with a domain one, but a host is +a domain name: the first shared name would otherwise read the other endpoint's payload. **Why.** A missed normalization step surfaces as a distinct key — visibly wrong — rather than being silently papered over at the cache layer. @@ -191,6 +194,105 @@ until the lookup was removed; see #110. **Instead of.** Wrapping everything in interfaces for symmetry. `LookupDNS` behind an interface buys nothing and costs a layer of indirection at every call site. +## The encryption probe + +`internal/domain/encryption_probe.go` and the three lookups built on it (#136). The common +thread: these results are cached for hours, so a wrong answer is worse than no answer. + +### 2026-11-16 — A handshake that times out fails the lookup; it is never a refusal + +**Decision.** A handshake has three outcomes: accepted, refused (`rejectedError`: the TCP +connection opened and the handshake then failed), and unknown (the connection never +opened, or time ran out). Unknown fails the whole lookup. + +**Why.** A failed lookup is retried on the next request. A wrong "TLS 1.3 not accepted" +sits in the cache for twelve hours, and one lost packet is enough to produce it. + +**Instead of.** Counting silence as refusal. Some middleboxes drop offers they dislike +instead of refusing them, so those hosts fail the lookup every time. That cost was weighed +and accepted when the endpoint shipped. + +### 2026-11-16 — A lookup where nothing was accepted is an error, not an empty result + +**Decision.** When every offer is refused the lookup returns `ErrNoHandshake`. +`IsExpectedError` knows it, so it does not page. + +**Why.** "This host accepts no TLS version" cannot be told apart from "this host is +blocking us", and only the second is common. + +**Instead of.** Returning a payload with every `accepted` false, which reads as a finding +and would be cached as one. + +### 2026-11-16 — Every handshake in a lookup goes to one address, and only to port 443 + +**Decision.** `newSession` resolves once through `domain.Resolver()`, picks one public +address (IPv4 first), and every handshake in that lookup dials it. The payload reports it +as `ip`. The port is a constant. + +**Why.** A host with several addresses can be configured differently on each; mixing them +gives a result true of no single server. IPv4 first because a missing IPv6 route on our +side would be reported as the target's failure. A caller-supplied port turns the endpoint +into a port prober, which is a product decision and not a parameter. + +**Instead of.** Dialing the hostname each time and letting the dialer pick, as `LookupSSL` +does for its single connection. + +### 2026-11-16 — The handshake skips verification; the certificate lookup judges the chain afterwards + +**Decision.** Every probe sets `InsecureSkipVerify`. `certificate` then runs +`x509.Verify` itself and reports `trust_verdict` and `hostname_verdict`. The verification +error is dropped, never returned. Trust is judged at a moment inside the leaf's validity +window (now, or the nearest end of the window), using only the certificates the server +sent. + +**Why.** Reporting expired, self-signed and mismatched certificates is the feature; +verifying in the handshake would turn the answer into an error. The error is dropped +because `IsExpectedError` deliberately treats x509 failures as ours (they can otherwise +only come from trusted upstreams), so one escaping would page on every untrusted host a +customer checks. The clamped time keeps trust and expiry independent: otherwise every +expired certificate is also untrusted, and "renewal was missed" is indistinguishable from +"no public CA issued this". + +**Instead of.** Verifying at `probed_at`, or fetching missing intermediates the way some +browsers do. A chain that only verifies after a repair fails in strict clients, which is +what the caller wants to know. + +**The trust store is checked before it is used.** `checkTrustStore` fails the lookup with +`ErrTrustStoreUnavailable` when the system roots are missing *or empty*. The empty case +looks unnecessary and is the one that happens: on Linux an image with no CA bundle loads +an empty pool with no error, and every chain then verifies as "unknown authority". Without +the check every host would be `untrusted`, cached for hours, with nothing wrong in the +logs. That error is ours, so it is deliberately not in `IsExpectedError` and it alerts. + +### 2026-11-16 — The key exchange probe offers default cipher suites; the others offer every suite + +**Decision.** `protocols` and `certificate` offer every suite the standard library has, +insecure ones included, and every key exchange group it can speak. `key_exchange` leaves +the default (ECDHE-only) suite list and checks that the negotiated group is the one +offered. + +**Why.** A legacy server with only RSA key exchange or CBC suites left still speaks TLS, +and leaving those suites out would report it as refusing. The groups are listed +explicitly for the same reason at the other end of the range: the default offer omits +some groups (pure ML-KEM), so a server that requires one refused the handshake and was +reported as accepting no TLS version and having no certificate. For the group probe the +extra suites are a hazard: a TLS 1.2 server could finish the handshake over RSA key exchange +without using the group at all, and the group would read as accepted. + +**Instead of.** One shared `tls.Config` for all three probes. + +### 2026-11-16 — All three encryption lookups are on the free plan + +**Decision.** `encryptionLookupMinPlan` gates nothing. + +**Why.** Pro gating in this API has meant "spends scarce upstream quota" (`reputation`, +`threat_intel`). These spend none: measured at about 1 ms of CPU and 60–100 ms of wall time +per handshake, with the per-plan host cap and rate limit bounding the rest. Gating would be +a pricing decision, and none has been made. + +**Revisit if.** Pricing for the encryption product is decided. It is a one-word change per +row, and `TestEncryptionLookup_EveryLookupIsFree` is there to make it a deliberate one. + ## HTTP surface and API contract ### The lookup endpoint returns `{"results": [...]}`, not a bare array @@ -416,7 +518,9 @@ and were previously answered by the same number. ### `usage.LookupColumns` is asserted to match `domain.AllLookupNames` -**Decision.** A test fails when they diverge. +**Decision.** A test fails when they diverge. It compares against the union of every +catalog (domain, IP, encryption), so a new catalog has to be added to the test as well as +to `LookupColumns`. **Why.** A new lookup that nobody added a column for fails loudly in CI rather than silently in production, where the symptom is a feature that appears unused forever. diff --git a/docs/operations.md b/docs/operations.md index 564e1fc..c15a462 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -65,6 +65,10 @@ Config values: | `ip.lookup_timeout` | `30s` | Overall timeout for all concurrent IP lookups | | `ip.max_ips.free` | `1` | Maximum IPs per request for free plan | | `ip.max_ips.pro` | `20` | Maximum IPs per request for pro plan | +| `encryption.lookup_timeout` | `30s` | Timeout for one encryption lookup, which is up to nine handshakes run in turn | +| `encryption.probe_timeout` | `5s` | Timeout for a single handshake inside a lookup, TCP connect included | +| `encryption.max_hosts.free` | `1` | Maximum hosts per encryption request for free plan | +| `encryption.max_hosts.pro` | `20` | Maximum hosts per encryption request for pro plan | | `domain.lookup_timeout` | `30s` | Overall timeout for all concurrent lookups per domain | | `domain.max_domains.free` | `1` | Maximum domains per request for free plan | | `domain.max_domains.pro` | `20` | Maximum domains per request for pro plan | @@ -127,6 +131,7 @@ The `migrations/` directory contains SQL files that are automatically applied wh - `015_request_log_ip_lookups.sql` — adds `geo`/`asn`/`reverse_dns`/`abuse_contact` columns now that IP lookups are individually selectable - `016_drop_request_log_cache_hit.sql` — drops the superseded `cache_hit` column. **Apply only after a build that no longer writes it (v0.55.0+) is deployed** — see below - `017_merge_basic_into_pro.sql` — moves any `basic` customer to `pro` and resets the `plan` column default from `basic` to `free`. **Apply before deploying the build that removes the plan (v0.73.0+)** — a surviving `basic` row is an unrecognized plan to that build and reads as `free` until this runs +- `018_request_log_encryption.sql` — adds `host_count` and the `protocols`/`key_exchange`/`certificate` columns for the encryption endpoint. **Apply before deploying the build that adds the endpoint**: that build names these columns in every usage insert, for every endpoint, so without them usage logging fails until the migration runs (requests are still served) - `seed.sql` — inserts test customers (admin, pro, free) with hashed keys API keys are stored as SHA-256 hashes. When inserting a key manually, hash it first: @@ -330,6 +335,7 @@ scripted and CI use: sactl # interactive menu sactl lookup domain example.com --lookups dns,ssl,risk sactl lookup ip 8.8.8.8 --lookups all +sactl lookup encryption example.com --lookups key_exchange,certificate sactl customer list sactl customer create --name "Acme" --plan pro --email ops@acme.com sactl customer plan --id 12 --plan pro @@ -457,7 +463,7 @@ How to read the labels: - **`route`** is the route template (`/v1/domain/lookup`), never the path as sent. A request that matched no route is `unmatched`, and a method outside the standard set is `other`, so a scanner cannot create a series per request. - **`plan`** is the caller's plan, or `none` for a request with no valid API key (docs pages, health checks, failed authentication). -- **`scope`** is `domain` or `ip`. It keeps the two `threat_intel` lookups apart. +- **`scope`** is `domain`, `ip`, or `host` for the encryption endpoint. It keeps the two `threat_intel` lookups apart. - **`lookup`** is a name from the lookup catalog. `fingerprint` and `risk` never appear: both are computed from other lookups and are never fetched. A `fingerprint` request shows up as `headers`. - **`outcome`** is `ok`, `error` or `timeout`. A fan-out lookup (`reputation`, `threat_intel`) is an `error` when any provider failed, even if it returned a partial result, which is the same line the cache draws when it declines to store one. - **Cache hits and coalesced callers are not in the lookup histogram.** It times work that went upstream, so a warm cache does not make a slow provider look fast. diff --git a/integration_test.go b/integration_test.go index 2a09074..4da6d27 100644 --- a/integration_test.go +++ b/integration_test.go @@ -116,6 +116,8 @@ func testConfig() *viper.Viper { cfg.Set("domain.max_domains.pro", 20) cfg.Set("ip.max_ips.free", 1) cfg.Set("ip.max_ips.pro", 20) + cfg.Set("encryption.max_hosts.free", 1) + cfg.Set("encryption.max_hosts.pro", 20) return cfg } @@ -139,6 +141,9 @@ var testCacheTTLs = map[string]time.Duration{ domain.LookupASNName: 22 * time.Hour, domain.LookupReverseDNSName: 6 * time.Hour, domain.LookupAbuseContactName: 24 * time.Hour, + domain.LookupProtocolsName: 12 * time.Hour, + domain.LookupKeyExchangeName: 11 * time.Hour, + domain.LookupCertificateName: 3 * time.Hour, } // decodeResults unwraps the {"results": [...]} envelope returned by the domain @@ -162,6 +167,23 @@ func decodeIPResults(t *testing.T, w *httptest.ResponseRecorder) []*domain.IPRes return env.Results } +// decodeEncryptionResults unwraps the {"results": [...]} envelope from the +// encryption endpoint. +func decodeEncryptionResults(t *testing.T, w *httptest.ResponseRecorder) []*domain.EncryptionResponse { + t.Helper() + var env domain.EncryptionResponseEnvelope + if err := json.Unmarshal(w.Body.Bytes(), &env); err != nil { + t.Fatalf("failed to unmarshal encryption response envelope: %v\nbody: %s", err, w.Body.String()) + } + return env.Results +} + +// encryptionRedisKey returns the namespaced Redis key for a per-lookup +// encryption cache entry. +func encryptionRedisKey(host, lookupName string) string { + return "intel:" + cache.EncryptionLookupKey(host, lookupName) +} + // ipRedisKey returns the namespaced Redis key for a per-lookup IP cache entry. func ipRedisKey(ip, lookupName string) string { return "intel:" + cache.IPLookupKey(ip, lookupName) @@ -337,6 +359,50 @@ func setupRouterWithUsage(t *testing.T) (*gin.Engine, *miniredis.Miniredis, *rec }, ) + // Encryption service with stubs. The real lookups make TLS handshakes to + // the target, which no test may do. nosuchhost.example stands in for a + // host that fails every lookup. + evidence := domain.Evidence{IP: "93.184.216.34", ProbedAt: time.Date(2026, 11, 9, 12, 0, 0, 0, time.UTC)} + encSvc := service.NewEncryptionService(rc, defaultTestTTL, testCacheTTLs, 30*time.Second, ¬ifications.NoopRecorder{}, nil) + encSvc.SetLookups( + func(_ context.Context, host string) (*domain.ProtocolsInfo, error) { + if host == "nosuchhost.example" { + return nil, &net.DNSError{Err: "no such host", Name: host, IsNotFound: true} + } + return &domain.ProtocolsInfo{ + Evidence: evidence, + Versions: []domain.ProtocolVersion{ + {Name: "TLS 1.3", Accepted: true}, {Name: "TLS 1.2", Accepted: true}, + {Name: "TLS 1.1", Accepted: false}, {Name: "TLS 1.0", Accepted: false}, + }, + }, nil + }, + func(_ context.Context, _ string) (*domain.KeyExchangeInfo, error) { + return &domain.KeyExchangeInfo{ + Evidence: evidence, + Groups: []domain.KeyExchangeGroup{ + {Name: "X25519MLKEM768", Accepted: true, PostQuantum: true}, + {Name: "x25519", Accepted: true}, + }, + Negotiated: "X25519MLKEM768", + Verdict: domain.KeyExchangePostQuantum, + }, nil + }, + func(_ context.Context, _ string) (*domain.CertificateInfo, error) { + return &domain.CertificateInfo{ + Evidence: evidence, + Chain: []domain.ChainCertificate{{Subject: "example.com", Issuer: "Test CA", KeyAlgorithm: "ECDSA", KeyBits: 256, SignatureAlgorithm: "ECDSA-SHA384"}}, + SANs: []string{"example.com"}, + DaysUntilExpiry: 61, + ValidityDays: 90, + ExpiryVerdict: domain.ExpiryValid, + AlgorithmVerdict: domain.AlgorithmsClassical, + TrustVerdict: domain.TrustTrusted, + HostnameVerdict: domain.HostnameMatch, + }, nil + }, + ) + fpSvc := newStubFingerprintService() repo := newStubRepo() @@ -363,6 +429,7 @@ func setupRouterWithUsage(t *testing.T) (*gin.Engine, *miniredis.Miniredis, *rec h := handler.New(handler.Deps{ DomainService: svc, IPService: ipSvc, + EncryptionService: encSvc, FingerprintService: fpSvc, UsageService: usageQ, Config: cfg, @@ -2731,3 +2798,209 @@ func TestIntegration_IPLookup_DedupesAndRecordsInputs(t *testing.T) { t.Errorf("inputs = %v, want both verbatim entries", google.Inputs) } } + +// ==================== Encryption Lookup Integration Tests ==================== + +func postEncryption(t *testing.T, r *gin.Engine, apiKey, body string) *httptest.ResponseRecorder { + t.Helper() + w := httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/v1/encryption/lookup", strings.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + if apiKey != "" { + req.Header.Set("X-API-Key", apiKey) + } + r.ServeHTTP(w, req) + return w +} + +func TestIntegration_EncryptionLookup_FullFlow(t *testing.T) { + r, _ := setupRouter(t) + + w := postEncryption(t, r, "test-admin-key", + `{"hosts":["https://Example.com:8443/path"],"lookups":["protocols","key_exchange","certificate"]}`) + if w.Code != http.StatusOK { + t.Fatalf("status = %d, want %d; body: %s", w.Code, http.StatusOK, w.Body.String()) + } + + results := decodeEncryptionResults(t, w) + if len(results) != 1 { + t.Fatalf("expected 1 result, got %d", len(results)) + } + res := results[0] + if res.Host != "example.com" { + t.Errorf("host = %q, want the normalized example.com", res.Host) + } + if res.Protocols == nil || len(res.Protocols.Versions) != 4 { + t.Errorf("protocols = %+v, want four versions", res.Protocols) + } + if res.KeyExchange == nil || res.KeyExchange.Verdict != domain.KeyExchangePostQuantum { + t.Errorf("key_exchange = %+v, want a post_quantum verdict", res.KeyExchange) + } + if res.Certificate == nil || res.Certificate.TrustVerdict != domain.TrustTrusted || res.Certificate.HostnameVerdict != domain.HostnameMatch { + t.Errorf("certificate = %+v, want trusted and matching", res.Certificate) + } + if len(res.Errors) != 0 { + t.Errorf("errors = %+v, want none", res.Errors) + } + + // The evidence fields are part of every payload on the wire, beside + // cache_hit rather than nested under it. + var wire struct { + Results []struct { + Certificate map[string]any `json:"certificate"` + } `json:"results"` + } + if err := json.Unmarshal(w.Body.Bytes(), &wire); err != nil { + t.Fatalf("decode wire shape: %v", err) + } + for _, field := range []string{"cache_hit", "ip", "probed_at", "chain", "trust_verdict", "hostname_verdict"} { + if _, ok := wire.Results[0].Certificate[field]; !ok { + t.Errorf("certificate payload is missing %q on the wire", field) + } + } +} + +func TestIntegration_EncryptionLookup_CachesPerLookupInItsOwnKeyspace(t *testing.T) { + r, mr := setupRouter(t) + body := `{"hosts":["example.com"],"lookups":["key_exchange","certificate"]}` + + first := decodeEncryptionResults(t, postEncryption(t, r, "test-admin-key", body)) + if first[0].KeyExchange.CacheHit || first[0].Certificate.CacheHit { + t.Error("first request reported a cache hit") + } + + for name, want := range map[string]time.Duration{ + domain.LookupKeyExchangeName: 11 * time.Hour, + domain.LookupCertificateName: 3 * time.Hour, + } { + key := encryptionRedisKey("example.com", name) + if !mr.Exists(key) { + t.Errorf("expected redis key %s", key) + continue + } + if got := mr.TTL(key); got != want { + t.Errorf("%s TTL = %v, want %v", name, got, want) + } + } + // A host is a domain name: the same name on the domain endpoint must not + // share an entry with this one. + if mr.Exists(redisKey("example.com", domain.LookupCertificateName)) { + t.Error("encryption result landed in the domain keyspace") + } + if mr.Exists(encryptionRedisKey("example.com", domain.LookupProtocolsName)) { + t.Error("protocols was cached without being requested") + } + + second := decodeEncryptionResults(t, postEncryption(t, r, "test-admin-key", body)) + if !second[0].KeyExchange.CacheHit || !second[0].Certificate.CacheHit { + t.Error("second request was not served from cache") + } + if !second[0].Certificate.ProbedAt.Equal(first[0].Certificate.ProbedAt) { + t.Error("probed_at changed on a cached result; it must report when the handshake was made") + } +} + +func TestIntegration_EncryptionLookup_EveryPlanMayUseEveryLookup(t *testing.T) { + r, _ := setupRouter(t) + body := `{"hosts":["example.com"],"lookups":["protocols","key_exchange","certificate"]}` + + for _, key := range []string{"test-free-key", "test-pro-key", "test-admin-key"} { + if w := postEncryption(t, r, key, body); w.Code != http.StatusOK { + t.Errorf("%s: status = %d, want 200; body: %s", key, w.Code, w.Body.String()) + } + } +} + +func TestIntegration_EncryptionLookup_Rejections(t *testing.T) { + r, _ := setupRouter(t) + + tests := []struct { + name string + key string + body string + want int + }{ + {"no key", "", `{"hosts":["example.com"],"lookups":["certificate"]}`, http.StatusUnauthorized}, + {"unknown key", "nope", `{"hosts":["example.com"],"lookups":["certificate"]}`, http.StatusUnauthorized}, + {"missing lookups", "test-pro-key", `{"hosts":["example.com"]}`, http.StatusBadRequest}, + {"domain lookup name", "test-pro-key", `{"hosts":["example.com"],"lookups":["ssl"]}`, http.StatusBadRequest}, + {"ip lookup name", "test-pro-key", `{"hosts":["example.com"],"lookups":["geo"]}`, http.StatusBadRequest}, + {"raw ip", "test-pro-key", `{"hosts":["93.184.216.34"],"lookups":["certificate"]}`, http.StatusBadRequest}, + {"free plan host limit", "test-free-key", `{"hosts":["a.example.com","b.example.com"],"lookups":["certificate"]}`, http.StatusBadRequest}, + {"invalid body", "test-pro-key", `{`, http.StatusBadRequest}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if w := postEncryption(t, r, tt.key, tt.body); w.Code != tt.want { + t.Errorf("status = %d, want %d; body: %s", w.Code, tt.want, w.Body.String()) + } + }) + } +} + +// A failing lookup is reported on its host and leaves the rest of the response +// intact; an invalid entry among valid ones becomes a validation result. +func TestIntegration_EncryptionLookup_PartialFailureAndMixedHosts(t *testing.T) { + r, mr := setupRouter(t) + + w := postEncryption(t, r, "test-pro-key", + `{"hosts":["nosuchhost.example","example.com","localhost"],"lookups":["protocols","certificate"]}`) + if w.Code != http.StatusOK { + t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String()) + } + + byHost := map[string]*domain.EncryptionResponse{} + for _, res := range decodeEncryptionResults(t, w) { + byHost[res.Host] = res + } + if len(byHost) != 3 { + t.Fatalf("got results for %d hosts, want 3", len(byHost)) + } + + failed := byHost["nosuchhost.example"] + if failed.Protocols != nil || failed.Certificate == nil { + t.Errorf("failing host = %+v, want protocols absent and certificate present", failed) + } + if len(failed.Errors) != 1 || failed.Errors[0].Lookup != domain.LookupProtocolsName || failed.Errors[0].Message != "no such host" { + t.Errorf("errors = %+v, want one sanitized protocols error", failed.Errors) + } + if mr.Exists(encryptionRedisKey("nosuchhost.example", domain.LookupProtocolsName)) { + t.Error("a failed lookup was cached") + } + + if ok := byHost["example.com"]; ok.Protocols == nil || len(ok.Errors) != 0 { + t.Errorf("healthy host = %+v, want protocols and no errors", ok) + } + + invalid := byHost["localhost"] + if len(invalid.Errors) != 1 || invalid.Errors[0].Lookup != "validation" || invalid.Errors[0].Message != "invalid hostname" { + t.Errorf("invalid host errors = %+v, want one validation error", invalid.Errors) + } +} + +func TestIntegration_EncryptionLookup_UsageRecordsHostsAndLookups(t *testing.T) { + r, _, rec := setupRouterWithUsage(t) + + w := postEncryption(t, r, "test-admin-key", + `{"hosts":["example.com","EXAMPLE.com"],"lookups":["protocols","certificate"]}`) + if w.Code != http.StatusOK { + t.Fatalf("status = %d; body: %s", w.Code, w.Body.String()) + } + + e := rec.last(t) + // Submitted entries, not unique hosts, and not counted as domains. + if e.HostCount != 2 || e.DomainCount != 0 || e.IPCount != 0 { + t.Errorf("counts = hosts %d, domains %d, ips %d; want 2, 0, 0", e.HostCount, e.DomainCount, e.IPCount) + } + lookups := slices.Clone(e.Lookups) + slices.Sort(lookups) + if want := []string{"certificate", "protocols"}; !slices.Equal(lookups, want) { + t.Errorf("lookups = %v, want %v", lookups, want) + } + if e.CacheHits != 0 || e.CacheMisses != 2 { + t.Errorf("cache = %d hits, %d misses; want 0 and 2", e.CacheHits, e.CacheMisses) + } + if e.Path != "/v1/encryption/lookup" { + t.Errorf("path = %q", e.Path) + } +} diff --git a/internal/app/app.go b/internal/app/app.go index 7447fdb..5e733d9 100644 --- a/internal/app/app.go +++ b/internal/app/app.go @@ -5,6 +5,7 @@ import ( "fmt" "os" "os/signal" + "slices" "syscall" "github.com/security-accelerated/intelligence-api/internal/auth" @@ -28,8 +29,9 @@ func Run(logger *zap.Logger, version string) error { logger = logger.With(zap.String("version", version)) cfg := config.Config() - // Both catalogs, so /info reports the same TTL table the services resolve. - lookupNames := append(append([]string{}, domain.AllLookupNames...), domain.AllIPLookupNames...) + // Every catalog, so /info reports the same TTL table the services resolve. + // A catalog left out here has its cache.ttl.* keys silently ignored. + lookupNames := slices.Concat(domain.AllLookupNames, domain.AllIPLookupNames, domain.AllEncryptionLookupNames) status := config.NewStatusSnapshot(version, lookupNames) @@ -292,10 +294,18 @@ func Run(logger *zap.Logger, version string) error { // IP intelligence service ipService := service.NewIPService(redisCache, defaultCacheTTL, cacheTTLs, cfg.GetDuration("ip.lookup_timeout"), geoReader, alerter, ipTIProviders, m) + // Encryption posture service. The per-handshake timeout is a domain + // package var like the other lookup limits above. + if v := cfg.GetDuration("encryption.probe_timeout"); v > 0 { + domain.EncryptionProbeTimeout = v + } + encryptionService := service.NewEncryptionService(redisCache, defaultCacheTTL, cacheTTLs, cfg.GetDuration("encryption.lookup_timeout"), alerter, m) + // HTTP h := handler.New(handler.Deps{ DomainService: domainService, IPService: ipService, + EncryptionService: encryptionService, FingerprintService: fpService, BillingService: billingSvc, UsageService: usageQuerySvc, diff --git a/internal/cache/cache.go b/internal/cache/cache.go index c99e90d..d36a0d2 100644 --- a/internal/cache/cache.go +++ b/internal/cache/cache.go @@ -35,3 +35,17 @@ const IPLookupKeyPrefix = "ip:" func IPLookupKey(ip, lookupName string) string { return IPLookupKeyPrefix + ip + ":" + lookupName } + +// EncryptionLookupKeyPrefix namespaces per-lookup encryption cache entries. +// Keys have the shape "encryption::". A host is a domain +// name, so without its own prefix an encryption lookup would share a keyspace +// with the domain endpoint and a future name reused across the two would +// collide. +const EncryptionLookupKeyPrefix = "encryption:" + +// EncryptionLookupKey builds the cache key for a single encryption lookup on a +// single host. The host must already be normalized; like LookupKey this never +// re-normalizes its inputs. +func EncryptionLookupKey(host, lookupName string) string { + return EncryptionLookupKeyPrefix + host + ":" + lookupName +} diff --git a/internal/cache/key_test.go b/internal/cache/key_test.go index 3b6da5f..b381fb9 100644 --- a/internal/cache/key_test.go +++ b/internal/cache/key_test.go @@ -59,3 +59,15 @@ func TestLookupKey_DistinctPerDomainAndLookup(t *testing.T) { t.Errorf("built %d distinct keys, want 6", len(seen)) } } + +// A host is a domain name, so the encryption endpoint needs its own keyspace: +// the same name on the two endpoints must never share a cache entry. +func TestEncryptionLookupKey_SeparateFromDomainKeys(t *testing.T) { + got := EncryptionLookupKey("example.com", "certificate") + if got != "encryption:example.com:certificate" { + t.Errorf("EncryptionLookupKey() = %q, want %q", got, "encryption:example.com:certificate") + } + if got == LookupKey("example.com", "certificate") { + t.Error("encryption and domain keys collide for the same host and lookup") + } +} diff --git a/internal/config/config.go b/internal/config/config.go index 458a345..6343a55 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -92,6 +92,11 @@ func setDefaults(v *viper.Viper) { v.SetDefault("cache.ttl.asn", "24h") v.SetDefault("cache.ttl.reverse_dns", "6h") v.SetDefault("cache.ttl.abuse_contact", "24h") + // Encryption lookups. A server's TLS configuration changes rarely; its + // certificate is watched more closely because expiry is counted in days. + v.SetDefault("cache.ttl.protocols", "12h") + v.SetDefault("cache.ttl.key_exchange", "12h") + v.SetDefault("cache.ttl.certificate", "4h") v.SetDefault("auth.cache_ttl", "5m") v.SetDefault("auth.rotation_grace", "24h") v.SetDefault("subdomain.http_timeout", "15s") @@ -149,6 +154,12 @@ func setDefaults(v *viper.Viper) { v.SetDefault("ip.lookup_timeout", "30s") v.SetDefault("ip.max_ips.free", 1) v.SetDefault("ip.max_ips.pro", 20) + // lookup_timeout bounds one encryption lookup, which is several handshakes + // run in turn. probe_timeout bounds a single handshake inside it. + v.SetDefault("encryption.lookup_timeout", "30s") + v.SetDefault("encryption.probe_timeout", "5s") + v.SetDefault("encryption.max_hosts.free", 1) + v.SetDefault("encryption.max_hosts.pro", 20) // The Prometheus endpoint is off unless asked for: enabling it opens a // second listener, which should never appear on an upgrade unannounced. v.SetDefault("metrics.enabled", false) diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 1605594..38d0dc4 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -45,6 +45,13 @@ func TestConfig_Defaults(t *testing.T) { {"geoip.city_db", "dbip-city-lite.mmdb"}, {"geoip.max_age", "720h"}, {"cache.ttl.asn", "24h"}, + {"encryption.lookup_timeout", "30s"}, + {"encryption.probe_timeout", "5s"}, + {"encryption.max_hosts.free", 1}, + {"encryption.max_hosts.pro", 20}, + {"cache.ttl.protocols", "12h"}, + {"cache.ttl.key_exchange", "12h"}, + {"cache.ttl.certificate", "4h"}, {"postgres.sslmode", "require"}, // Off by default: turning it on opens a second, unauthenticated listener. {"metrics.enabled", false}, diff --git a/internal/config/sample-config.yml b/internal/config/sample-config.yml index 27012ea..3cd877c 100644 --- a/internal/config/sample-config.yml +++ b/internal/config/sample-config.yml @@ -43,6 +43,10 @@ cache: asn: 24h reverse_dns: 6h abuse_contact: 24h + # Encryption lookups. + protocols: 12h + key_exchange: 12h + certificate: 4h auth: cache_ttl: 5m @@ -123,6 +127,14 @@ ip: free: 1 pro: 20 +# Encryption posture lookups: TLS handshakes we make to port 443 of each host. +encryption: + lookup_timeout: 30s # one lookup, which is up to nine handshakes in turn + probe_timeout: 5s # one handshake, TCP connect included + max_hosts: + free: 1 + pro: 20 + # DB-IP Lite City (CC BY 4.0), downloaded in the background when missing or # stale. No key needed. The asn lookup uses Team Cymru DNS and needs no file. geoip: diff --git a/internal/config/status.go b/internal/config/status.go index 6c1e344..a2479f6 100644 --- a/internal/config/status.go +++ b/internal/config/status.go @@ -86,6 +86,10 @@ type LookupConfig struct { IPTimeout string `json:"ip_timeout"` MaxIPsFree int `json:"max_ips_free"` MaxIPsPro int `json:"max_ips_pro"` + EncryptionTimeout string `json:"encryption_timeout"` + EncryptionProbe string `json:"encryption_probe_timeout"` + MaxHostsFree int `json:"max_hosts_free"` + MaxHostsPro int `json:"max_hosts_pro"` } type ServicesStatus struct { @@ -208,6 +212,10 @@ func NewStatusSnapshot(version string, lookupNames []string) *StatusSnapshot { IPTimeout: cfg.GetDuration("ip.lookup_timeout").String(), MaxIPsFree: cfg.GetInt("ip.max_ips.free"), MaxIPsPro: cfg.GetInt("ip.max_ips.pro"), + EncryptionTimeout: cfg.GetDuration("encryption.lookup_timeout").String(), + EncryptionProbe: cfg.GetDuration("encryption.probe_timeout").String(), + MaxHostsFree: cfg.GetInt("encryption.max_hosts.free"), + MaxHostsPro: cfg.GetInt("encryption.max_hosts.pro"), }, } } diff --git a/internal/domain/encryption_certificate.go b/internal/domain/encryption_certificate.go new file mode 100644 index 0000000..ea9fa2d --- /dev/null +++ b/internal/domain/encryption_certificate.go @@ -0,0 +1,271 @@ +package domain + +import ( + "bytes" + "context" + "crypto/ecdsa" + "crypto/ed25519" + "crypto/rsa" + "crypto/tls" + "crypto/x509" + "errors" + "math" + "time" +) + +// LookupCertificate reports the certificate chain host presents on port 443: +// the algorithms each certificate uses, when the leaf expires, whether the +// chain leads to a publicly trusted root, and whether the leaf covers host. +func LookupCertificate(ctx context.Context, host string) (*CertificateInfo, error) { + s, err := newSession(ctx, host) + if err != nil { + return nil, err + } + return probeCertificate(ctx, s) +} + +// probeCertificate makes one handshake, as permissive as the client can be, +// and describes the chain the server sent. This is the chain a client with +// current defaults receives; a server holding both an RSA and an ECDSA +// certificate picks one per connection. +func probeCertificate(ctx context.Context, s *session) (*CertificateInfo, error) { + // Down to TLS 1.0 with every cipher suite, so that a server too old for + // current defaults still gets its certificate reported, and with every + // group, so that one requiring a key exchange outside those defaults does + // too. + //nolint:gosec // G402: reaching legacy servers is the feature. + state, err := s.handshake(ctx, &tls.Config{ + MinVersion: tls.VersionTLS10, + CipherSuites: everyCipherSuite(), + CurvePreferences: everyGroup(), + }) + if err != nil { + var rejected *rejectedError + if errors.As(err, &rejected) { + return nil, ErrNoHandshake + } + return nil, err + } + if len(state.PeerCertificates) == 0 { + return nil, errors.New("server presented no certificate") + } + // Without a trust store there is no trust verdict to give, and guessing + // "untrusted" would be cached as a finding about the host. Fail the lookup + // instead: it is retried, and the failure alerts. + roots, err := s.roots() + if err != nil { + return nil, err + } + return describeChain(state.PeerCertificates, s.host, roots, s.evidence()), nil +} + +// describeChain builds the certificate payload from a chain, leaf first. Split +// from the handshake so the verdict rules can be tested on certificates built +// in memory. roots is the trust store for the trust verdict and must not be +// nil: a nil pool would make x509 fall back to whatever the machine has. +func describeChain(chain []*x509.Certificate, host string, roots *x509.CertPool, ev Evidence) *CertificateInfo { + leaf := chain[0] + info := &CertificateInfo{ + Evidence: ev, + SANs: leaf.DNSNames, + DaysUntilExpiry: int(math.Floor(leaf.NotAfter.Sub(ev.ProbedAt).Hours() / 24)), + ValidityDays: int(math.Round(leaf.NotAfter.Sub(leaf.NotBefore).Hours() / 24)), + ExpiryVerdict: expiryVerdict(leaf, ev.ProbedAt), + TrustVerdict: trustVerdict(chain, roots, ev.ProbedAt), + HostnameVerdict: hostnameVerdict(leaf, host), + } + + strength := strengthPostQuantum + for _, cert := range chain { + selfSigned := isSelfSigned(cert) + info.Chain = append(info.Chain, ChainCertificate{ + Subject: displayName(cert.Subject.CommonName, cert.Subject.String()), + Issuer: displayName(cert.Issuer.CommonName, cert.Issuer.String()), + NotBefore: cert.NotBefore, + NotAfter: cert.NotAfter, + KeyAlgorithm: cert.PublicKeyAlgorithm.String(), + KeyBits: keyBits(cert), + SignatureAlgorithm: cert.SignatureAlgorithm.String(), + SelfSigned: selfSigned, + }) + + strength = min(strength, keyStrength(cert)) + // A self-signed certificate's signature is made with its own key and + // protects nothing: a trust anchor is trusted by being installed, not + // by its signature. Old roots signed with SHA-1 are not a weakness. + if !selfSigned { + strength = min(strength, signatureStrength(cert.SignatureAlgorithm)) + } + } + info.AlgorithmVerdict = strength.verdict() + + return info +} + +// isSelfSigned reports whether cert was signed with its own key. Matching +// subject and issuer names only make a certificate self-issued: a CA rolling +// over to a new key can publish a certificate with the same name on both +// sides, signed by the old key. That one is an ordinary link in the chain and +// its signature has to be scored like any other. +// +// When the signature cannot be checked at all (an algorithm the standard +// library refuses, such as MD5, or does not implement), the names are all +// there is to go on, and the certificate is treated as self-signed as before. +func isSelfSigned(cert *x509.Certificate) bool { + if !bytes.Equal(cert.RawSubject, cert.RawIssuer) { + return false + } + err := cert.CheckSignature(cert.SignatureAlgorithm, cert.RawTBSCertificate, cert.Signature) + if err == nil { + return true + } + var insecure x509.InsecureAlgorithmError + return errors.As(err, &insecure) || errors.Is(err, x509.ErrUnsupportedAlgorithm) +} + +// algorithmStrength orders the algorithm verdicts so a chain can be scored by +// its weakest part. +type algorithmStrength int + +const ( + strengthWeak algorithmStrength = iota + strengthUnknown + strengthClassical + strengthPostQuantum +) + +func (s algorithmStrength) verdict() string { + switch s { + case strengthWeak: + return AlgorithmsWeak + case strengthClassical: + return AlgorithmsClassical + case strengthPostQuantum: + return AlgorithmsPostQuantum + default: + return AlgorithmsUnknown + } +} + +// keyStrength scores a certificate's public key. The size floors are the ones +// public CAs have enforced for years: 2048-bit RSA and 224-bit elliptic curves. +func keyStrength(cert *x509.Certificate) algorithmStrength { + switch cert.PublicKeyAlgorithm { + case x509.RSA: + if keyBits(cert) < 2048 { + return strengthWeak + } + return strengthClassical + case x509.ECDSA: + if keyBits(cert) < 224 { + return strengthWeak + } + return strengthClassical + case x509.Ed25519: + return strengthClassical + case x509.DSA: + return strengthWeak + case x509.MLDSA: + return strengthPostQuantum + default: + return strengthUnknown + } +} + +// signatureStrength scores the algorithm a certificate was signed with. +func signatureStrength(alg x509.SignatureAlgorithm) algorithmStrength { + switch alg { + case x509.MD2WithRSA, x509.MD5WithRSA, x509.SHA1WithRSA, + x509.DSAWithSHA1, x509.DSAWithSHA256, x509.ECDSAWithSHA1: + return strengthWeak + case x509.MLDSA44, x509.MLDSA65, x509.MLDSA87: + return strengthPostQuantum + case x509.UnknownSignatureAlgorithm: + return strengthUnknown + default: + return strengthClassical + } +} + +// keyBits returns the public key size in bits, or 0 when it has no single +// meaningful size to report. +func keyBits(cert *x509.Certificate) int { + switch key := cert.PublicKey.(type) { + case *rsa.PublicKey: + return key.N.BitLen() + case *ecdsa.PublicKey: + return key.Curve.Params().BitSize + case ed25519.PublicKey: + return 256 + default: + return 0 + } +} + +func expiryVerdict(leaf *x509.Certificate, now time.Time) string { + switch { + case now.Before(leaf.NotBefore): + return ExpiryNotYetValid + case now.After(leaf.NotAfter): + return ExpiryExpired + default: + return ExpiryValid + } +} + +// trustVerdict reports whether the chain leads to a root in roots, using the +// certificates the server sent as intermediates. Nothing is fetched: a server +// that leaves out an intermediate is untrusted here even though some browsers +// would repair the chain, because a strict client fails on it. +// +// The chain is judged at a moment inside the leaf's validity window: now when +// the leaf is current, otherwise the nearest end of the window. Expiry has its +// own verdict, and folding it in here would make every expired certificate +// untrusted as well, hiding the difference between "renewal was missed" and +// "this was never issued by a public CA". +// +// The verification error is deliberately dropped. It is an answer about the +// target, reported as data, and must never come back as the lookup's error: +// IsExpectedError treats x509 failures as ours. +func trustVerdict(chain []*x509.Certificate, roots *x509.CertPool, now time.Time) string { + leaf := chain[0] + at := now + if at.Before(leaf.NotBefore) { + at = leaf.NotBefore + } else if at.After(leaf.NotAfter) { + at = leaf.NotAfter + } + + intermediates := x509.NewCertPool() + for _, cert := range chain[1:] { + intermediates.AddCert(cert) + } + + // No DNSName: the hostname has its own verdict. + if _, err := leaf.Verify(x509.VerifyOptions{ + Roots: roots, + Intermediates: intermediates, + CurrentTime: at, + }); err != nil { + return TrustUntrusted + } + return TrustTrusted +} + +// hostnameVerdict reports whether the leaf covers host, by the rules a browser +// applies: subject alternative names only, wildcards one label deep. +func hostnameVerdict(leaf *x509.Certificate, host string) string { + if leaf.VerifyHostname(host) != nil { + return HostnameMismatch + } + return HostnameMatch +} + +// displayName prefers a certificate's common name and falls back to the full +// distinguished name for certificates issued without one. +func displayName(commonName, full string) string { + if commonName != "" { + return commonName + } + return full +} diff --git a/internal/domain/encryption_certificate_test.go b/internal/domain/encryption_certificate_test.go new file mode 100644 index 0000000..fdb4528 --- /dev/null +++ b/internal/domain/encryption_certificate_test.go @@ -0,0 +1,283 @@ +package domain + +import ( + "crypto/mldsa" + "crypto/rand" + "crypto/rsa" + "crypto/x509" + "testing" + "time" +) + +func rsaKey(t *testing.T, bits int) *rsa.PrivateKey { + t.Helper() + key, err := rsa.GenerateKey(rand.Reader, bits) + if err != nil { + t.Fatalf("generate %d-bit rsa key: %v", bits, err) + } + return key +} + +func TestDescribeChain_AlgorithmVerdict(t *testing.T) { + valid := func(spec certSpec) certSpec { + spec.notBefore, spec.notAfter = testNow.AddDate(0, 0, -1), testNow.AddDate(0, 0, 30) + return spec + } + ev := Evidence{IP: "93.184.216.34", ProbedAt: testNow} + + caKey := ecdsaKey(t) + ca, _ := makeCert(t, valid(certSpec{cn: "Test CA", key: caKey, isCA: true})) + + pqKey, err := mldsa.GenerateKey(mldsa.MLDSA65()) + if err != nil { + t.Fatalf("generate ml-dsa key: %v", err) + } + pqCA, _ := makeCert(t, valid(certSpec{cn: "PQ CA", key: pqKey, isCA: true})) + pqLeafKey, err := mldsa.GenerateKey(mldsa.MLDSA65()) + if err != nil { + t.Fatalf("generate ml-dsa key: %v", err) + } + + issued := func(cn string, spec certSpec) *x509.Certificate { + spec.cn, spec.parent, spec.parentKey = cn, ca, caKey + cert, _ := makeCert(t, valid(spec)) + return cert + } + + classicalLeaf := issued("classical.test", certSpec{key: ecdsaKey(t)}) + weakLeaf := issued("weak.test", certSpec{key: rsaKey(t, 1024)}) + pqLeaf, _ := makeCert(t, valid(certSpec{cn: "pq.test", key: pqLeafKey, parent: pqCA, parentKey: pqKey})) + // A post-quantum key certified by a classical CA: the signature is the + // weak link, so the chain is classical. + mixedLeaf := issued("mixed.test", certSpec{key: pqLeafKey}) + + tests := []struct { + name string + chain []*x509.Certificate + want string + }{ + {"classical leaf and ca", []*x509.Certificate{classicalLeaf, ca}, AlgorithmsClassical}, + {"1024-bit rsa leaf", []*x509.Certificate{weakLeaf, ca}, AlgorithmsWeak}, + {"post-quantum leaf and ca", []*x509.Certificate{pqLeaf, pqCA}, AlgorithmsPostQuantum}, + {"post-quantum key, classical signature", []*x509.Certificate{mixedLeaf, ca}, AlgorithmsClassical}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + info := describeChain(tt.chain, "host.test", x509.NewCertPool(), ev) + if info.AlgorithmVerdict != tt.want { + t.Errorf("AlgorithmVerdict = %q, want %q (chain %+v)", info.AlgorithmVerdict, tt.want, info.Chain) + } + if len(info.Chain) != len(tt.chain) { + t.Errorf("got %d chain entries, want %d", len(info.Chain), len(tt.chain)) + } + }) + } +} + +// A certificate's own signature is left out of the algorithm verdict only when +// it really is self-signed. Matching names are not enough. +func TestDescribeChain_SelfSignedIsDecidedBySignatureNotName(t *testing.T) { + valid := func(spec certSpec) certSpec { + spec.notBefore, spec.notAfter = testNow.AddDate(0, 0, -1), testNow.AddDate(0, 0, 30) + return spec + } + ev := Evidence{ProbedAt: testNow} + mldsaKey := func() *mldsa.PrivateKey { + key, err := mldsa.GenerateKey(mldsa.MLDSA65()) + if err != nil { + t.Fatalf("generate ml-dsa key: %v", err) + } + return key + } + + t.Run("ca rolled over to a new key under the same name", func(t *testing.T) { + // The old classical key certifies the CA's new post-quantum key. + // Subject and issuer are the same name, but this is an ordinary link + // whose classical signature makes the chain classical. + oldKey := ecdsaKey(t) + oldCA, _ := makeCert(t, valid(certSpec{cn: "Rollover CA", key: oldKey, isCA: true})) + newKey := mldsaKey() + rollover, _ := makeCert(t, valid(certSpec{cn: "Rollover CA", key: newKey, isCA: true, parent: oldCA, parentKey: oldKey})) + leaf, _ := makeCert(t, valid(certSpec{cn: "leaf.test", key: mldsaKey(), parent: rollover, parentKey: newKey})) + + info := describeChain([]*x509.Certificate{leaf, rollover}, "leaf.test", x509.NewCertPool(), ev) + if info.Chain[1].SelfSigned { + t.Error("a certificate signed by a different key was reported as self-signed") + } + if info.AlgorithmVerdict != AlgorithmsClassical { + t.Errorf("AlgorithmVerdict = %q, want %q: the rollover certificate's signature is classical", info.AlgorithmVerdict, AlgorithmsClassical) + } + }) + + t.Run("old root signed with sha-1", func(t *testing.T) { + // Still exempt: a trust anchor is trusted by being installed, not by + // its signature, so a SHA-1 root must not make the chain weak. + rootKey := rsaKey(t, 2048) + root, _ := makeCert(t, valid(certSpec{cn: "Old Root", key: rootKey, isCA: true, sigAlg: x509.SHA1WithRSA})) + leaf, _ := makeCert(t, valid(certSpec{cn: "leaf.test", key: ecdsaKey(t), parent: root, parentKey: rootKey})) + + info := describeChain([]*x509.Certificate{leaf, root}, "leaf.test", x509.NewCertPool(), ev) + if !info.Chain[1].SelfSigned { + t.Error("a self-signed SHA-1 root was not reported as self-signed") + } + if info.AlgorithmVerdict != AlgorithmsClassical { + t.Errorf("AlgorithmVerdict = %q, want %q: a root's own SHA-1 signature is not a weakness", info.AlgorithmVerdict, AlgorithmsClassical) + } + }) +} + +func TestSignatureStrength(t *testing.T) { + tests := []struct { + alg x509.SignatureAlgorithm + want algorithmStrength + }{ + {x509.SHA1WithRSA, strengthWeak}, + {x509.MD5WithRSA, strengthWeak}, + {x509.ECDSAWithSHA1, strengthWeak}, + {x509.SHA256WithRSA, strengthClassical}, + {x509.ECDSAWithSHA384, strengthClassical}, + {x509.PureEd25519, strengthClassical}, + {x509.MLDSA65, strengthPostQuantum}, + {x509.UnknownSignatureAlgorithm, strengthUnknown}, + } + for _, tt := range tests { + t.Run(tt.alg.String(), func(t *testing.T) { + if got := signatureStrength(tt.alg); got != tt.want { + t.Errorf("signatureStrength(%s) = %v, want %v", tt.alg, got, tt.want) + } + }) + } +} + +func TestDescribeChain_Expiry(t *testing.T) { + tests := []struct { + name string + notBefore time.Time + notAfter time.Time + wantDays int + wantValid int + want string + }{ + {"valid", testNow.AddDate(0, 0, -17), testNow.AddDate(0, 0, 30), 30, 47, ExpiryValid}, + {"expires within the day", testNow.AddDate(0, 0, -89), testNow.Add(6 * time.Hour), 0, 89, ExpiryValid}, + {"expired", testNow.AddDate(0, 0, -100), testNow.Add(-36 * time.Hour), -2, 99, ExpiryExpired}, + {"not yet valid", testNow.AddDate(0, 0, 2), testNow.AddDate(0, 0, 92), 92, 90, ExpiryNotYetValid}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + cert, _ := makeCert(t, certSpec{cn: "expiry.test", key: ecdsaKey(t), notBefore: tt.notBefore, notAfter: tt.notAfter}) + + info := describeChain([]*x509.Certificate{cert}, "expiry.test", x509.NewCertPool(), Evidence{ProbedAt: testNow}) + if info.ExpiryVerdict != tt.want { + t.Errorf("ExpiryVerdict = %q, want %q", info.ExpiryVerdict, tt.want) + } + if info.DaysUntilExpiry != tt.wantDays { + t.Errorf("DaysUntilExpiry = %d, want %d", info.DaysUntilExpiry, tt.wantDays) + } + if info.ValidityDays != tt.wantValid { + t.Errorf("ValidityDays = %d, want %d", info.ValidityDays, tt.wantValid) + } + }) + } +} + +// The trust verdict answers one question: does the chain the server sent lead +// to a root in the trust store. The cases that matter are the ones where it +// could be confused with another verdict or with a browser's leniency. +func TestDescribeChain_TrustVerdict(t *testing.T) { + yearEitherSide := func(spec certSpec) certSpec { + spec.notBefore, spec.notAfter = testNow.AddDate(-1, 0, 0), testNow.AddDate(1, 0, 0) + return spec + } + + rootKey := ecdsaKey(t) + root, _ := makeCert(t, yearEitherSide(certSpec{cn: "Test Root", key: rootKey, isCA: true})) + interKey := ecdsaKey(t) + inter, _ := makeCert(t, yearEitherSide(certSpec{cn: "Test Intermediate", key: interKey, isCA: true, parent: root, parentKey: rootKey})) + + leaf := func(notBefore, notAfter time.Time) *x509.Certificate { + cert, _ := makeCert(t, certSpec{ + cn: "trust.test", key: ecdsaKey(t), dnsNames: []string{"trust.test"}, + notBefore: notBefore, notAfter: notAfter, + parent: inter, parentKey: interKey, + }) + return cert + } + current := leaf(testNow.AddDate(0, 0, -10), testNow.AddDate(0, 0, 80)) + expired := leaf(testNow.AddDate(0, 0, -100), testNow.AddDate(0, 0, -10)) + notYetValid := leaf(testNow.AddDate(0, 0, 5), testNow.AddDate(0, 0, 95)) + selfSigned, _ := makeCert(t, certSpec{ + cn: "trust.test", key: ecdsaKey(t), dnsNames: []string{"trust.test"}, + notBefore: testNow.AddDate(0, 0, -10), notAfter: testNow.AddDate(0, 0, 80), + }) + + trusted := x509.NewCertPool() + trusted.AddCert(root) + + tests := []struct { + name string + chain []*x509.Certificate + roots *x509.CertPool + want string + wantExpiry string + }{ + {"chains to a trusted root", []*x509.Certificate{current, inter}, trusted, TrustTrusted, ExpiryValid}, + {"root sent along with the chain", []*x509.Certificate{current, inter, root}, trusted, TrustTrusted, ExpiryValid}, + {"root not in the trust store", []*x509.Certificate{current, inter, root}, x509.NewCertPool(), TrustUntrusted, ExpiryValid}, + // Nothing is fetched to repair a chain, so a missing intermediate is + // untrusted even though the root is known. + {"intermediate left out", []*x509.Certificate{current}, trusted, TrustUntrusted, ExpiryValid}, + {"self-signed", []*x509.Certificate{selfSigned}, trusted, TrustUntrusted, ExpiryValid}, + // Expiry has its own verdict. A lapsed certificate from a trusted CA + // must stay distinguishable from one no public CA ever issued. + {"expired but from a trusted root", []*x509.Certificate{expired, inter}, trusted, TrustTrusted, ExpiryExpired}, + {"not yet valid but from a trusted root", []*x509.Certificate{notYetValid, inter}, trusted, TrustTrusted, ExpiryNotYetValid}, + {"expired and from an unknown root", []*x509.Certificate{expired, inter}, x509.NewCertPool(), TrustUntrusted, ExpiryExpired}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + info := describeChain(tt.chain, "trust.test", tt.roots, Evidence{ProbedAt: testNow}) + if info.TrustVerdict != tt.want { + t.Errorf("TrustVerdict = %q, want %q", info.TrustVerdict, tt.want) + } + if info.ExpiryVerdict != tt.wantExpiry { + t.Errorf("ExpiryVerdict = %q, want %q", info.ExpiryVerdict, tt.wantExpiry) + } + }) + } +} + +func TestDescribeChain_HostnameVerdict(t *testing.T) { + withSANs, _ := makeCert(t, certSpec{ + cn: "example.test", key: ecdsaKey(t), dnsNames: []string{"example.test", "*.wild.test"}, + notBefore: testNow.AddDate(0, 0, -1), notAfter: testNow.AddDate(0, 0, 30), + }) + commonNameOnly, _ := makeCert(t, certSpec{ + cn: "example.test", key: ecdsaKey(t), + notBefore: testNow.AddDate(0, 0, -1), notAfter: testNow.AddDate(0, 0, 30), + }) + + tests := []struct { + name string + cert *x509.Certificate + host string + want string + }{ + {"exact name", withSANs, "example.test", HostnameMatch}, + {"another name", withSANs, "other.test", HostnameMismatch}, + {"wildcard covers one label", withSANs, "a.wild.test", HostnameMatch}, + {"wildcard does not cover two labels", withSANs, "a.b.wild.test", HostnameMismatch}, + {"wildcard does not cover the bare name", withSANs, "wild.test", HostnameMismatch}, + // Clients stopped reading the common name years ago; a certificate + // that only names the host there does not cover it. + {"common name without a san", commonNameOnly, "example.test", HostnameMismatch}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + info := describeChain([]*x509.Certificate{tt.cert}, tt.host, x509.NewCertPool(), Evidence{ProbedAt: testNow}) + if info.HostnameVerdict != tt.want { + t.Errorf("HostnameVerdict = %q, want %q", info.HostnameVerdict, tt.want) + } + }) + } +} diff --git a/internal/domain/encryption_key_exchange.go b/internal/domain/encryption_key_exchange.go new file mode 100644 index 0000000..ecd3596 --- /dev/null +++ b/internal/domain/encryption_key_exchange.go @@ -0,0 +1,103 @@ +package domain + +import ( + "context" + "crypto/tls" + "fmt" +) + +// probedGroups are the key exchange groups a lookup offers, post-quantum +// first. Names are the IANA "TLS Supported Groups" names, which is what other +// tools and server configurations call them. The list is every group the +// standard library implements; a group it cannot speak cannot be probed. +var probedGroups = []struct { + id tls.CurveID + name string + postQuantum bool +}{ + {tls.X25519MLKEM768, "X25519MLKEM768", true}, + {tls.SecP256r1MLKEM768, "SecP256r1MLKEM768", true}, + {tls.SecP384r1MLKEM1024, "SecP384r1MLKEM1024", true}, + {tls.MLKEM1024, "MLKEM1024", true}, + {tls.X25519, "x25519", false}, + {tls.CurveP256, "secp256r1", false}, + {tls.CurveP384, "secp384r1", false}, + {tls.CurveP521, "secp521r1", false}, +} + +// LookupKeyExchange reports which key exchange groups host accepts on port +// 443, and whether any of them is post-quantum. +func LookupKeyExchange(ctx context.Context, host string) (*KeyExchangeInfo, error) { + s, err := newSession(ctx, host) + if err != nil { + return nil, err + } + return probeKeyExchange(ctx, s) +} + +// probeKeyExchange offers each group on its own, then all of them together to +// see which one the server picks. +// +// The cipher suites are left at the standard library's defaults, which are all +// ECDHE. Offering RSA key exchange here would let a TLS 1.2 server complete the +// handshake without using the group at all. The negotiated group is checked +// against the one offered for the same reason. +// +// A server with no forward-secret key exchange left accepts none of these and +// reports ErrNoHandshake. That is rare enough to leave as a failed lookup. +func probeKeyExchange(ctx context.Context, s *session) (*KeyExchangeInfo, error) { + info := &KeyExchangeInfo{Evidence: s.evidence(), Verdict: KeyExchangeClassical} + anyAccepted := false + + for _, g := range probedGroups { + state, accepted, err := s.offer(ctx, &tls.Config{ + MinVersion: tls.VersionTLS12, + CurvePreferences: []tls.CurveID{g.id}, + }) + if err != nil { + return nil, fmt.Errorf("%s: %w", g.name, err) + } + accepted = accepted && state.CurveID == g.id + + info.Groups = append(info.Groups, KeyExchangeGroup{ + Name: g.name, + Accepted: accepted, + PostQuantum: g.postQuantum, + }) + if accepted { + anyAccepted = true + if g.postQuantum { + info.Verdict = KeyExchangePostQuantum + } + } + } + + if !anyAccepted { + return nil, ErrNoHandshake + } + + // A refusal here is left as an empty Negotiated rather than failing the + // lookup: the per-group answers above are already complete. + state, accepted, err := s.offer(ctx, &tls.Config{ + MinVersion: tls.VersionTLS12, + CurvePreferences: everyGroup(), + }) + if err != nil { + return nil, fmt.Errorf("combined offer: %w", err) + } + if accepted { + info.Negotiated = groupName(state.CurveID) + } + + return info, nil +} + +// groupName returns the IANA name for a probed group, or "" for anything else. +func groupName(id tls.CurveID) string { + for _, g := range probedGroups { + if g.id == id { + return g.name + } + } + return "" +} diff --git a/internal/domain/encryption_model.go b/internal/domain/encryption_model.go new file mode 100644 index 0000000..6989ca2 --- /dev/null +++ b/internal/domain/encryption_model.go @@ -0,0 +1,188 @@ +package domain + +import "time" + +// --- Encryption Posture Request/Response --- + +// Canonical lookup names accepted in EncryptionRequest.Lookups. These names are +// the contract shared by the request body, the per-lookup cache keys, the +// per-lookup TTL config, and usage tracking. +const ( + LookupProtocolsName = "protocols" + LookupKeyExchangeName = "key_exchange" + LookupCertificateName = "certificate" +) + +// AllEncryptionLookupNames lists every valid encryption lookup name. +var AllEncryptionLookupNames = []string{ + LookupProtocolsName, + LookupKeyExchangeName, + LookupCertificateName, +} + +type EncryptionRequest struct { + Hosts []string `json:"hosts" binding:"required,min=1"` + Lookups []string `json:"lookups"` +} + +// EncryptionLookupOptions carries the normalized, deduplicated, validated set +// of lookups to run. Built in exactly one place (the handler); everything +// downstream sees only explicit lookup names. +type EncryptionLookupOptions struct { + Lookups []string +} + +// Has reports whether the named lookup was requested. +func (o EncryptionLookupOptions) Has(name string) bool { + return sliceContains(o.Lookups, name) +} + +type EncryptionResponse struct { + Host string `json:"host"` + Inputs []string `json:"inputs,omitempty"` + + Protocols *ProtocolsResult `json:"protocols,omitempty"` + KeyExchange *KeyExchangeResult `json:"key_exchange,omitempty"` + Certificate *CertificateResult `json:"certificate,omitempty"` + + Errors []LookupError `json:"errors,omitempty"` +} + +// EncryptionResponseEnvelope wraps the per-host results, matching the domain +// and IP endpoints so every API response is a JSON object. +type EncryptionResponseEnvelope struct { + Results []*EncryptionResponse `json:"results"` +} + +// --- Per-lookup response wrappers --- +// +// Each wrapper embeds the pure lookup payload and adds a cache_hit flag. Only +// the embedded payload is ever marshaled into Redis. + +type ProtocolsResult struct { + CacheHit bool `json:"cache_hit"` + *ProtocolsInfo +} + +type KeyExchangeResult struct { + CacheHit bool `json:"cache_hit"` + *KeyExchangeInfo +} + +type CertificateResult struct { + CacheHit bool `json:"cache_hit"` + *CertificateInfo +} + +// Evidence says where and when a result was observed. Every encryption payload +// embeds it, because a cached answer is an older observation and a host with +// several addresses can be configured differently on each. +type Evidence struct { + IP string `json:"ip"` + ProbedAt time.Time `json:"probed_at"` +} + +// --- Protocols --- + +type ProtocolsInfo struct { + Evidence + Versions []ProtocolVersion `json:"versions"` + // LegacyAccepted is true when the server accepts TLS 1.0 or TLS 1.1, both + // deprecated by RFC 8996. + LegacyAccepted bool `json:"legacy_accepted"` +} + +type ProtocolVersion struct { + Name string `json:"name"` + Accepted bool `json:"accepted"` +} + +// --- Key exchange --- + +// Key exchange verdicts. Post-quantum here means the host accepts at least one +// post-quantum group, so a client that negotiates it gets session keys safe +// from an attacker who records traffic now and decrypts it later. It is a +// statement of support, not about every connection, and it says nothing about +// the certificate, which has its own verdict. +const ( + KeyExchangePostQuantum = "post_quantum" + KeyExchangeClassical = "classical" +) + +type KeyExchangeInfo struct { + Evidence + Groups []KeyExchangeGroup `json:"groups"` + // Negotiated is the group the server chose when offered every group at + // once, post-quantum first. Empty when that combined offer was refused. + Negotiated string `json:"negotiated,omitempty"` + Verdict string `json:"verdict"` +} + +type KeyExchangeGroup struct { + Name string `json:"name"` + Accepted bool `json:"accepted"` + PostQuantum bool `json:"post_quantum"` +} + +// --- Certificate --- + +// Certificate algorithm verdicts, strongest claim last. A chain is only as +// good as its weakest certificate, so one weak link makes the chain weak and +// one classical link makes it classical. +const ( + AlgorithmsWeak = "weak" + AlgorithmsUnknown = "unknown" + AlgorithmsClassical = "classical" + AlgorithmsPostQuantum = "post_quantum" +) + +// Certificate expiry verdicts. There is deliberately no "expiring soon": what +// counts as soon depends on the certificate's lifetime and the caller's +// renewal process, so the response gives days_until_expiry and validity_days +// and leaves the threshold to the caller. +const ( + ExpiryValid = "valid" + ExpiryExpired = "expired" + ExpiryNotYetValid = "not_yet_valid" +) + +// Certificate trust verdicts: whether the chain the server sent leads to a +// root in the public trust store. Judged apart from the leaf's validity dates, +// which expiry_verdict already reports, so an expired certificate from a +// public CA reads "expired" and "trusted" rather than failing twice. +const ( + TrustTrusted = "trusted" + TrustUntrusted = "untrusted" +) + +// Certificate hostname verdicts: whether the leaf covers the host that was +// asked about. +const ( + HostnameMatch = "match" + HostnameMismatch = "mismatch" +) + +type CertificateInfo struct { + Evidence + // Chain is what the server sent, leaf first. + Chain []ChainCertificate `json:"chain"` + // SANs, DaysUntilExpiry and ValidityDays describe the leaf. + SANs []string `json:"sans,omitempty"` + DaysUntilExpiry int `json:"days_until_expiry"` + ValidityDays int `json:"validity_days"` + ExpiryVerdict string `json:"expiry_verdict"` + AlgorithmVerdict string `json:"algorithm_verdict"` + TrustVerdict string `json:"trust_verdict"` + HostnameVerdict string `json:"hostname_verdict"` +} + +type ChainCertificate struct { + Subject string `json:"subject"` + Issuer string `json:"issuer"` + NotBefore time.Time `json:"not_before"` + NotAfter time.Time `json:"not_after"` + KeyAlgorithm string `json:"key_algorithm"` + KeyBits int `json:"key_bits,omitempty"` + SignatureAlgorithm string `json:"signature_algorithm"` + SelfSigned bool `json:"self_signed"` +} diff --git a/internal/domain/encryption_probe.go b/internal/domain/encryption_probe.go new file mode 100644 index 0000000..c9c27ee --- /dev/null +++ b/internal/domain/encryption_probe.go @@ -0,0 +1,250 @@ +package domain + +import ( + "context" + "crypto/tls" + "crypto/x509" + "errors" + "fmt" + "net" + "net/netip" + "sync" + "time" + + "github.com/security-accelerated/intelligence-api/internal/safenet" +) + +// The TLS probe behind the encryption lookups (protocols, key_exchange, +// certificate). Each rule in this file is a way to return a wrong answer that +// would then be cached for hours; docs/decisions.md has the reasoning. + +// probePort is the only port an encryption lookup connects to. Taking a port +// from the caller would turn the endpoint into a general port prober, so that +// stays out until there is a decision to offer it. +const probePort = 443 + +// EncryptionProbeTimeout bounds a single handshake, TCP connect included. Set +// from encryption.probe_timeout at startup. +var EncryptionProbeTimeout = 5 * time.Second + +// ErrNoHandshake means every handshake a lookup tried was refused. That cannot +// be told apart from a host that is blocking us, so it is reported as a failed +// lookup rather than as "this host accepts nothing". +var ErrNoHandshake = errors.New("no TLS handshake succeeded on port 443") + +// session is one lookup's view of a host. A lookup makes several handshakes, +// and all of them go to the one address picked here: a host with several +// addresses can be configured differently on each, and mixing them would +// produce a result that is true of no single server. +type session struct { + host string + addr netip.AddrPort + // dial opens the TCP connection. Production uses safenet, which refuses + // private and reserved addresses; tests substitute a plain dialer to reach + // a loopback server. + dial func(ctx context.Context, network, address string) (net.Conn, error) + now func() time.Time + // roots returns the trust store the certificate lookup judges a chain + // against. Production uses the system roots; tests supply their own so the + // result does not depend on the machine running them. + roots func() (*x509.CertPool, error) +} + +// ErrTrustStoreUnavailable means the system root certificates could not be +// loaded, or loaded as an empty set. It is a fault in our environment, not a +// finding about a target, so IsExpectedError does not know it and it alerts. +var ErrTrustStoreUnavailable = errors.New("certificate trust store unavailable") + +// systemTrustStore loads the system roots once per process. +var systemTrustStore = sync.OnceValues(func() (*x509.CertPool, error) { + return checkTrustStore(x509.SystemCertPool()) +}) + +// checkTrustStore turns a missing or empty trust store into an error. +// +// The empty case is the one that matters. On Linux a container image with no +// CA bundle does not fail to load: the standard library hands back an empty +// pool and no error, and verifying against it reports every chain as signed by +// an unknown authority. Without this check every host would get trust_verdict +// "untrusted", cached for hours, and nothing would say why. +func checkTrustStore(pool *x509.CertPool, err error) (*x509.CertPool, error) { + if err != nil { + return nil, fmt.Errorf("load system roots (%v): %w", err, ErrTrustStoreUnavailable) + } + if pool == nil || pool.Equal(x509.NewCertPool()) { + return nil, fmt.Errorf("system roots are empty: %w", ErrTrustStoreUnavailable) + } + return pool, nil +} + +// newSession resolves host through the lookup resolver and pins one public +// address for the handshakes that follow. +func newSession(ctx context.Context, host string) (*session, error) { + addrs, err := Resolver().LookupNetIP(ctx, "ip", host) + if err != nil { + return nil, fmt.Errorf("resolve: %w", err) + } + addr, err := pickAddr(addrs) + if err != nil { + return nil, err + } + return &session{ + host: host, + addr: netip.AddrPortFrom(addr, probePort), + dial: safenet.SafeDialer(EncryptionProbeTimeout).DialContext, + now: time.Now, + roots: systemTrustStore, + }, nil +} + +// pickAddr chooses the address to probe: the first public IPv4 address, or +// failing that the first public IPv6 one. IPv4 first because not every +// environment this runs in has an IPv6 route, and a connect failure of our own +// making would be reported as the target's. +// +// A host whose addresses are all private or reserved yields a +// safenet.BlockedError, the same error the dialer would raise. The dialer +// still checks again at connect time; this only produces the clearer message +// earlier. +func pickAddr(addrs []netip.Addr) (netip.Addr, error) { + var firstV6 netip.Addr + var blocked netip.Addr + for _, a := range addrs { + a = a.Unmap() + if safenet.IsPrivateAddr(a) { + if !blocked.IsValid() { + blocked = a + } + continue + } + if a.Is4() { + return a, nil + } + if !firstV6.IsValid() { + firstV6 = a + } + } + if firstV6.IsValid() { + return firstV6, nil + } + if blocked.IsValid() { + return netip.Addr{}, &safenet.BlockedError{IP: blocked} + } + return netip.Addr{}, errors.New("host has no addresses") +} + +// evidence records where and when this session observed the host. +func (s *session) evidence() Evidence { + return Evidence{IP: s.addr.Addr().String(), ProbedAt: s.now().UTC()} +} + +// rejectedError marks a handshake the server answered and refused: an alert, a +// reset, a closed connection, or parameters this client would not accept. It +// is an answer about the offer, not a failure of the lookup. +type rejectedError struct{ cause error } + +func (e *rejectedError) Error() string { return "handshake rejected: " + e.cause.Error() } +func (e *rejectedError) Unwrap() error { return e.cause } + +// handshake makes one TLS handshake with cfg and returns the negotiated state. +// It sets ServerName and InsecureSkipVerify on cfg, so pass a fresh one. +// +// There are three outcomes, and keeping them apart is what makes a result +// trustworthy: +// +// - success: the server accepted what cfg offered. +// - *rejectedError: the TCP connection opened and the handshake then failed. +// The server does not accept this offer. +// - any other error: the connection never opened, or the handshake timed +// out. Nothing was learned, so the caller must fail the lookup rather than +// record a refusal. A failed lookup is retried; a wrong "not accepted" +// would be cached. +// +// A timeout counts as "nothing learned" even though some middleboxes silently +// drop offers they dislike. Treating silence as refusal would let one lost +// packet be cached as a finding. +func (s *session) handshake(ctx context.Context, cfg *tls.Config) (*tls.ConnectionState, error) { + ctx, cancel := context.WithTimeout(ctx, EncryptionProbeTimeout) + defer cancel() + + conn, err := s.dial(ctx, "tcp", s.addr.String()) + if err != nil { + return nil, fmt.Errorf("connect: %w", err) + } + defer conn.Close() + + cfg.ServerName = s.host + // InsecureSkipVerify is intentional, as in LookupSSL: the point is to + // report what the server presents, including expired, self-signed and + // mismatched certificates. Verifying during the handshake would turn the + // answer the caller asked for into a handshake error. The certificate + // lookup judges the chain afterwards and reports the outcome as data. This + // connection carries no credentials and reads no data; it exists only to + // see what the target negotiates. + cfg.InsecureSkipVerify = true + + client := tls.Client(conn, cfg) + if err := client.HandshakeContext(ctx); err != nil { + if timedOut(ctx, err) { + return nil, fmt.Errorf("handshake: %w", err) + } + return nil, &rejectedError{cause: err} + } + state := client.ConnectionState() + return &state, nil +} + +// offer makes one handshake and reports whether the server accepted it. A +// non-nil error means the question could not be answered. +func (s *session) offer(ctx context.Context, cfg *tls.Config) (*tls.ConnectionState, bool, error) { + state, err := s.handshake(ctx, cfg) + var rejected *rejectedError + switch { + case err == nil: + return state, true, nil + case errors.As(err, &rejected): + return nil, false, nil + default: + return nil, false, err + } +} + +// timedOut reports whether a handshake failed because time ran out rather +// than because the server answered. +func timedOut(ctx context.Context, err error) bool { + if ctx.Err() != nil || errors.Is(err, context.DeadlineExceeded) { + return true + } + var netErr net.Error + return errors.As(err, &netErr) && netErr.Timeout() +} + +// everyCipherSuite lists every TLS 1.0–1.2 cipher suite the standard library +// implements, including the ones it marks insecure. Probes that ask "does the +// server speak this at all" offer the lot: a server that only has RSA key +// exchange or CBC suites left still accepts TLS, and leaving those out would +// report it as refusing. +func everyCipherSuite() []uint16 { + secure, insecure := tls.CipherSuites(), tls.InsecureCipherSuites() + ids := make([]uint16, 0, len(secure)+len(insecure)) + for _, suite := range secure { + ids = append(ids, suite.ID) + } + for _, suite := range insecure { + ids = append(ids, suite.ID) + } + return ids +} + +// everyGroup lists every key exchange group the probe can speak, post-quantum +// first. The standard library's default offer leaves some of them out (pure +// ML-KEM, for one), so a probe that leaves CurvePreferences empty cannot +// complete a handshake with a server that insists on one of those, and would +// report it as refusing TLS altogether. +func everyGroup() []tls.CurveID { + ids := make([]tls.CurveID, 0, len(probedGroups)) + for _, g := range probedGroups { + ids = append(ids, g.id) + } + return ids +} diff --git a/internal/domain/encryption_probe_test.go b/internal/domain/encryption_probe_test.go new file mode 100644 index 0000000..f676167 --- /dev/null +++ b/internal/domain/encryption_probe_test.go @@ -0,0 +1,528 @@ +package domain + +import ( + "context" + "crypto" + "crypto/ecdsa" + "crypto/elliptic" + "crypto/rand" + "crypto/tls" + "crypto/x509" + "crypto/x509/pkix" + "errors" + "io" + "math/big" + "net" + "net/netip" + "testing" + "time" + + "github.com/security-accelerated/intelligence-api/internal/safenet" +) + +// testNow is the clock every test session reports, so expiry arithmetic is +// deterministic. +var testNow = time.Date(2026, 11, 9, 12, 0, 0, 0, time.UTC) + +// certSpec describes a certificate to build in memory. A nil parent makes it +// self-signed. +type certSpec struct { + cn string + key crypto.Signer + notBefore time.Time + notAfter time.Time + dnsNames []string + isCA bool + parent *x509.Certificate + parentKey crypto.Signer + // sigAlg overrides the signature algorithm; zero picks the default for + // the signing key. + sigAlg x509.SignatureAlgorithm +} + +func makeCert(t *testing.T, spec certSpec) (cert *x509.Certificate, der []byte) { + t.Helper() + tmpl := &x509.Certificate{ + SerialNumber: big.NewInt(time.Now().UnixNano()), + Subject: pkix.Name{CommonName: spec.cn}, + NotBefore: spec.notBefore, + NotAfter: spec.notAfter, + DNSNames: spec.dnsNames, + IsCA: spec.isCA, + BasicConstraintsValid: true, + KeyUsage: x509.KeyUsageDigitalSignature | x509.KeyUsageCertSign, + SignatureAlgorithm: spec.sigAlg, + } + parent, signer := tmpl, spec.key + if spec.parent != nil { + parent, signer = spec.parent, spec.parentKey + } + der, err := x509.CreateCertificate(rand.Reader, tmpl, parent, spec.key.Public(), signer) + if err != nil { + t.Fatalf("create certificate %q: %v", spec.cn, err) + } + cert, err = x509.ParseCertificate(der) + if err != nil { + t.Fatalf("parse certificate %q: %v", spec.cn, err) + } + return cert, der +} + +func ecdsaKey(t *testing.T) *ecdsa.PrivateKey { + t.Helper() + key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + if err != nil { + t.Fatalf("generate key: %v", err) + } + return key +} + +// serverCertificate is a self-signed ECDSA certificate valid for 90 days, +// with 80 of them left at testNow. +func serverCertificate(t *testing.T) tls.Certificate { + t.Helper() + key := ecdsaKey(t) + _, der := makeCert(t, certSpec{ + cn: "probe.test", + key: key, + notBefore: testNow.AddDate(0, 0, -10), + notAfter: testNow.AddDate(0, 0, 80), + dnsNames: []string{"probe.test", "www.probe.test"}, + }) + return tls.Certificate{Certificate: [][]byte{der}, PrivateKey: key} +} + +// loopbackSession points a session at a listener on loopback, which the +// production dialer refuses by design. Its trust store is empty, so a trust +// verdict here never depends on the roots installed on the machine. +func loopbackSession(t *testing.T, ln net.Listener) *session { + t.Helper() + return &session{ + host: "probe.test", + addr: ln.Addr().(*net.TCPAddr).AddrPort(), + dial: (&net.Dialer{}).DialContext, + now: func() time.Time { return testNow }, + roots: func() (*x509.CertPool, error) { return x509.NewCertPool(), nil }, + } +} + +// startTLSServer runs a TLS server on loopback that completes each handshake +// and then waits for the client to hang up. +func startTLSServer(t *testing.T, cfg *tls.Config) *session { + t.Helper() + if len(cfg.Certificates) == 0 { + cfg.Certificates = []tls.Certificate{serverCertificate(t)} + } + ln, err := tls.Listen("tcp", "127.0.0.1:0", cfg) + if err != nil { + t.Fatalf("listen: %v", err) + } + t.Cleanup(func() { _ = ln.Close() }) + + go func() { + for { + conn, err := ln.Accept() + if err != nil { + return + } + go func() { + defer conn.Close() + _, _ = io.Copy(io.Discard, conn) + }() + } + }() + return loopbackSession(t, ln) +} + +// startTCPServer runs a plain TCP server on loopback and hands each accepted +// connection to handle. +func startTCPServer(t *testing.T, handle func(net.Conn)) *session { + t.Helper() + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatalf("listen: %v", err) + } + t.Cleanup(func() { _ = ln.Close() }) + + go func() { + for { + conn, err := ln.Accept() + if err != nil { + return + } + go handle(conn) + } + }() + return loopbackSession(t, ln) +} + +func setProbeTimeout(t *testing.T, d time.Duration) { + t.Helper() + prev := EncryptionProbeTimeout + EncryptionProbeTimeout = d + t.Cleanup(func() { EncryptionProbeTimeout = prev }) +} + +func TestPickAddr(t *testing.T) { + addr := netip.MustParseAddr + tests := []struct { + name string + addrs []netip.Addr + want netip.Addr + blocked bool + wantErr bool + }{ + {name: "prefers ipv4 over an earlier ipv6", addrs: []netip.Addr{addr("2606:4700::1"), addr("93.184.216.34")}, want: addr("93.184.216.34")}, + {name: "ipv6 when there is no ipv4", addrs: []netip.Addr{addr("2606:4700::1")}, want: addr("2606:4700::1")}, + {name: "skips a private address", addrs: []netip.Addr{addr("10.0.0.5"), addr("93.184.216.34")}, want: addr("93.184.216.34")}, + {name: "unmaps ipv4-mapped ipv6", addrs: []netip.Addr{addr("::ffff:93.184.216.34")}, want: addr("93.184.216.34")}, + {name: "all private is blocked", addrs: []netip.Addr{addr("127.0.0.1"), addr("192.168.1.1")}, blocked: true, wantErr: true}, + {name: "mapped private is blocked", addrs: []netip.Addr{addr("::ffff:10.0.0.1")}, blocked: true, wantErr: true}, + {name: "no addresses", wantErr: true}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got, err := pickAddr(tt.addrs) + if (err != nil) != tt.wantErr { + t.Fatalf("pickAddr() error = %v, wantErr %v", err, tt.wantErr) + } + var blocked *safenet.BlockedError + if errors.As(err, &blocked) != tt.blocked { + t.Errorf("pickAddr() error = %v, want BlockedError = %v", err, tt.blocked) + } + if got != tt.want { + t.Errorf("pickAddr() = %v, want %v", got, tt.want) + } + }) + } +} + +// newSession is the only place a hostname from a caller becomes an address to +// connect to, so its three answers are worth pinning down against a real +// resolver: a public address is pinned on 443, a private one is refused, and +// a name that does not exist is an error. +func TestNewSession(t *testing.T) { + t.Run("pins a public address on port 443", func(t *testing.T) { + server, _ := startDNSServer(t, testZone{A: []string{"10.0.0.7", "93.184.216.34"}}) + useLocalResolver(t, server) + + s, err := newSession(context.Background(), "probe.test") + if err != nil { + t.Fatalf("newSession() error = %v", err) + } + if want := netip.MustParseAddrPort("93.184.216.34:443"); s.addr != want { + t.Errorf("addr = %v, want %v", s.addr, want) + } + if s.host != "probe.test" { + t.Errorf("host = %q, want probe.test", s.host) + } + }) + + t.Run("refuses a host with only private addresses", func(t *testing.T) { + server, _ := startDNSServer(t, testZone{A: []string{"127.0.0.1"}}) + useLocalResolver(t, server) + + _, err := newSession(context.Background(), "internal.test") + var blocked *safenet.BlockedError + if !errors.As(err, &blocked) { + t.Errorf("newSession() error = %v, want a BlockedError", err) + } + }) + + t.Run("fails for a name that does not exist", func(t *testing.T) { + server, _ := startDNSServer(t, testZone{NXDOMAIN: true}) + useLocalResolver(t, server) + + _, err := newSession(context.Background(), "nope.test") + if err == nil { + t.Fatal("newSession() error = nil, want a resolution error") + } + // A name that does not resolve is a finding about the target, so it + // must not count toward alerting. + if !IsExpectedError(err) { + t.Errorf("IsExpectedError(%v) = false, want true", err) + } + }) +} + +func TestProbeProtocols(t *testing.T) { + tests := []struct { + name string + min, max uint16 + curves []tls.CurveID + want map[string]bool + wantLegacy bool + }{ + { + name: "modern server", + min: tls.VersionTLS12, max: tls.VersionTLS13, + want: map[string]bool{"TLS 1.3": true, "TLS 1.2": true, "TLS 1.1": false, "TLS 1.0": false}, + }, + { + name: "tls 1.3 only", + min: tls.VersionTLS13, max: tls.VersionTLS13, + want: map[string]bool{"TLS 1.3": true, "TLS 1.2": false, "TLS 1.1": false, "TLS 1.0": false}, + }, + { + name: "legacy server without tls 1.3", + min: tls.VersionTLS10, max: tls.VersionTLS12, + want: map[string]bool{"TLS 1.3": false, "TLS 1.2": true, "TLS 1.1": true, "TLS 1.0": true}, + wantLegacy: true, + }, + { + // A group the standard library does not offer by default. The probe + // asks about the version, so it has to offer every group it can + // speak or this server reads as refusing TLS 1.3. + name: "tls 1.3 server that only takes pure ml-kem", + min: tls.VersionTLS13, max: tls.VersionTLS13, + curves: []tls.CurveID{tls.MLKEM1024}, + want: map[string]bool{"TLS 1.3": true, "TLS 1.2": false, "TLS 1.1": false, "TLS 1.0": false}, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + s := startTLSServer(t, &tls.Config{MinVersion: tt.min, MaxVersion: tt.max, CurvePreferences: tt.curves}) + + info, err := probeProtocols(context.Background(), s) + if err != nil { + t.Fatalf("probeProtocols() error = %v", err) + } + if len(info.Versions) != len(tt.want) { + t.Fatalf("got %d versions, want %d", len(info.Versions), len(tt.want)) + } + for _, v := range info.Versions { + if v.Accepted != tt.want[v.Name] { + t.Errorf("%s accepted = %v, want %v", v.Name, v.Accepted, tt.want[v.Name]) + } + } + if info.LegacyAccepted != tt.wantLegacy { + t.Errorf("LegacyAccepted = %v, want %v", info.LegacyAccepted, tt.wantLegacy) + } + if info.IP != "127.0.0.1" || !info.ProbedAt.Equal(testNow) { + t.Errorf("evidence = %s at %s, want 127.0.0.1 at %s", info.IP, info.ProbedAt, testNow) + } + }) + } +} + +// The three ways a probe can fail to get a TLS answer must stay distinct: +// only a server that answered and refused may be reported as ErrNoHandshake, +// and none of them may come back as a result. Each is a finding about the +// target, so none of them may count toward alerting either. +func TestProbeFailureModes(t *testing.T) { + t.Run("server hangs up on every handshake", func(t *testing.T) { + s := startTCPServer(t, func(c net.Conn) { _ = c.Close() }) + + if _, err := probeProtocols(context.Background(), s); !errors.Is(err, ErrNoHandshake) { + t.Errorf("probeProtocols() error = %v, want ErrNoHandshake", err) + } + if _, err := probeKeyExchange(context.Background(), s); !errors.Is(err, ErrNoHandshake) { + t.Errorf("probeKeyExchange() error = %v, want ErrNoHandshake", err) + } + if _, err := probeCertificate(context.Background(), s); !errors.Is(err, ErrNoHandshake) { + t.Errorf("probeCertificate() error = %v, want ErrNoHandshake", err) + } + }) + + t.Run("server accepts the connection and says nothing", func(t *testing.T) { + setProbeTimeout(t, 150*time.Millisecond) + s := startTCPServer(t, func(c net.Conn) { + defer c.Close() + _, _ = io.Copy(io.Discard, c) + }) + + _, err := probeProtocols(context.Background(), s) + if err == nil || errors.Is(err, ErrNoHandshake) { + t.Errorf("probeProtocols() error = %v, want a timeout that is not ErrNoHandshake", err) + } + if !IsExpectedError(err) { + t.Errorf("IsExpectedError(%v) = false, want true", err) + } + }) + + t.Run("nothing is listening", func(t *testing.T) { + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatalf("listen: %v", err) + } + s := loopbackSession(t, ln) + _ = ln.Close() + + _, err = probeProtocols(context.Background(), s) + if err == nil || errors.Is(err, ErrNoHandshake) { + t.Errorf("probeProtocols() error = %v, want a connect error that is not ErrNoHandshake", err) + } + if !IsExpectedError(err) { + t.Errorf("IsExpectedError(%v) = false, want true", err) + } + }) +} + +func TestProbeKeyExchange(t *testing.T) { + tests := []struct { + name string + cfg *tls.Config + wantAccepted []string + wantVerdict string + wantNegotiated string + }{ + { + name: "hybrid post-quantum and classical", + cfg: &tls.Config{MinVersion: tls.VersionTLS13, CurvePreferences: []tls.CurveID{tls.X25519MLKEM768, tls.X25519}}, + wantAccepted: []string{"X25519MLKEM768", "x25519"}, + wantVerdict: KeyExchangePostQuantum, + wantNegotiated: "X25519MLKEM768", + }, + { + name: "pure ml-kem only", + cfg: &tls.Config{MinVersion: tls.VersionTLS13, CurvePreferences: []tls.CurveID{tls.MLKEM1024}}, + wantAccepted: []string{"MLKEM1024"}, + wantVerdict: KeyExchangePostQuantum, + wantNegotiated: "MLKEM1024", + }, + { + name: "classical only", + cfg: &tls.Config{MinVersion: tls.VersionTLS13, CurvePreferences: []tls.CurveID{tls.CurveP384}}, + wantAccepted: []string{"secp384r1"}, + wantVerdict: KeyExchangeClassical, + wantNegotiated: "secp384r1", + }, + { + // Hybrids are TLS 1.3 only, so a TLS 1.2 server must come back + // classical even though it lists one. + name: "tls 1.2 server", + cfg: &tls.Config{MinVersion: tls.VersionTLS12, MaxVersion: tls.VersionTLS12, CurvePreferences: []tls.CurveID{tls.X25519MLKEM768, tls.CurveP256}}, + wantAccepted: []string{"secp256r1"}, + wantVerdict: KeyExchangeClassical, + wantNegotiated: "secp256r1", + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + s := startTLSServer(t, tt.cfg) + + info, err := probeKeyExchange(context.Background(), s) + if err != nil { + t.Fatalf("probeKeyExchange() error = %v", err) + } + if len(info.Groups) != len(probedGroups) { + t.Fatalf("got %d groups, want one per probed group (%d)", len(info.Groups), len(probedGroups)) + } + + want := make(map[string]bool, len(tt.wantAccepted)) + for _, name := range tt.wantAccepted { + want[name] = true + } + for _, g := range info.Groups { + if g.Accepted != want[g.Name] { + t.Errorf("%s accepted = %v, want %v", g.Name, g.Accepted, want[g.Name]) + } + } + if info.Verdict != tt.wantVerdict { + t.Errorf("Verdict = %q, want %q", info.Verdict, tt.wantVerdict) + } + if info.Negotiated != tt.wantNegotiated { + t.Errorf("Negotiated = %q, want %q", info.Negotiated, tt.wantNegotiated) + } + }) + } +} + +func TestProbeCertificate(t *testing.T) { + s := startTLSServer(t, &tls.Config{MinVersion: tls.VersionTLS12}) + + info, err := probeCertificate(context.Background(), s) + if err != nil { + t.Fatalf("probeCertificate() error = %v", err) + } + if len(info.Chain) != 1 { + t.Fatalf("got %d certificates, want 1", len(info.Chain)) + } + leaf := info.Chain[0] + if leaf.Subject != "probe.test" || leaf.KeyAlgorithm != "ECDSA" || leaf.KeyBits != 256 || !leaf.SelfSigned { + t.Errorf("leaf = %+v, want a self-signed 256-bit ECDSA certificate for probe.test", leaf) + } + if info.DaysUntilExpiry != 80 || info.ValidityDays != 90 { + t.Errorf("DaysUntilExpiry = %d, ValidityDays = %d, want 80 and 90", info.DaysUntilExpiry, info.ValidityDays) + } + if info.ExpiryVerdict != ExpiryValid || info.AlgorithmVerdict != AlgorithmsClassical { + t.Errorf("verdicts = %q / %q, want valid / classical", info.ExpiryVerdict, info.AlgorithmVerdict) + } + if len(info.SANs) != 2 { + t.Errorf("SANs = %v, want two names", info.SANs) + } + // A self-signed certificate nobody trusts is the answer, not an error: the + // lookup succeeded and says so in its verdicts. + if info.TrustVerdict != TrustUntrusted || info.HostnameVerdict != HostnameMatch { + t.Errorf("verdicts = %q / %q, want untrusted / match", info.TrustVerdict, info.HostnameVerdict) + } +} + +// A missing trust store is our fault, not a fact about the host. The lookup +// must fail, so nothing is cached, and the failure must alert. +func TestProbeCertificate_NoTrustStoreFailsTheLookup(t *testing.T) { + s := startTLSServer(t, &tls.Config{MinVersion: tls.VersionTLS12}) + s.roots = func() (*x509.CertPool, error) { return checkTrustStore(x509.NewCertPool(), nil) } + + info, err := probeCertificate(context.Background(), s) + if info != nil { + t.Errorf("probeCertificate() returned a result (trust_verdict %q) with no trust store to judge against", info.TrustVerdict) + } + if !errors.Is(err, ErrTrustStoreUnavailable) { + t.Fatalf("probeCertificate() error = %v, want ErrTrustStoreUnavailable", err) + } + if IsExpectedError(err) { + t.Error("a missing trust store was classified as expected; it would never alert") + } +} + +func TestCheckTrustStore(t *testing.T) { + loaded := x509.NewCertPool() + cert, _ := makeCert(t, certSpec{cn: "Some Root", key: ecdsaKey(t), isCA: true, notBefore: testNow.AddDate(0, 0, -1), notAfter: testNow.AddDate(1, 0, 0)}) + loaded.AddCert(cert) + + if pool, err := checkTrustStore(loaded, nil); err != nil || pool != loaded { + t.Errorf("checkTrustStore(loaded) = %v, %v; want the pool and no error", pool, err) + } + // What Linux hands back when the image has no CA bundle: no error, no + // certificates. + if _, err := checkTrustStore(x509.NewCertPool(), nil); !errors.Is(err, ErrTrustStoreUnavailable) { + t.Errorf("checkTrustStore(empty) error = %v, want ErrTrustStoreUnavailable", err) + } + if _, err := checkTrustStore(nil, errors.New("permission denied")); !errors.Is(err, ErrTrustStoreUnavailable) { + t.Errorf("checkTrustStore(load error) error = %v, want ErrTrustStoreUnavailable", err) + } + // The machine running the suite has roots, and so must production. + if _, err := systemTrustStore(); err != nil { + t.Errorf("systemTrustStore() error = %v on this machine", err) + } +} + +// The certificate probe has to reach a server whatever key exchange it insists +// on, including a group the standard library leaves out of its defaults. +func TestProbeCertificate_ServerWithNonDefaultGroup(t *testing.T) { + s := startTLSServer(t, &tls.Config{MinVersion: tls.VersionTLS13, CurvePreferences: []tls.CurveID{tls.MLKEM1024}}) + + info, err := probeCertificate(context.Background(), s) + if err != nil { + t.Fatalf("probeCertificate() error = %v, want the certificate of a pure ML-KEM server", err) + } + if len(info.Chain) != 1 { + t.Errorf("got %d certificates, want 1", len(info.Chain)) + } +} + +// The session's host is what the hostname verdict is judged against, so a +// certificate for another name must come back as a mismatch, not an error. +func TestProbeCertificate_HostnameMismatch(t *testing.T) { + s := startTLSServer(t, &tls.Config{MinVersion: tls.VersionTLS12}) + s.host = "other.test" + + info, err := probeCertificate(context.Background(), s) + if err != nil { + t.Fatalf("probeCertificate() error = %v", err) + } + if info.HostnameVerdict != HostnameMismatch { + t.Errorf("HostnameVerdict = %q, want %q", info.HostnameVerdict, HostnameMismatch) + } +} diff --git a/internal/domain/encryption_protocols.go b/internal/domain/encryption_protocols.go new file mode 100644 index 0000000..46d44e5 --- /dev/null +++ b/internal/domain/encryption_protocols.go @@ -0,0 +1,64 @@ +package domain + +import ( + "context" + "crypto/tls" + "fmt" +) + +// probedVersions are the protocol versions a lookup offers, newest first. +// SSL 3.0 and earlier are absent because the standard library cannot speak +// them; a server that accepts only those reports ErrNoHandshake. +var probedVersions = []struct { + id uint16 + name string +}{ + {tls.VersionTLS13, "TLS 1.3"}, + {tls.VersionTLS12, "TLS 1.2"}, + {tls.VersionTLS11, "TLS 1.1"}, + {tls.VersionTLS10, "TLS 1.0"}, +} + +// LookupProtocols reports which TLS versions host accepts on port 443. +func LookupProtocols(ctx context.Context, host string) (*ProtocolsInfo, error) { + s, err := newSession(ctx, host) + if err != nil { + return nil, err + } + return probeProtocols(ctx, s) +} + +// probeProtocols offers each version on its own, one handshake per version. +// Offering a range would only show which version the server prefers. +func probeProtocols(ctx context.Context, s *session) (*ProtocolsInfo, error) { + info := &ProtocolsInfo{Evidence: s.evidence()} + anyAccepted := false + + for _, v := range probedVersions { + _, accepted, err := s.offer(ctx, &tls.Config{ + // Deliberately reaches down to TLS 1.0 with every cipher suite: + // finding out whether the server still accepts them is the lookup. + // Every group too, so the answer is about the version and not + // about which key exchange the server happens to require. + MinVersion: v.id, + MaxVersion: v.id, + CipherSuites: everyCipherSuite(), + CurvePreferences: everyGroup(), + }) + if err != nil { + return nil, fmt.Errorf("%s: %w", v.name, err) + } + info.Versions = append(info.Versions, ProtocolVersion{Name: v.name, Accepted: accepted}) + if accepted { + anyAccepted = true + if v.id == tls.VersionTLS10 || v.id == tls.VersionTLS11 { + info.LegacyAccepted = true + } + } + } + + if !anyAccepted { + return nil, ErrNoHandshake + } + return info, nil +} diff --git a/internal/domain/errors.go b/internal/domain/errors.go index b975246..b2b87b3 100644 --- a/internal/domain/errors.go +++ b/internal/domain/errors.go @@ -78,6 +78,12 @@ func IsExpectedError(err error) bool { return true } + // The encryption probe reached the target and every handshake it offered + // was refused. Whatever is listening on 443 does not speak TLS to us. + if errors.Is(err, ErrNoHandshake) { + return true + } + // TLS handshake failures below the certificate layer — a target that is not // speaking TLS on 443, or speaking it badly. That is a finding about them. var recordErr tls.RecordHeaderError @@ -102,10 +108,12 @@ func IsExpectedError(err error) bool { // Certificate *verification* failures are deliberately NOT expected. // - // Everything that touches an arbitrary target domain — LookupSSL, and the - // headers lookup via safeTransport — sets + // Everything that touches an arbitrary target domain — LookupSSL, the + // encryption probe, and the headers lookup via safeTransport — sets // InsecureSkipVerify, precisely so it can inspect expired and self-signed - // certificates. So an x509 error cannot come from a target. It can only + // certificates. The certificate lookup does verify the chain afterwards, + // but it reports the outcome as a verdict and discards the error (see + // trustVerdict). So an x509 error cannot come from a target. It can only // come from trustedTransport, which is used solely for crt.sh, RDAP, // VirusTotal, URLhaus and AlienVault OTX — services with valid public // certificates. diff --git a/internal/domain/errors_test.go b/internal/domain/errors_test.go index af2a157..1a9e314 100644 --- a/internal/domain/errors_test.go +++ b/internal/domain/errors_test.go @@ -46,6 +46,8 @@ func TestIsExpectedError_Expected(t *testing.T) { {"connection reset", fmt.Errorf("read: %w", syscall.ECONNRESET)}, {"tls record header", tls.RecordHeaderError{Msg: "first record does not look like a TLS handshake"}}, + + {"encryption probe refused on every offer", ErrNoHandshake}, } for _, tt := range tests { diff --git a/internal/handler/changelog.yaml b/internal/handler/changelog.yaml index 80c2e35..fc1ce27 100644 --- a/internal/handler/changelog.yaml +++ b/internal/handler/changelog.yaml @@ -10,6 +10,28 @@ # terms (#91). An entry a later release reversed keeps its text and gains a # "superseded in vX" note, rather than being hidden or rewritten. +- version: v1.3.0 + date: 2026-11-16 + changes: + - text: "New endpoint: `POST /v1/encryption/lookup` reports how well a host's encryption holds up, checked from the outside with TLS handshakes to port 443. It takes a `hosts` array and the same required `lookups` array as the other endpoints, and returns the same `results` envelope with a per-lookup `cache_hit`. Documented at `/docs/encryption` and in the OpenAPI specification" + audience: public + - text: "`protocols` reports which of TLS 1.0, 1.1, 1.2 and 1.3 the host accepts, with `legacy_accepted` set when it still takes the two retired versions" + audience: public + - text: "`key_exchange` reports which of eight key exchange groups the host accepts, four of them post-quantum, which one it picks when offered all of them, and a `post_quantum` or `classical` verdict: whether the host supports a key exchange that protects traffic recorded today from being decrypted later. A client still has to negotiate one of those groups to get that protection" + audience: public + - text: "`certificate` describes every certificate in the chain the host sends (key type and size, signature algorithm, validity) and gives four verdicts: `expiry_verdict`, `algorithm_verdict`, `trust_verdict` (does the chain lead to a publicly trusted root) and `hostname_verdict` (does the certificate cover the host). An expired, untrusted or mismatched certificate is reported in those verdicts, not returned as an error" + audience: public + - text: "Every encryption result says which address was probed (`ip`) and when (`probed_at`). A lookup returns a complete answer or fails: a handshake that times out fails the lookup and is not cached, so it is never reported as the host refusing" + audience: public + - text: "All three encryption lookups are available on every plan: 1 host per request on free, 20 on pro. Usage statistics gain `total_hosts`, the hosts submitted to the new endpoint" + audience: public + - text: "Encryption endpoint internals (#136): `EncryptionService` on the shared runner, cache keys under `encryption:`, config keys `encryption.lookup_timeout`, `encryption.probe_timeout`, `encryption.max_hosts.*` and `cache.ttl.protocols` / `key_exchange` / `certificate` (12h, 12h, 4h). The probe pins one address per lookup and dials through `safenet.SafeDialer`; `ErrNoHandshake` is classified as expected so a host with nothing on 443 does not alert" + audience: internal + - text: "Migration `018_request_log_encryption.sql` adds `host_count` and the `protocols`, `key_exchange` and `certificate` columns to `request_log`. Apply it to production before deploying this version: the build names those columns in every usage insert" + audience: internal + - text: "`sactl lookup encryption HOST` and an Encryption posture entry in the interactive lookup menu; `sactl usage` prints the host total" + audience: internal + - version: v1.2.0 date: 2026-11-16 changes: diff --git a/internal/handler/docs.go b/internal/handler/docs.go index dddc872..fd4d74b 100644 --- a/internal/handler/docs.go +++ b/internal/handler/docs.go @@ -49,6 +49,9 @@ var docsDomainHTML string //go:embed docs_ip.html var docsIPHTML string +//go:embed docs_encryption.html +var docsEncryptionHTML string + //go:embed docs_account.html var docsAccountHTML string @@ -61,6 +64,7 @@ var docsNotFoundHTML string var docsTmpl = template.Must(template.New("docs").Parse(docsHTML)) var docsDomainTmpl = template.Must(template.New("docs_domain").Parse(docsDomainHTML)) var docsIPTmpl = template.Must(template.New("docs_ip").Parse(docsIPHTML)) +var docsEncryptionTmpl = template.Must(template.New("docs_encryption").Parse(docsEncryptionHTML)) var docsAccountTmpl = template.Must(template.New("docs_account").Parse(docsAccountHTML)) var docsChangelogTmpl = template.Must(template.New("docs_changelog").Parse(docsChangelogHTML)) var docsNotFoundTmpl = template.Must(template.New("docs_404").Parse(docsNotFoundHTML)) @@ -84,6 +88,7 @@ var docsPages = []docsPage{ {"/docs", docsHTML, docsTmpl}, {"/docs/domain", docsDomainHTML, docsDomainTmpl}, {"/docs/ip", docsIPHTML, docsIPTmpl}, + {"/docs/encryption", docsEncryptionHTML, docsEncryptionTmpl}, {"/docs/account", docsAccountHTML, docsAccountTmpl}, {"/docs/changelog", docsChangelogHTML, docsChangelogTmpl}, } @@ -248,5 +253,6 @@ func isAPIPath(path string) bool { // the overview and the domain reference, which pushed the changelog's length // onto pages people open to look something up and meant two copies of the same // list to keep in sync. Likewise the account endpoints have their own page -// rather than a table row on the overview: /v1/usage and /v1/keys/rotate are -// two of the four public endpoints and were the only two with no reference. +// rather than a table row on the overview: /v1/usage and /v1/keys/rotate were +// two of the four public endpoints at the time, and the only two with no +// reference. diff --git a/internal/handler/docs.html b/internal/handler/docs.html index fcde48d..9d1536c 100644 --- a/internal/handler/docs.html +++ b/internal/handler/docs.html @@ -3,9 +3,9 @@ - + - + Intelligence API Documentation @@ -116,9 +116,11 @@ .hero-metrics small { color: var(--ink-soft); font-size: 13px; } + /* Two columns for four cards: the three endpoints and the shared contract + sit in a 2x2 block instead of leaving one card alone on a second row. */ .services { display: grid; - grid-template-columns: repeat(3, minmax(0, 1fr)); + grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 20px; margin-top: 24px; } @@ -263,6 +265,7 @@ Overview Domain IP + Encryption Account Changelog @@ -285,7 +288,7 @@

Documentation

Intelligence API

-

Security Accelerated exposes domain and IP intelligence through a single REST surface tuned for operational triage, enrichment, and automation.

+

Security Accelerated exposes domain intelligence, IP intelligence, and encryption posture through a single REST surface tuned for operational triage, enrichment, and automation.

https://api.securityaccelerated.com @@ -300,9 +303,9 @@

Operational Profile

Built for direct lookup workflows, enrichment jobs, and security automation where latency, limits, and failure modes need to be obvious.

  • - 2 + 3 Core endpoints - Domain and IP intelligence with shared auth and rate limiting. + Domain intelligence, IP intelligence, and encryption posture with shared auth and rate limiting.
  • 30m–24h @@ -352,7 +355,7 @@

    Your first request

  • Each lookup carries its own cache_hit, so one result can mix cached and freshly fetched fields.
  • A lookup that fails does not fail the request. You get 200, the field is absent, and the reason is in errors, which is present only when something failed — see partial failures.
-

Full reference: Domain Intelligence and IP Intelligence.

+

Full reference: Domain Intelligence, IP Intelligence, and Encryption Posture.

@@ -368,9 +371,15 @@

IP Intelligence

POST/v1/ip/lookup
Open endpoint reference +
+

Encryption Posture

+

Which TLS versions a host accepts, which key exchange groups it accepts including post-quantum ones, and what its certificate chain looks like — algorithms, expiry, trust, and hostname match — checked from the outside on port 443.

+
POST/v1/encryption/lookup
+ Open endpoint reference +

Shared contract

-

Both APIs use the same authentication model, plan gating, JSON error envelope, and request tracing headers, so client integration stays predictable.

+

All three APIs use the same authentication model, plan gating, JSON error envelope, and request tracing headers, so client integration stays predictable.

  • Use X-API-Key on every request.
  • Pass X-Client-Request-ID for your own trace IDs.
  • @@ -397,8 +406,10 @@

    Plans

    Rate limit5 req/min120 req/min Domains per request120 IPs per request120 + Hosts per request (encryption)120 Core lookups (WHOIS, DNS, SSL, headers, GeoIP, ASN, RDNS)YesYes Email security, subdomains, CT logs, BGP, fingerprint, DNS security, abuse contactYesYes + Encryption posture (TLS versions, key exchange, certificate)YesYes Aggregate risk score (add risk to lookups)YesYes Usage statistics + self-service key rotationYesYes Reputation, threat intelligence-Yes @@ -431,6 +442,7 @@

    Rate Limiting

    Caching

    Domain results are cached per lookup, per domain, each with its own TTL — 30 minutes for fast-moving data like dns and headers, up to 24 hours for whois and ct_logs. Every lookup object reports its own cache_hit, so a single result can mix cached and live fields. See the Domain Intelligence docs for the full table.

    IP results work the same way, under a separate ip: key namespace — 24 hours for abuse_contact and asn, 6 hours for reverse_dns, 30 minutes for threat_intel. geo reads a local database and is never cached, so its cache_hit is always false. See the IP Intelligence docs.

    +

    Encryption results are cached per lookup, per host — 12 hours for protocols and key_exchange, 4 hours for certificate. Each result says when it was observed and which address answered. See the Encryption Posture docs.

diff --git a/internal/handler/docs_404.html b/internal/handler/docs_404.html index 957c491..aa37a3f 100644 --- a/internal/handler/docs_404.html +++ b/internal/handler/docs_404.html @@ -92,6 +92,7 @@ Overview Domain IP + Encryption Account Changelog @@ -123,6 +124,7 @@

No route here

  • OverviewAuthentication, plans, rate limits, and error handling
  • Domain IntelligencePOST /v1/domain/lookup and every response field
  • IP IntelligencePOST /v1/ip/lookup and every response field
  • +
  • Encryption PosturePOST /v1/encryption/lookup and every response field
  • AccountYour usage statistics, and rotating your key
  • ChangelogCustomer-facing changes, newest first
  • OpenAPI specificationGenerate a client from the full contract
  • diff --git a/internal/handler/docs_account.html b/internal/handler/docs_account.html index 110ac0d..f863e80 100644 --- a/internal/handler/docs_account.html +++ b/internal/handler/docs_account.html @@ -23,6 +23,7 @@ Overview Domain IP + Encryption Account Changelog @@ -183,6 +184,7 @@

    Response

    "avg_latency_ms": 412.8, "total_domains": 2140, "total_ips": 96, + "total_hosts": 0, "status_codes": { "200": 1270, "429": 14 }, "feature_usage": { "dns": 2140, "ssl": 2140, "whois": 757 }, "requests_by_path": { "/v1/domain/lookup": 1188, "/v1/ip/lookup": 96 }, @@ -202,6 +204,7 @@

    Response Fields

    avg_latency_msfloatMean server-side response time in milliseconds total_domainsintDomains submitted across all requests, counting duplicates total_ipsintIPs submitted across all requests, counting duplicates + total_hostsintHosts submitted to the encryption endpoint across all requests, counting duplicates status_codesobjectRequest counts keyed by HTTP status code feature_usageobjectCounts keyed by lookup name — see below requests_by_pathobjectRequest counts keyed by endpoint path @@ -286,7 +289,7 @@

    Error Handling

    Prefer to generate a client? The full OpenAPI 3.1 specification - covers every endpoint — domain lookup, IP lookup, usage, and key rotation. + covers every endpoint — domain lookup, IP lookup, encryption lookup, usage, and key rotation.

    {{.Version}}