Protocol security

Protocol Security

Rules (for AI agents)

ALWAYS

• Default to TLS 1.3 for new clients and servers; permit TLS 1.2 only for interop with legacy peers. Disable TLS 1.0/1.1, SSLv2/v3.
• Validate the server certificate: chain to a trusted CA, name matches the expected hostname (or SAN), not expired, not revoked (OCSP stapling enabled).
• Enable HSTS on HTTP responses for everything served over HTTPS: Strict-Transport-Security: max-age=63072000; includeSubDomains; preload. Add the host to the HSTS preload list once stable.
• Use mutual TLS (mTLS) for service-to-service traffic inside a trust domain (mesh: Istio / Linkerd; standalone: SPIFFE / SPIRE for identity).
• For gRPC clients/servers, use grpc.secure_channel / grpc.SslCredentials / credentials.NewTLS — never insecure_channel in production.
• For WebSocket servers, validate the Origin header against an allowlist and authenticate the handshake (cookies + CSRF token, or a query-string bearer used once at upgrade and re-validated).
• For service-to-service tokens, prefer SPIFFE IDs (spiffe://trust-domain/...) with short-lived workload certs over long-lived API keys.
• Pin the certificate (public key pinning) for high-risk mobile / desktop clients calling back to the operator's own backend.

NEVER

• Disable certificate verification (InsecureSkipVerify: true, verify=False, rejectUnauthorized: false, CURLOPT_SSL_VERIFYPEER=0). The only acceptable use is in a unit test that runs against a localhost ephemeral cert.
• Implement a custom X509TrustManager / HostnameVerifier / URLSessionDelegate / ServerCertificateValidationCallback that unconditionally returns trusted.
• Mix HTTP and HTTPS resources on the same page (mixed content) — modern browsers will block subresources, but APIs are still vulnerable to MITM downgrade.
• Send tokens / passwords over plain HTTP — even on localhost in dev unless the dev environment is documented as not security-relevant.
• Use grpc.insecure_channel(...) in production code.
• Trust the Host / X-Forwarded-Host / Forwarded header without an allowlist; absolute URLs built from Host enable host-header injection and password-reset poisoning.
• Forward incoming Authorization / Cookie headers blindly across origins in your service mesh — re-derive identity from mTLS or a service token.
• Enable TLS renegotiation on clients you control; pin to tls.NoRenegotiation where available.

KNOWN FALSE POSITIVES

• Localhost-only dev servers with self-signed certs and explicit documentation are fine; CI tests against ephemeral CA-signed certs are fine.
• A small number of legacy enterprise integrations require TLS 1.2 with a specific cipher; document the exception and isolate the integration behind a proxy.
• Public read-only endpoints (e.g., status pages) can legitimately serve over HTTP for cacheability, though HTTPS is still preferred.

Context (for humans)

NIST SP 800-52 Rev. 2 is the authoritative US-government TLS reference; RFC 8446 is TLS 1.3 itself. The recurring failure mode in code review is InsecureSkipVerify (or its equivalents in every language) — usually introduced "to make tests work" and never reverted.

This skill pairs naturally with crypto-misuse (algorithm choice) and auth-security (token issuance).

Verify & lock (triaging a finding)

A scanner/review hit is a candidate, not a confirmed bug. Confirm it, fix it, then lock it so it can't come back.

1. Confirm it's real (probe the suspect endpoint/handshake). Drive the live client or server with a scanning client. For TLS downgrade / weak ciphers, run testssl.sh host:port or force a sub-1.2 handshake: openssl s_client -connect host:port -tls1_1 (or -cipher 'DES-CBC3-SHA'). For cert validation, present an invalid/self-signed/wrong-host cert and see if the client completes the connection. For plaintext fallback / missing HSTS, hit the HTTP scheme and watch for a 200 with no redirect or no Strict-Transport-Security. For gRPC, check whether an insecure_channel peer connects. Real if the weak handshake succeeds, the bad cert is accepted, or plaintext is served — a false positive is a localhost/CI ephemeral cert, a documented legacy-peer exception, or a public read-only HTTP status page (per KNOWN FALSE POSITIVES).
2. Fix, then lock with a regression test (unit or integration — dev's call). Assert the connection is rejected for: TLS < 1.2, a disabled weak cipher, an invalid/self-signed/hostname-mismatched cert (i.e. no InsecureSkipVerify / verify=False / rejectUnauthorized:false), and a plaintext/insecure_channel peer. Assert HSTS is present on HTTPS responses and the WebSocket handshake rejects a disallowed Origin. Include the benign case: a valid TLS 1.2/1.3 handshake with a CA-signed, hostname-matched cert still succeeds. Commit it to CI so the guard can't be silently dropped in a later refactor.

References

• rules/tls_defaults.json
• rules/cert_validation_sinks.json
• NIST SP 800-52 Rev. 2.
• RFC 8446 — TLS 1.3.
• OWASP Transport Layer Security Cheat Sheet.
• CWE-295 — Improper Certificate Validation.