Skip to content

ADR-0006: Security Architecture Controls for the BookingZone Platform

Status: Accepted Date: 2026-05-06 Deciders: Architecture team Impacted Repos: reservation-api-server, bz-api-server, admin-web-app, venuplus-app, customer-web-app

Context

A vendor-supplied "Current Security Plan" (May 2026) proposed a generic AWS security architecture: CloudFront, WAF, Fail2Ban, GuardDuty, Inspector, CloudWatch, Secrets Manager — sized for a stack of EC2 instances running Node.js, PHP, and MongoDB.

That stack does not match BookingZone:

  • bz-api-server runs on AWS Lambda + API Gateway + DynamoDB.
  • reservation-api-server runs on ECS Fargate behind ALB + RDS MariaDB + ElastiCache Redis + EFS, deployed via CodePipeline.
  • Frontends (admin-web-app, venuplus-app) are hosted on AWS Amplify. customer-web-app and bz-customer-web are on other CDN providers (TBD).
  • Authentication is on Amazon Cognito (customer + admin pools).

We have no public EC2 instances anywhere, no SSH endpoints, and no self-managed databases. As a result, several PDF recommendations (Fail2Ban, "hide EC2 IP behind CloudFront") are inapplicable, while several controls critical to our stack (Cognito drift detection, image signing, audit logging for compliance) are absent from the plan.

We also lack a written security architecture: there is no canonical document that lists the controls we run, why, and where they live. The May 3, 2026 Cognito incident (AutoVerifiedAttributes silently wiped, ~3-day signup outage) was made worse by this absence — there was no single document that named drift detection as a missing control.

Decision

Adopt a stack-appropriate, defense-in-depth control matrix documented in specs/SYS-002-security-architecture/spec.md as the canonical security architecture for the BookingZone platform. The matrix:

  1. Maps every recommended control to one of: Implemented, Higher-priority gap, Lower-priority gap, Suggestion (someday), or Not applicable to our stack.
  2. Replaces the vendor PDF as the source of truth.
  3. Is reviewed at least quarterly; new controls land via PR with explicit ADR amendment.

We adopt the following as Higher-priority gaps to file as Issues now (P1 in our priority scale):

  • Bot protection on customer-facing form / cart endpoints — direct response to the 2026-05-05 GHL-pollution incident (~6,000 fake contacts in 5 minutes via the abandon-cart flow); add a bot challenge, IP rate-limit, and GHL-side contact-creation throttle.
  • Cloudflare evaluation spike — front-of-stack DDoS + Bot Management; layer in front of AWS WAF or stay AWS-only and expand WAF; documented decision + POC.
  • Expand WAF managed rule sets to all customer endpoints — today's WAF protects only payment/booking paths.
  • CloudTrail organization-wide audit trail — compliance baseline (SOC 2, PCI); ~30 min to enable.
  • GuardDuty enable + Slack/email alerting in both AWS accounts — free, threat detection; ~1 hr.
  • AWS Backup plan + tested restore covering RDS, EFS, and DynamoDB in prod — data loss prevention with documented RTO/RPO; ~1 day.
  • Enable Inspector v2 + ECR image immutability — continuous CVE scanning; tag tamper-resistance; ~1 hr enable + initial triage.
  • Standardize Dependabot + GitHub secret scanning across reservation-api-server, admin-web-app, venuplus-app — supply-chain hygiene.

We accept the following as Lower-priority gaps to track in the spec (P2 — file as Issues but not blocking):

  • Frontend security headers on Amplify (CSP, HSTS, X-Content-Type-Options, X-Frame-Options) for admin-web-app and venuplus-app. Especially valuable on the customer-facing payment UI when those repos move to Amplify.
  • Cognito pool drift detector + synthetic signup canary (the underlying May 3 incident has been remediated manually; automated detection remains desirable as recurrence prevention).
  • VPC Endpoints for SSM / ECR / S3 / Secrets Manager / RDS.
  • AWS Config + CIS conformance pack.
  • CloudFront in front of the ECS ALB.
  • Cognito Advanced Security Features (compromised-credentials check, adaptive auth).
  • AWS SSO / Identity Center for engineer access (replace long-lived IAM users).
  • IAM Access Analyzer + automated least-privilege review.
  • CodeQL / Semgrep PR check across the 3 active repos.

We accept the following as Suggestions documented but not scheduled (P3):

  • SAST in CI (CodeQL / Semgrep), DAST scheduled scans (OWASP ZAP).
  • IaC scanning (cdk-nag, checkov) as a PR check.
  • SBOM generation per release.
  • Multi-region disaster-recovery plan (or explicit "single-region acceptable" decision).
  • Frontend security headers (CSP, HSTS, X-Content-Type-Options) on Amplify.
  • PCI-DSS SAQ-A self-assessment (we route cards but never store PAN).
  • WAF IP reputation + ASN blocking rules.
  • Documented incident-response runbook with on-call rotation.

We explicitly reject as not applicable to our stack:

  • Fail2Ban — there are no SSH endpoints; the equivalent control is IAM + Session Manager + GuardDuty, already adopted.
  • "Hide EC2 IP via CloudFront" as a primary motive — there are no public EC2 IPs.

Consequences

Positive

  • Single canonical answer to "what's our security architecture?" — replaces ad-hoc questions.
  • May 3-class incidents are addressed by named controls, not tribal knowledge.
  • New AWS accounts (e.g., FinCo) inherit a known baseline.
  • The spec doubles as compliance evidence for SOC 2 / PCI conversations.

Negative / Trade-offs

  • One more document to maintain. Mitigation: quarterly review cadence is explicit.
  • Some Tier-2 / Tier-3 items will sit unaddressed for quarters. Accepted, because the document forces an explicit "deferred" decision rather than a silent gap.

Risks / Mitigations

  • Risk: spec becomes stale and false. Mitigation: each control row has an "evidence link" pointing at code (CDK file, workflow, IAM policy) — drift becomes obvious at review time.
  • Risk: lower-priority items quietly never ship. Mitigation: every quarterly review must explicitly re-rank or close suggestions, not just defer.

Alternatives Considered

  • Adopt the vendor PDF as-is — rejected. ~60% of its controls don't apply and it omits controls we actually need (Cognito drift, audit log, image scanning).
  • Per-repo security docs — rejected. Security spans repos; per-repo documents diverge and miss cross-cutting controls (Cognito, IAM, network).
  • Defer until a customer asks — rejected. The May 3 incident already demonstrated the cost of the documentation gap.

Implementation Notes

  • The control matrix lives in specs/SYS-002-security-architecture/spec.md.
  • Tier-0 / Higher-priority items get GitHub Issues (P1 priority) tied to Project #1, mapped back to this ADR.
  • Tier-2 / Tier-3 items remain as suggestions in the spec; they may graduate to Issues at any quarterly review.
  • All future security-relevant infrastructure changes must update the spec in the same PR.

References

  • specs/SYS-002-security-architecture/spec.md (the living matrix)
  • system-constitution.md (overall principles)
  • reservation-api-server/aws-infra/DEPLOYMENT.md (current ECS deployment)
  • reservation-api-server/.cursor/rules/aws-destructive-update-apis.mdc (May 3 Cognito incident write-up)
  • bz-api-server/serverless/resources/waf.yml (legacy WAF)
  • reservation-api-server/aws-infra/cdk/lib/waf-stack.ts (new WAF)
  • Vendor input: "Current Security Plan" PDF (May 2026)