# API Gateway Control Guide

Use this reference when the review scope includes API Gateway REST, HTTP, or WebSocket APIs, custom domains, authorizers, throttling, quotas, stages, resource policies, or API Gateway logging.

## What people get wrong

The lazy story is:

> API Gateway is managed, so the API edge is safe by default.

Wrong. API Gateway removes server management; it does not remove API abuse, auth, quota, logging, or data-exposure risk.

Common bad assumptions:

- A public API is acceptable because the backend is private.
- JWT authorizer exists, so authorization is solved.
- Account-level throttling is enough for per-tenant abuse.
- CloudWatch metrics exist, so audit evidence exists.
- CORS is a browser concern, not a security review item.
- Stage variables, access logs, and mapping templates cannot leak sensitive data.

## Officially grounded controls

Current AWS documentation points API Gateway reviewers toward these control families:

- IAM authorization, Lambda/JWT/Cognito authorizers, and resource policies for access control.
- CloudWatch metrics/logs and access logging for observability.
- CloudTrail for API management-plane audit activity.
- AWS Config and Security Hub CSPM for configuration/security evidence.
- Throttling and quotas to limit request rates and protect downstream systems.

Treat those as required evidence categories, not optional polish.

## Non-negotiable review checks

### 1. Identify API type before giving guidance

REST API, HTTP API, and WebSocket API do not expose the same controls or operational surfaces. Do not give one-size-fits-all recommendations.

Capture:

- API type and stage
- custom domain and TLS policy
- integration type and backend
- authorizer type
- resource policy, if any
- usage plan/API key design, if any
- throttling/quota settings
- access-log format and destination

### 2. Split authentication from authorization

An authorizer answers “who is this?” or “is this token acceptable?”. It does not automatically prove per-route, per-tenant, or object-level authorization.

Look for:

- route/method authorization coverage
- claims-to-permission mapping
- tenant isolation checks
- explicit deny paths
- unauthenticated OPTIONS/CORS behavior
- bypasses through alternate stages/domains

### 3. Treat throttling as layered protection

Review all relevant layers:

- account-level throttles
- stage/method throttles
- usage plans and quotas
- WAF rate-based rules
- downstream service capacity
- retry behavior from clients and integrations

A single throttle setting is not an abuse-control strategy.

### 4. Logs must be useful and safe

Access logs should answer who/what/when/outcome without leaking secrets.

Check for:

- request ID / extended request ID
- principal or anonymized tenant identifier
- route/method/status/integration latency
- WAF decision correlation where applicable
- no bearer tokens, cookies, API keys, passwords, or PII payloads in logs
- retention and KMS controls for log groups

## Minimum safe workflow

1. Classify API type, stage, custom domain, and backend integration.
2. Enumerate all public routes and unauthenticated routes.
3. Verify authorizer, resource policy, and route authorization coverage.
4. Verify throttles, quotas, usage plans, and downstream capacity assumptions.
5. Inspect access-log settings and log redaction posture.
6. Check CloudTrail/Config/Security Hub evidence for management-plane and config drift.
7. Identify rollback: stage variable, canary, deployment, DNS, or previous deployment ID.

## Verification targets

Use read-only evidence when available:

- API Gateway API/stage/domain/authorizer/resource-policy descriptions
- route/method authorization settings
- stage access-log settings
- usage plan and API key attachment where used
- CloudWatch metrics: 4xx, 5xx, latency, integration latency, throttles
- CloudTrail events for recent API/stage/domain changes

## When to push back

Push back if the design says:

- “public for now, auth later”
- “API keys are authentication”
- “JWT means authorization is done”
- “we do not need throttling because traffic is low”
- “we log full requests for debugging”
- “rollback is redeploying main”

# CloudFront Origin Protection Guide

Use this reference when the review scope includes CloudFront distributions, origins, cache behaviors, origin access control, TLS, custom headers, cache keys, origin request policies, or distribution rollback.

## What people get wrong

The naive story is:

> CloudFront is in front, so the origin is protected.

Wrong. CloudFront only protects the origin if the origin is configured to reject direct access and the cache/origin policies do not leak or amplify risk.

Common bad assumptions:

