Przejdź do treści
Biblioteka skilli
DevOps i chmura · Przegląd i audyt

edge-proxy-tls

/edge-proxy-tls

Projektuje i przegląda brzegowy serwer Caddy: TLS na żądanie dla domen klientów, zaufane proxy, limity żądań i utwardzony kontener.

Repozytorium
skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
08.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
30
Przestarzałość

Brak sygnałów. Repozytorium zmienione 08.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Projektuje i przegląda brzegowy serwer Caddy: TLS na żądanie dla domen klientów, zaufane proxy, limity żądań i utwardzony kontener.

Oryginalny opis (EN)

Designs and reviews a Caddy edge: on-demand TLS for customer domains gated by an ask endpoint without secrets in the URL, trusted proxies and X-Forwarded-* handling, real client IPs, rate limits, cache headers with stale-if-error, a hardened edge container, caddy validate in CI and two edges. Use when editing a Caddyfile or custom-domain TLS. Not for in-cluster ingress or CDN setup.

Jak działa

  1. Applies when / does not apply
  2. Rules
  3. Procedure
  4. Traps
  5. Done when
  6. References
  7. Sources
Sekcje z nagłówków SKILL.md, w oryginale · 192 linii, 2 152 słów
Podgląd SKILL.md
---
name: edge-proxy-tls
description: "Designs and reviews a Caddy edge: on-demand TLS for customer domains gated by an ask endpoint without secrets in the URL, trusted proxies and X-Forwarded-* handling, real client IPs, rate limits, cache headers with stale-if-error, a hardened edge container, caddy validate in CI and two edges. Use when editing a Caddyfile or custom-domain TLS. Not for in-cluster ingress or CDN setup."
license: Apache-2.0
metadata:
  author: "Rene Roscher"
paths:
  - "**/Caddyfile*"
  - "**/*.caddyfile"
  - "**/xcaddy*"
---

# Edge proxy and TLS

This skill decides how the public edge terminates TLS for the product's own domains and for customer domains,
which forwarded headers it trusts, how it protects the origin, and how its config is proven before it ships. The
examples use Caddy; the header, cache and container rules hold for any reverse proxy. Caddy syntax stays with the
Caddy docs; failover of the edge pair belongs to `high-availability`. The failure this prevents: an edge that
issues certificates for any name an attacker sends, leaks its gate secret into logs, builds `http://` redirects
behind TLS, falls over under a flood and runs as root on the host network.

## Applies when / does not apply

- Applies: a Caddyfile or Caddy JSON config; custom domains for customers (status pages, shops, white-label
  apps); the endpoint that approves certificate issuance; trusted proxy and client IP settings in the edge or
  the app behind it; rate limits, cache headers and error pages at the edge; the edge's container or service unit;
  CI for the edge image.
- Does not apply: Kubernetes Ingress or Gateway objects inside the cluster, a managed CDN's own config,
  certificate questions for internal mTLS, DNS failover (`high-availability`), application-level throttling.

## Rules

### On-demand TLS

- [invariant] `on_demand` is enabled only together with an `ask` endpoint (or a `permission` module), and the
  endpoint returns 2xx only for domains a customer added and verified. Every other case, including an internal
  error, returns a non-2xx status. Why: Caddy's docs say "On-demand TLS must be both enabled and restricted to
  prevent abuse"; an endpoint that fails open issues certificates for any name pointed at the edge. Test: ask for
  a random domain, a pending domain, and a verified domain with the database unreachable; only the verified
  domain with a working database gets 2xx. Source: https://caddyserver.com/docs/automatic-https and
  https://caddyserver.com/docs/caddyfile/options (`?domain=` query, 2xx authorizes), verified 2026-11-03.
- [invariant] The ask endpoint is reachable only on a private network or loopback, and a shared secret, if used,
  is never part of the URL. Put it in a request header added by a loopback-only Caddy site that proxies to the
  app, compare it in constant time, and fail closed when the secret is unset. Why: query strings end up in access
  logs, error trackers and config dumps; the ask URL is part of the config. Test: the config's `ask` URL contains
  no `secret=`, `token=` or `key=`; a request without the header and an app with an empty secret both get 403.
  Source: reproducible with the test above; pattern in
  [references/on-demand-tls.md](references/on-demand-tls.md).
