Add deployment security & compliance docs (SECURITY.md)#22
Conversation
Documents the guidance that recurs in security questionnaires and compliance reviews, closing the gaps from the Symphony + WAF security review (#13): 1. Private key handling — inline vs by-path sources, in-memory Zeroizing, on-disk file permission/ownership baseline, and live file-watch rotation. 2. Config-file integrity — the hot-reloaded config is a traffic-control surface; recommend restrictive perms + file-integrity monitoring. 3. MD5/JA3 rationale — MD5 appears only because JA3 is defined over it; it is a non-cryptographic identity label, not an integrity/auth use. Includes a ready questionnaire answer. JA4 (truncated SHA-256) noted as the successor. 4. TLS parameters attestation (plan-for-later) — current rustls 0.23 + ring provider / TLS 1.2+1.3 state, PCI DSS 12.3.3 reporting need, and the aws-lc-rs FIPS provider-swap path (incl. the ring/md-5 call sites to move). 5. DDoS shared-responsibility statement — L3/L4 volumetric is upstream's; Symphony provides connection-level controls. Includes a questionnaire answer. Items 1-3 are documentation; 4-5 are design notes to keep options open. Linked from README. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new SECURITY.md file and updates the README.md to document deployment security and compliance guidelines for Symphony, covering private key handling, configuration file integrity, non-cryptographic MD5 usage in JA3, TLS parameter attestation plans, and DDoS shared responsibility. The review feedback suggests removing an internal reference to CLAUDE.md from the public documentation and clarifying that the ja4Blocklist feature is upcoming to prevent operator confusion.
kriszyp
requested review from
Devin-Holland
and removed request for
Ethan-Arrowood
Devin-Holland
left a comment
Devin-Holland
left a comment
There was a problem hiding this comment.
New SECURITY.md for Symphony plus a README link. Clear, well-scoped deployment guidance with ready-made questionnaire answers. Correctly frames JA3's MD5 as a non-cryptographic label and DDoS as shared-responsibility, and is honest about what's not implemented yet (TLS-parameter reporting, the FIPS aws-lc-rs path, k8s projected-volume rotation not covered by the file watcher).
One spot-check (the doc makes concrete code claims): the Zeroizing PEM wipe, the ring call sites in src/tls.rs (Ticketer + cert-dedup SHA-256), and JA3 in src/sni.rs should match the current code so the questionnaire answers stay accurate. Assuming those are current, good to ship.
2 participants
Closes #13.
What this adds
A new
SECURITY.mdwith the deployment-hardening and security-questionnaire guidance that keeps coming up in customer compliance reviews, plus a short pointer section in the README. Docs-only — no code changes.Covers the five items from #13:
Private key handling — where keys come from (inline PEM vs
certChainFile/privateKeyFileinsymphony-server), what happens in memory (the PEM buffer isZeroizingand zeroed on drop — seesrc/tls.rs::CertSpec), a recommended on-disk baseline (key files0600, key dir0700, dedicated non-root service user +CAP_NET_BIND_SERVICE), and how live file-watch rotation behaves, including the known k8s..datasymlink-swap gap. Explicitly notes KMS/HSM is out of scope by design.Config-file integrity — the standalone server hot-reloads its config on change, which makes the config file a traffic-control surface: whoever can write it can redirect traffic silently, with no restart to notice. Recommends restrictive permissions plus file-integrity monitoring (FIM) as the primary detection, generating the config from a controlled source rather than hand-editing, and treating
status.jsonas untrusted output.MD5/JA3 rationale — one written explanation that MD5 appears in the dependency tree solely because the JA3 standard is defined over it, that it's a non-cryptographic identity label (not integrity/auth/signing/confidentiality), and that JA4 (truncated SHA-256) is the randomization-resistant successor. Includes a ready-to-paste questionnaire answer so support/sales don't improvise.
TLS parameters attestation (plan-for-later) — documents the current state accurately (rustls 0.23 with the
ringCryptoProvider,tls12feature on → TLS 1.2 + 1.3 with rustls defaults; neither configurable nor reportable today), why PCI DSS 12.3.3 makes reportability worth building eventually, and the rustlsaws-lc-rsFIPS 140-3 path — including the honest caveat that a provider swap also has to move the explicitringcall sites (sessionTicketer, cert-dedup SHA-256) and JA3'smd-5. Marked clearly as not implemented, recorded to keep the design open.Shared-responsibility DDoS statement — L3/L4 volumetric protection is the upstream network/cloud provider's job; Symphony contributes connection-level controls (per-IP rate/concurrency limits, CIDR lists, handshake timeouts,
requireSni, JA3/JA4 blocklists). Also written as a ready questionnaire answer.Notes for reviewers
src/tls.rs,Cargo.toml, the server cert-watch behavior) rather than written from memory — worth a second pair of eyes on the TLS/provider facts in §4 especially.ja4Blocklist, which lands with PR Add JA4 TLS client fingerprinting (core, BSD-scoped) and fix GREASE filtering #20; if this merges first that's a brief forward reference, if Add JA4 TLS client fingerprinting (core, BSD-scoped) and fix GREASE filtering #20 merges first it's accurate on arrival. Happy to reword if you'd rather not race.Drafted by KrAIs (Claude Fable) on Kris's behalf.
🤖 Generated with Claude Code