# Design Decisions & Rationale An ADR-style log of the choices made in this project, *why* they were made, and what was rejected. Several of these were reversed mid-stream — the reversals are kept here on purpose so nobody re-walks a dead end. --- ## D1 — WAF terminates client TLS; origin does not do public HTTPS **Decision:** Imperva handles all public-facing TLS. The origin never runs ACME / Let's Encrypt and never serves a publicly-trusted cert. **Why:** The whole point of the lab is that Imperva is the edge. Having the origin also try to obtain public certs is redundant, and on this locked-down host ACME would fail anyway (egress is restricted and ingress is Imperva-only). Keeping cert management at the edge is simpler and matches the intended topology. --- ## D2 — First attempt: plain-HTTP origin (REVERSED) **Decision (later reversed):** Have Caddy serve only plain HTTP on `:80` and let Imperva connect to the origin over HTTP; `auto_https off`. **Why it was chosen:** The user's initial goal was "forward https/http traffic from the WAF without Caddy doing SSL." The cleanest literal reading is: Imperva terminates TLS, origin speaks plain HTTP, Caddy needs no cert at all. **Why it was reversed:** The user then wanted a certificate they could upload to / associate with Imperva (origin re-encryption). Plain HTTP has no cert to produce, so we moved to a self-signed HTTPS origin (D5). **Artifacts from this phase worth remembering:** - `https://35.203.147.44/` returning `PR_CONNECT_RESET_ERROR` was *expected* here — nothing was listening on 443. That reset is not a bug; it's the correct result of hitting a port with no listener. Test HTTP origins with `curl -v http://localhost/` from the host, and the real path via the hostname. --- ## D3 — Single catch-all site block in the Caddyfile **Decision:** Exactly one site block (`:443`, or `:80` in the HTTP phase). No separate hostname block. **Why:** With `auto_https off`, a hostname block like `flytoouter.space { }` no longer routes to 443 automatically — it binds the same plain port as an explicit `:80`/`:443` block. Two blocks fighting over one port produces: ``` Error: adapting config using caddyfile: ambiguous site definition: :80 ``` This actually happened (a leftover domain block from the pre-WAF config remained in the file). The container crash-looped, spamming the error hundreds of times — that volume is just the restart policy retrying, not hundreds of distinct problems. **Rejected:** keeping host-specific blocks. If host-based routing is ever wanted (e.g. rejecting requests whose Host isn't `flytoouter.space` as origin hardening), it goes *inside* the single block as a `@host` matcher, never as a second site block. --- ## D4 — `handle` not `handle_path` for `/api/*` **Decision:** Route the API with `handle /api/* { reverse_proxy … }`. **Why:** `handle_path` strips the matched prefix; `handle` preserves it. The backend's routes are defined under `/api/v1/...`, so the prefix must survive the proxy hop. --- ## D5 — Self-signed cert on the origin, generated with OpenSSL (not Caddy internal CA) **Decision:** Generate the origin cert with `openssl` (self-signed, RSA 2048, 3650 days, SAN = DNS + IP) and hand the files to Caddy via `tls `. **Why OpenSSL over Caddy's `tls internal`:** `tls internal` mints a cert via Caddy's internal CA and buries it in `/data/caddy/pki/...`, which is awkward to export. The lab needs the cert *as a file on disk* — to upload to / associate with Imperva and to have explicit control over the SAN. OpenSSL gives that in one command. **Why self-signed is acceptable here:** Only Imperva connects to the origin. Browsers only ever see Imperva's edge cert (D1). So the self-signed cert causes zero visitor-facing warnings. The critical rule: **the self-signed cert belongs only on the re-encryption leg, never on the edge/visitor leg.** **SAN includes both DNS and IP** so Imperva matches regardless of whether it addresses the origin by hostname or by `35.203.147.44`. --- ## D6 — Debugging the "cert not found" start failure **Symptom:** `caddy validate` reported `open /etc/caddy/certs/origin.crt: no such file or directory`, and curl to `:443` reset. **Root cause & rule:** The config was fine; the cert file wasn't visible *inside the container*. Two common causes on rootless Podman: 1. **Tilde didn't expand** in `-v ~/imperva-proxy/certs:...`, creating an empty anonymous mount. Fix: use absolute paths (`/home/matt/...`). 2. Stale `:Z` SELinux relabel state from an earlier container. Fix: recreate the container. The TLS reset was a *symptom* of Caddy refusing to start the HTTPS server, not an independent TLS problem. Always read the `validate` / `podman logs` output first. --- ## D7 — Three OWASP attacks for the demo: SQLi, Reflected XSS, Path Traversal **Decision:** Demo exactly these three. **Why these three:** Imperva blocks all three with **default, out-of-the-box signatures** (no custom rules needed), and each surfaces as a **different, clearly labeled event** in the portal (SQL Injection / Cross-Site Scripting / Illegal Resource Access). Three distinct classifications reads as comprehensive coverage rather than three flavors of one thing. **Why credential stuffing / rate-limiting was left OUT of the demo set:** It needs a **custom rate policy** configured in Imperva, not a signature match. It doesn't produce the clean one-payload-one-block moment the other three do. Kept as an optional "bonus" for later if we want to showcase custom rules. --- ## D8 — Deploy via `podman save | ssh podman load`, not a container registry **Decision:** Build locally, pipe the image over the existing SSH connection into the host's Podman, then swap the container via the `gcp-lab` connection alias. **Why:** Zero new infrastructure. All the pieces already exist (SSH key, locked ingress, remote Podman socket, connection alias). A registry (GCP Artifact Registry or GHCR) would add credential management on both ends and, for Artifact Registry, IAM wiring (service account + `artifactregistry.reader`) that's easy to get subtly wrong. **Trade-off accepted:** `podman save` ships **every layer every time**, so each deploy moves the full image even for a one-line change (~20–40s on this lab). The registry's layer-caching win only pays off at high deploy frequency, which a demo lab isn't. **Upgrade path:** If this ever becomes team-touched or high-frequency, migrating to Artifact Registry is clean — only the *ship* step changes (`push`/`pull` instead of `save | ssh load`); the rest of `deploy.sh` is unchanged. --- ## D9 — Build locally, never on the host **Decision:** All image builds happen on the local workstation. **Why:** The `e2-micro` (shared-core, burstable) doesn't have the memory to run the Vue multi-stage build (npm install + build) reliably, even with the swapfile. Building locally and shipping the finished image sidesteps OOM kills entirely. --- ## D10 — Frontend screens map 1:1 to attacks **Decision:** Give the flight-booking SPA four screens, each a natural home for one attack, so the demo feels like poking a real product rather than hitting raw endpoints: - Passenger/admin lookup → SQLi (`/api/v1/users?q=`) - Flight search results → Reflected XSS (`/api/v1/search?term=`) - Boarding-pass download → Path Traversal (`/api/v1/download?file=`) - Login → existing endpoint, kept as the credential-stuffing bonus **Why:** A believable UI makes the "exploitable without the WAF, blocked with it" narrative land better in a live demo than curling endpoints.