- [invariant] Issuance has its own limits, because Caddy's `interval` and `burst` options "are NOT recommended":
  the ask route is throttled, answers are cached briefly (negatives shorter than positives), the lookup is a
  constant-time indexed query without DNS or network calls, and a breaker stops new orders when failed ACME
  attempts exceed a budget. Why: a flood of distinct SNI names otherwise hammers the app and burns CA rate limits.
  Test: 1,000 handshakes with random names under a customer suffix produce no ACME order and stay within the
  throttle at the app. Source: https://caddyserver.com/docs/caddyfile/options (ask "should return as fast as
  possible", deprecated rate options), verified 2026-11-03.
- [invariant] All edges share one certificate storage, so a failover or a new node reuses existing certificates.
  Why: "Any Caddy instances that are configured to use the same storage will automatically share those resources
  and coordinate certificate management as a cluster"; separate storage re-issues every certificate on failover.
  Test: fail over to the second edge; its log shows no new orders for known domains. Source:
  https://caddyserver.com/docs/automatic-https, verified 2026-11-03.
- [invariant] The certificate actually served is monitored from outside: expiry and issuer for the product's
  wildcard and for one synthetic customer domain the product owns. Why: renewals can fail silently for days while
  the old certificate still works. Test: a blackbox probe alerts at a set number of days before expiry. Source:
  reproducible with the test above.

### Forwarded headers and client IP

