imperva-demo/docs/DECISIONS.md

# 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 <crt> <key>`.

**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.