Open-Source Wikis

/

Caddy

/

Security

caddyserver/caddy

Security

Caddy is a TLS-terminating server that handles internet-facing traffic. Several parts of the code are explicitly security-critical and call out for extra care.

The authoritative reporting policy is .github/SECURITY.md. Please read it before submitting a report.

Trust boundaries

graph TD
    Internet[Internet client]
    AdminUser[Operator]
    Caddy[Caddy process]
    Storage[Storage backend]
    Upstream[Upstream services]
    OS[OS trust store]
    ACME[Public ACME CAs]

    Internet -->|TLS| Caddy
    Caddy -->|optional mTLS| Upstream
    AdminUser -->|HTTP / mTLS| Caddy
    Caddy -->|read/write certs, OCSP| Storage
    Caddy -->|ACME challenges| ACME
    Caddy -->|caddy trust adds root| OS

Boundaries that need scrutiny:

  • Public TLS: the inbound TLS handshake (modules/caddytls/connpolicy.go, ~39 KB).
  • ACME issuance: the path from automation policy to issuer to private key on disk (modules/caddytls/automation.go, acmeissuer.go).
  • Admin endpoint: the local admin API can rewrite the entire running config (admin.go).
  • Local CA: the PKI app's private root and intermediates (modules/caddypki/ca.go, crypto.go).
  • Reverse proxy: request forwarding can leak sensitive headers if mis-configured (modules/caddyhttp/reverseproxy/).

AGENTS.md flags caddyhttp and caddytls explicitly as security-critical packages requiring extra review scrutiny.

Hardening defaults

  • Admin endpoint binds to localhost:2019 with origin enforcement: requests with foreign Host/Origin headers are rejected (admin.go: originAllowed). To bind to a non-loopback address, configure AdminConfig.Identity for client-cert auth.
  • TLS defaults to safe ciphers and protocols; connpolicy.go and values.go define the curated lists.
  • Auto-HTTPS only manages certificates for hostnames that explicitly appear in matchers; IP-only sites get no automatic certs.
  • skip_install_trust exists to keep tests from polluting the OS trust store; production never opts into that.
  • The reverse proxy strips Authorization/Cookie headers when trusted_proxies is not set up to validate the inbound chain (see reverseproxy.go's header-handling logic).

On-demand TLS rate-limiting

modules/caddytls/ondemand.go rate-limits and gates on-demand certificate issuance. Without those gates, an attacker could trigger ACME issuance for arbitrary hostnames pointed at your server. The ask endpoint pattern is the recommended permission check.

ECH (Encrypted ClientHello)

modules/caddytls/ech.go (~43 KB) implements ECH so that SNI is no longer a trivial sidechannel. Operators publishing ECH config keys should follow the rotation discipline encoded in that file.

Logging redaction

The filter encoder + filter modules (modules/logging/filterencoder.go, filters.go) make it possible to redact cookie values, query parameters, and IP addresses in access logs. Use caddy.logging.encoders.filter.cookie, …filter.query, …filter.ip_mask, etc., for any log destination that may end up in less-trusted hands.

AI policy and reports

The security policy (SECURITY.md) requires that vulnerability reports disclose whether AI was used at any stage — discovery, writing, testing, or validating. Failure to disclose is grounds for dismissal and possible blocklisting. The wording is unusually direct because the project receives many low-quality automated reports.

AGENTS.md likewise requires that AI-assisted contributions be disclosed and fully comprehended by the human contributor.

Reporting a vulnerability

  • File a private advisory at https://github.com/caddyserver/caddy/security/advisories/new.
  • Include a minimal reproducible config, exact commands, full debug logs, and ideally a patch diff.
  • Use real domain names (the policy considers public registrations to be public information).
  • Do not encrypt the message.

Out of scope (per SECURITY.md):

  • Misconfigurations.
  • Issues in dependencies (open a regular PR to bump them).
  • Pre-release code.
  • Client-side issues, IP spoofing, BGP, or anything that requires a compromised system to exploit.

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.

Security – Caddy wiki | Factory