- [invariant] Trust `X-Forwarded-*` only from listed proxy ranges: `trusted_proxies` (by default "no proxies are
  trusted"), `client_ip_headers`, and `trusted_proxies_strict` for right-to-left parsing. Why: the docs warn that
  "the left-most IP address may be spoofed by the client". Test: send `X-Forwarded-For: [documentation address]`
  directly to the edge; the access log shows the real peer address. Source:
  https://caddyserver.com/docs/caddyfile/options and
  https://caddyserver.com/docs/caddyfile/directives/reverse_proxy, verified 2026-11-03.
- [invariant] Behind the edge, nobody trusts the forwarded scheme and port blindly. The edge sets
  `X-Forwarded-Proto: https` for TLS sites; a second proxy hop (an in-cluster ingress) either passes the edge's
  headers through for the edge's address range only, or the app derives the public scheme from its configured base
  URL; nginx-based hops use `absolute_redirect off`. Why: a hop that receives plain HTTP from the edge reports
  `http` and port 80, and the app then emits `http://` redirects, canonical URLs and `:80` links that search
  engines index. Test: `curl -sI https://[host]/[path that redirects]` returns a relative or `https://` Location
  without a port, and the canonical tag is `https`. Source: https://nginx.org/en/docs/http/ngx_http_core_module.html
  (`absolute_redirect`, `port_in_redirect`) and
  https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/ (`use-forwarded-headers`
  default false), verified 2026-11-03.
- [invariant] The real client IP reaches the app before any rate limit or audit log relies on it: PROXY protocol
  turned on at the load balancer and the receiver in the same change, or forwarded headers with trusted ranges.
  Why: with SNAT every request carries the balancer's address, so one client's limit blocks everyone. Test: a
  request from a known address appears with that address in the app log. Source: reproducible with the test above.

### Protecting the origin

- [invariant] Rate limit per client address and per prefix (IPv4 /24, a short IPv6 prefix) at the edge, before
  the cache, with a distinct 429 page marked `Cache-Control: no-store`. Caddy needs a plugin for this (for example
  `caddy-ratelimit`, built with `xcaddy`), so CI checks that the module is in the binary. Why: a distributed flood
  on an uncacheable URL can take the edge down, and a cached 429 serves the limit to everyone. Test: a burst from
  one address gets 429, a second address is unaffected, and the 429 carries `no-store`. Source:
  https://github.com/mholt/caddy-ratelimit (not built in, `ipv4_prefix`, `ipv6_prefix`, shared state), verified
  2026-11-03.
- [default] Request hygiene at the edge: drop client `Cache-Control`, `Pragma` and `Authorization` before the
  cache on public pages, cap request body size, answer 404 for internal paths, keep the upstream retry window
  (`lb_try_duration`) short, and use passive health checks (`unhealthy_latency`, `unhealthy_request_count`) to shed
  load. Trade-off: some clients lose the ability to force a refresh. Deviate only with an ADR that names this
  trade-off. Source: https://caddyserver.com/docs/caddyfile/directives/reverse_proxy, verified 2026-11-03.

### Caching public pages

- [invariant] The origin decides cacheability per response with `Cache-Control`; anything unmarked is `no-store`.
  Responses that depend on a session, cookie or token are never shared-cached. Why: a cache that guesses serves one
  user's page to another. Test: a logged-in response carries `private` or `no-store` and the edge does not store
  it. Source: reproducible with the test above.
- [invariant] Public pages carry `stale-if-error` (and `stale-while-revalidate` where freshness allows), and error
  responses (5xx, 429) are `no-store` so they never replace the last good copy. Why: during an origin outage the
  edge keeps serving the last good page; RFC 5861 says a stale response "MAY be used to satisfy the request,
  regardless of other freshness information". Test: stop the origin; a cached page is still served with an `Age`
  header beyond its max-age. Source: https://www.rfc-editor.org/rfc/rfc5861.html, verified 2026-11-03.

### The edge itself

- [invariant] The edge container does not run as root on the host network. It runs as a non-root user, adds back
  only `NET_BIND_SERVICE` (or binds high ports behind a port mapping), uses `read_only: true` with tmpfs for
  writable paths, `cap_drop: [ALL]`, `no-new-privileges`, a hard memory limit with the Go heap limit
  (`GOMEMLIMIT`) below it, and the admin endpoint off or on loopback. Why: a compromised edge on the host network
  as root owns the host; a flood that grows memory without a limit takes the whole VM. Test: `docker inspect`
  shows a non-root user, `ReadonlyRootfs: true` and `CapDrop: [ALL]`; writing to `/` inside fails. Source:
  https://docs.docker.com/reference/compose-file/services/ (`read_only`, `cap_drop`, `security_opt`, `mem_limit`),
  verified 2026-11-03.
- [invariant] Every config change is validated by the proxy binary of the image that ships before it is called
  done, locally and again in CI: `caddy validate --config [file] --adapter caddyfile` inside the pinned image, plus
  `caddy list-modules` to assert every module the config uses; `nginx -t` for an nginx hop. A directive or option
  you have not seen in the docs of the installed version, or one moved into another block, counts as unverified
  until validate passes. Why: validate "loads and provisions all of its modules", which `caddy adapt` does not; an
  unknown directive, an option in the wrong block and a module missing from the build all fail only at start, and
  a failed start of the edge takes every site down. Test: remove the rate limit module from the build and CI
  fails; a server option written as a site directive (`log_credentials` inside a site block instead of the global
  `servers` block) fails validate with "unrecognized directive" and exit 1 (Caddy 2.11.7, reproduced 2026-11-05),
  and an unknown nginx directive fails `nginx -t` with "unknown directive". Source:
  https://caddyserver.com/docs/command-line, https://caddyserver.com/docs/caddyfile/options (`servers`,
  `log_credentials`), https://nginx.org/en/docs/switches.html (`-t`), verified 2026-11-05.
- [default] Two edges in separate failure domains, active and passive behind a floating address or both behind
  DNS, with a health check that tests real serving and treats a check timeout as a failure; roll out one edge at a
  time, passive first. Trade-off: a second machine and a failover component to maintain. Deviate only with an ADR
  that names this trade-off. Test: stop and separately freeze (`SIGSTOP`) the active edge; traffic moves within the
  stated RTO both times. Source: reproducible with the test above; failure-domain rules in `high-availability`.

## Procedure

1. Gate: find the config that is actually deployed (trace the rollout), not a copy in another directory.
2. Walk the rules: on-demand TLS, headers and client IP, origin protection, caching, the edge container.
3. Load the reference that matches the change.
4. Validate in the pinned image (`caddy validate --adapter caddyfile`, `caddy list-modules`, `nginx -t` for nginx
   hops) after every edit, not once at the end. Then start the edge container with its production settings
   (`container-images`: read-only, tmpfs owned by its user, dropped capabilities) and test with `curl -sI` against
   it or a staging edge: redirects, canonical, cache headers, 429 page, ask responses.
5. Report the diff and the test results. Roll out passive first; do not apply from this skill.

## Traps