- S3 origin is private because CloudFront uses it.
- Origin access identity and origin access control are interchangeable.
- Viewer HTTPS is enough; origin HTTPS does not matter.
- Forwarding all headers/cookies/query strings is safer because it is “complete”.
- Cache invalidation is the rollback plan.
- Custom origin headers are secrets.

## Officially grounded controls

Current AWS docs ground these CloudFront controls:

- Origin Access Control for restricting S3 origins, including migration from legacy OAI and SSE-KMS permission considerations.
- HTTPS viewer/origin policies for encrypted transport.
- Custom origin headers for origin request shaping, with documented header restrictions.
- Cache behavior, cache key, and origin request policy choices that affect correctness, privacy, and cost.
- AWS WAF association for edge filtering and rule enforcement.

## Non-negotiable review checks

### 1. Prove the origin cannot be bypassed

For S3 origins, verify bucket policy allows the CloudFront distribution/OAC path and denies unintended direct access.

For custom origins, verify one or more controls:

- origin only reachable from expected networks
- secret header is not the only control unless risk accepted
- ALB/security group/origin firewall rules restrict direct access
- origin TLS certificate and hostname behavior are correct

### 2. Cache keys are security boundaries

Cache policies can leak tenant/user-specific responses if identity-bearing inputs are omitted from the cache key.

Check:

- Authorization/cookie/query/header forwarding
- whether authenticated responses are cached
- error response caching
- compression and content negotiation
- cache behavior path precedence

### 3. TLS and domain posture are part of rollback

Capture:

- viewer protocol policy
- minimum TLS protocol
- certificate scope and expiration
- alternate domain names
- DNS cutover/rollback path

### 4. Origin request controls can create data exposure

Forwarding too much can expose cookies and auth headers to origins that do not need them. Forwarding too little can break authorization or cache correctness.

## Minimum safe workflow

1. Map viewer domain -> distribution -> behavior -> origin -> backend.
2. Identify every origin and whether direct access is blocked.
3. Review cache and origin request policies for sensitive variance.
4. Verify TLS policy, certificate, and DNS ownership.
5. Verify WAF association and logging posture.
6. Define rollback: previous distribution config, DNS change, origin failover, or behavior revert.

## Verification targets

Use read-only evidence when available:

- distribution config and status
- cache behaviors and origin request/cache policies
- OAC/OAI config and S3 bucket policy
- origin protocol policy and custom headers
- WAF web ACL association
- standard or real-time log delivery
- CloudWatch metrics and CloudFront 4xx/5xx/error-rate signals

## When to push back

Push back if the design says:

- “the S3 bucket is public but hidden behind CloudFront”
- “we forward everything to avoid bugs”
- “custom header is our only origin protection”
- “we can invalidate if something goes wrong”
- “CloudFront is global so regional evidence is irrelevant” without explaining global-control-plane implications

# API and Edge Observability / Incident Playbook

Use this reference for API Gateway, CloudFront, WAF, Shield, or ALB edge incidents involving 4xx/5xx spikes, latency, throttling, false positives, cache poisoning, origin failures, bot traffic, or unexpected cost.

## What people get wrong

The naive story is:

> We have dashboards, so we can debug the edge.

Wrong. Edge incidents cross services. If request IDs, logs, WAF decisions, cache behavior, and origin metrics cannot be correlated, dashboards become theater.

Common bad assumptions:

- 4xx means client fault.
- 5xx means origin fault.
- WAF blocks are always attacks.
- CloudFront cache hit ratio is always good when high.
- API Gateway throttles prove abuse rather than mis-sized quotas.
- Cost spikes are separate from reliability incidents.

## Evidence to collect first

Capture the time window and compare against a clean baseline.

Minimum evidence set:

- affected hostnames, paths, methods, status codes
- CloudFront distribution and cache behavior
- API Gateway API/stage/route, if applicable
- WAF web ACL/rule/action/labels, if applicable
- origin target and origin health
- recent deployments, WAF changes, DNS/certificate changes, or cache policy changes
- customer impact and business priority

## Failure-mode map

### 4xx spike

Check:

- authorizer failures
- resource policy denies
- WAF blocks/challenges/CAPTCHA
- CORS/preflight failures
- missing routes or base-path mappings
- signed URL/cookie failures
- request size/header validation

### 5xx spike

Check:

- origin health and target group status
- API Gateway integration errors/timeouts
- Lambda/backend errors
- CloudFront origin connection attempts/timeouts
- certificate/TLS origin mismatch
- DNS/origin failover behavior

### Latency spike

Check:

- cache hit ratio and origin latency
- API Gateway integration latency vs total latency
- backend saturation
- WAF inspection overhead from expensive rules
- regional vs global path differences

### False-positive WAF incident

Check:

- rule ID/rule group/label
- sampled requests/logs
- recent managed rule updates or overrides
- path-specific exception options
- count-mode rollback

## Minimum safe incident workflow

1. State the exact time window and affected edge path.
2. Identify whether the symptom begins at viewer, edge, WAF, API Gateway, or origin.
3. Correlate metrics and logs across services.
4. Identify the smallest reversible mitigation.
5. Prefer count/allow exception scoped by path/header/method over disabling a whole managed rule group.
6. Record rollback and post-incident hardening actions.

## Verification targets

Use read-only evidence when available:

- CloudFront standard/real-time logs or distribution metrics
- API Gateway access logs and execution metrics
- WAF logs/sampled requests and rule metrics
- CloudWatch alarms and metric math dashboards
- origin target health and backend logs
- CloudTrail events for recent configuration changes
- Cost Explorer / usage evidence if request volume or logging cost spiked

## When to push back

Push back if the user asks to:

- disable the entire WAF to fix one false positive
- increase throttles without checking origin capacity
- invalidate all cache paths as a generic rollback
- ignore missing logs and “just infer” root cause
- call the incident resolved without post-mitigation metrics

# Official sources

Use this reference only when you need source grounding for AWS service behavior or the detailed source list.

## AWS documentation

Use these as starting points, not as proof of the user's live AWS state:

### API Gateway

- API Gateway security best practices
  https://docs.aws.amazon.com/apigateway/latest/developerguide/security-best-practices.html
- API Gateway throttling and quotas
  https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html

### CloudFront

- Restrict access to an Amazon S3 origin with CloudFront OAC
  https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html
- Add custom headers to origin requests
  https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html
- Require HTTPS between CloudFront and an S3 origin
  https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https-cloudfront-to-s3-origin.html
- Use AWS WAF protections with CloudFront
  https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-awswaf.html

### AWS WAF / Shield

- How AWS WAF works
  https://docs.aws.amazon.com/waf/latest/developerguide/how-aws-waf-works.html
- AWS Managed Rules for AWS WAF
  https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups.html
- Best practices for anti-DDoS
  https://docs.aws.amazon.com/waf/latest/developerguide/waf-anti-ddos-best-practices.html
- How AWS Shield and Shield Advanced work
  https://docs.aws.amazon.com/waf/latest/developerguide/ddos-overview.html
- Automatic application-layer DDoS mitigation with Shield Advanced
  https://docs.aws.amazon.com/waf/latest/developerguide/ddos-automatic-app-layer-response.html

## Grounding rule

Official documentation explains AWS service behavior. It does not prove the user's current account, Region, quota, resource configuration, IAM boundary, pricing, or operational state. Prefer read-only AWS MCP or CLI evidence, repository evidence, or sanitized user-provided evidence for current-state claims.

## Current MCP/documentation refresh (2026-06-02)

Service facts from official docs:

- API Gateway security best-practice guidance points reviewers to IAM, CloudWatch, CloudTrail, AWS Config, Security Hub CSPM, and JWT authorizers as API security controls.
- API Gateway throttling and quotas are separate control layers; account/stage/method throttles, usage plans, and downstream capacity must be reviewed together.
- CloudFront OAC is the current S3-origin protection path; legacy OAI exists but is not the preferred new pattern. OAC/S3 bucket policy and SSE-KMS permissions must be reviewed together.
- CloudFront custom origin headers can help origin request shaping, but AWS documents headers CloudFront cannot add and separate guidance for forwarding `Authorization`; do not treat custom headers as a complete security boundary.
- AWS WAF web ACLs use rules, rule groups, labels, WCUs, dashboards, bot analysis, and metrics; AWS Managed Rules should be tested before production blocking.
- AWS anti-DDoS guidance calls for baseline traffic patterns, CloudWatch metrics, and staging tests; Shield Standard is automatic, while Shield Advanced adds additional protections for eligible resources.