- The ask secret as a query parameter, which then shows up in every access log line of the app.
- An ask endpoint that returns 200 when its cache or database is down.
- `interval` and `burst` left in the config as the only issuance limit.
- A rate limit block commented out because nobody checked whether the module is in the image.
- An ingress that reports `X-Forwarded-Proto: http` to the app, found only when search results show `http://`.
- A cached 429 or 503 page that replaces the last good copy.
- A binary with file capabilities in an image whose capabilities are all dropped: it can fail to start. Test the
  final image with the final security settings.
- A health check script that times out and is skipped, so a frozen edge keeps the floating address.
- A config reviewed only by reading it. Global options, server options and site directives look alike in a
  Caddyfile, and only validate tells which block accepts which.

## Done when

- The ask endpoint is private, fails closed, has no secret in its URL, and is throttled and cached.
- All edges share certificate storage, and served certificates are monitored from outside.
- Forwarded headers are trusted only from listed ranges; redirects and canonicals are `https` without a port.
- Rate limits answer 429 with `no-store`; public pages have `stale-if-error`.
- The edge runs non-root, read-only, with dropped capabilities and a memory limit.
- The last config edit passed `caddy validate` (or `nginx -t`) in the shipped image, with the output quoted; CI
  repeats it, and failover between two edges was tested.

## References

- [references/on-demand-tls.md](references/on-demand-tls.md): load when building or reviewing the ask endpoint,
  the issuance limits, shared storage or wildcard certificates.
- [references/edge-config.md](references/edge-config.md): load when writing the Caddyfile for headers, rate limits,
  caching and error pages, or the container and CI setup.

## Sources

- https://caddyserver.com/docs/automatic-https: on-demand TLS restriction, ask endpoint, shared storage, verified
  2026-11-03.
- https://caddyserver.com/docs/caddyfile/options: `on_demand_tls`, `trusted_proxies`, `client_ip_headers`,
  `trusted_proxies_strict`, `admin off`, verified 2026-11-03.
- https://caddyserver.com/docs/caddyfile/directives/reverse_proxy: forwarded headers, health checks,
  `lb_try_duration`, verified 2026-11-03.
- https://caddyserver.com/docs/command-line: `validate`, `adapt`, `list-modules`, verified 2026-11-03 and
  2026-11-05.
- https://nginx.org/en/docs/switches.html: `nginx -t` tests the configuration, verified 2026-11-05.
- https://github.com/mholt/caddy-ratelimit: rate limit module, verified 2026-11-03.
- https://www.rfc-editor.org/rfc/rfc5861.html: `stale-while-revalidate`, `stale-if-error`, verified 2026-11-03.
- https://nginx.org/en/docs/http/ngx_http_core_module.html and
  https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/: redirect and forwarded
  header settings, verified 2026-11-03.
- https://docs.docker.com/reference/compose-file/services/: container hardening options, verified 2026-11-03.
Pliki w paczce (3)
  • SKILL.md 15 KB
  • references/edge-config.md 4 KB
  • references/on-demand-tls.md 3 KB

Wersje

W bazie nie ma innych skilli o nazwie edge-proxy-tls.

Migawka bazy z 13.11.2026 · wersja paczki a8b1b677b990 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100caddy
    Opisuje Caddy v2 jako reverse proxy z automatycznym HTTPS: składnię Caddyfile, dyrektywy, TLS, wyzwania DNS i zarządzanie przez API.
  • 90reverse-proxy-tls
    Konfiguruje i diagnozuje reverse proxy oraz HTTPS dla Caddy, Nginx i Traefik, sprawdzając ścieżkę od krawędzi do aplikacji.
  • 100tls-reverse-proxy-build
    Buduje utwardzony reverse proxy TLS w nginx, Caddy lub HAProxy i sprawdza go przez nginx -t, openssl oraz testssl.sh.
  • 100caddy
    Wspiera pracę z serwerem Caddy: automatyczne HTTPS, konfiguracja Caddyfile, reverse proxy i równoważenie obciążenia.
  • 100caddy-automatic-https-web-server
    Konfiguruje lekki, wydajny serwer Caddy z automatycznym TLS od Let's Encrypt dla stron i usług.
  • 100vault-eso-tls-certificate-governance
    Zarządza automatyzacją certyfikatów TLS w HashiCorp Vault, External Secrets Operator i bramie Caddy lub Ingress: rotacja i wdrożenia GitOps.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.