Sampled live evidence:

- Read-only regional availability sampling reported `isAvailableIn` for Amazon API Gateway, Amazon CloudFront, AWS WAF, and AWS Shield in `us-east-1`, `us-west-2`, `eu-west-1`, and `ap-southeast-1`.
- Read-only API availability sampling reported `WAFV2+GetWebACL`, `WAFV2+ListRuleGroups`, and `CloudWatch+DescribeAlarms` as `isAvailableIn` in those sampled regions.
- `CloudFront+GetDistribution` sampled as `isAvailableIn` in `us-east-1` and `us-west-2`, and `Not Found` in `eu-west-1` and `ap-southeast-1`; treat CloudFront API evidence as global/service-specific rather than normal regional workload proof.

Stale or missing guidance corrected:

- The prior reference set was too generic and lacked component-specific guidance for API Gateway, CloudFront, WAF/Shield, and cross-service incident triage.
- It did not call out API type differences, JWT/authZ separation, cache-key sensitivity, OAC vs OAI, WAF count-mode limits, managed-rule staging, Shield Advanced scope, or evidence correlation across edge services.
- It did not provide verification targets or pushback criteria comparable to the stronger AgentCore references.

Review implications:

- Public edge exposure is not acceptable without evidence for authN/authZ, throttling/quotas, TLS, origin protection, WAF/Shield posture, logging, alarms, and rollback.
- CloudFront distribution state, cache behavior, origin policy, WAF decisions, API Gateway stages/routes, and quotas must come from repo/live evidence, not documentation alone.
- Treat sampled live evidence as regional/API availability only; it does not prove the user's resources are configured safely.

# Safety checklist

Use this reference before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting recommendations.

## Non-negotiables

- Never ask users to paste secrets, access keys, session tokens, private keys, customer identifiers, or sensitive account data into chat.
- Use read-only AWS MCP or read-only AWS CLI evidence for live state when available; otherwise use repository evidence, sanitized user evidence, or official documentation and label the evidence level.
- Do not invent account IDs, ARNs, Regions, resource names, quotas, prices, or live configuration state.
- Require explicit user approval before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting actions.
- Use current official AWS documentation for service behavior when the answer depends on AWS service details.
- Keep remediation least-privilege, reversible, and scoped to the requested workload or account boundary.

## Stress checks

- What can expose data?
- What can escalate privilege?
- What can break production or block rollback?
- What can create unbounded cost?
- What compliance or audit evidence is missing?
- What rollback or validation path is unproven?

## Evidence labels

Use `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`. Documentation alone never proves the user's live AWS state.

# WAF, Shield, and Abuse Controls Guide

Use this reference when the review scope includes AWS WAF web ACLs, managed rules, custom rules, rate-based rules, Bot Control, Shield Advanced, Firewall Manager, labels, logging, or abuse/DDoS posture.

## What people get wrong

The lazy story is:

> We attached WAF, so abuse is handled.

Wrong. A web ACL can be ineffective, too broad, too expensive, noisy, or dangerous if rules are untested or exclusions are careless.

Common bad assumptions:

- Managed rule groups can be enabled straight to block in production.
- Count mode means protected.
- Rate-based rules work without baseline traffic knowledge.
- Bot Control labels are automatically safe to block on.
- WAF logs are optional because CloudWatch metrics exist.
- Shield Advanced means no app-layer DDoS planning is needed.

## Officially grounded controls

Current AWS docs ground these WAF/Shield controls:

- Web ACLs, rules, rule groups, labels, WCUs, dashboards, and bot analysis.
- AWS Managed Rules with explicit guidance to test rule groups before production deployment.
- Rate, CAPTCHA/challenge, SQLi/XSS-style request inspection, and label-based handling.
- Anti-DDoS best practices: establish traffic baselines, monitor CloudWatch metrics, and test in staging.
- Shield Standard is automatically included; Shield Advanced adds additional DDoS protections for eligible resources.

## Non-negotiable review checks

### 1. Identify scope and attachment

Capture whether the web ACL is for CloudFront/global or regional resources such as ALB/API Gateway/AppSync.

Verify:

- associated resource(s)
- default action
- rule priority order
- managed/custom rule groups
- WCU headroom
- count/block/challenge/CAPTCHA actions
- labels and label match rules

### 2. Test managed rules before blocking

Require count-mode observation or staged rollout for new or changed managed rule groups unless there is an active incident requiring emergency block.

### 3. Rate limits need baselines

Rate-based rules should be tied to:

- normal request-rate baseline
- attack threshold
- aggregation key
- exception list
- false-positive rollback
- CloudWatch/WAF-log validation

### 4. Logging is evidence, not decoration

WAF logs are needed to explain blocked/allowed traffic, labels, rule matches, false positives, and cost/noise tradeoffs.

## Minimum safe workflow

1. Map protected resources and web ACL scope.
2. Inspect default action and rule priority.
3. Review managed rule groups, custom rules, labels, WCU, and overrides.
4. Check rate-based rules against baseline traffic.
5. Verify logging, metrics, dashboards, and alarm coverage.
6. Define false-positive rollback and emergency block procedure.
7. If Shield Advanced is claimed, verify protected resources and response/escalation path.

## Verification targets

Use read-only evidence when available:

- WAFv2 web ACL, rules, rule groups, and logging configuration
- CloudFront/API Gateway/ALB association
- WAF sampled requests and log destinations
- CloudWatch metrics: allowed, blocked, counted, challenged, CAPTCHA, rule matches
- Shield Advanced protection status where claimed
- Firewall Manager policy if multi-account governance is in scope

## When to push back

Push back if the design says:

- “turn on every managed rule in block mode”
- “we do not need WAF logs”
- “Count mode means protected”
- “one global rate limit fits all endpoints”
- “allowlist our office IPs broadly”
- “Shield Advanced means WAF tuning is unnecessary”

# Workflow and output contract

Use this reference only when performing the full review, implementation guidance, incident triage, or production-readiness pass.

## Review domains

Check these areas before giving a verdict:
- Public entry points, domains, TLS, DNS, authN/authZ, origin type, cache behavior, and routing path
- API Gateway throttling/quotas/logging, CloudFront OAC/OAI, WAF rules/actions/count mode, Shield, and origin protection
- Sensitive logging, CORS, headers, cache keys, invalidation, rate limits, bot/abuse controls, and error responses
- Metrics, access logs, WAF logs, CloudFront logs, alarms, rollback, staged deployment, and blast radius

## Safe workflow

1. **Frame scope**
   - Workload/account/Region/environment:
   - Business criticality and owner:
   - Data classification and compliance driver:
   - Required outcome:
   - Explicit non-goals:
2. **Collect evidence**
   - Prefer read-only AWS MCP or read-only AWS CLI evidence for current-state claims when available.
   - Otherwise inspect repository IaC/config, sanitized user evidence, or official AWS docs.
   - Label each finding as `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`.
3. **Stress-test risk**
   - What can expose data?
   - What can escalate privilege?
   - What can break production or block rollback?
   - What can create unbounded cost?
   - What evidence is missing?
4. **Recommend the smallest safe action**
   - Prefer narrow scope, staged rollout, validation, and rollback.
   - If the safest action is to stop and gather evidence, say that plainly.

## Output contract

Return this structure:
```markdown
# AWS API Edge Delivery Review: <scope>
## Executive verdict
- Status: READY / READY WITH RISKS / NOT READY / NEEDS EVIDENCE
- Biggest risk:
- Evidence level:
## Scope and assumptions
- Confirmed:
- Unknown:
- Out of scope:
## Findings
| Severity | Finding | Evidence | Why it matters | Minimum safe action |
|---|---|---|---|---|
## Recommended actions
1. <action> — owner: <owner>, validation: <check>, rollback: <rollback>
## Validation
- Commands or checks:
- Expected result:
## Residual risk
- <risk or explicit none>
```