This document describes the security architecture, threat model, and controls implemented in webhook-relay. It is intended for security review and production deployment approval.

1. System Overview
2. Threat Model
3. Security Controls
4. Network Architecture
5. Authentication & Authorization
6. Input Validation
7. Rate Limiting
8. Audit Logging
9. Credential Management
10. Container Security
11. IAM Principle of Least Privilege
12. Residual Risks

webhook-relay is a stateless HTTP service that receives webhook payloads from external sources (e.g., Power Automate) and writes them to a GCS bucket. It is deployed as a Google Cloud Run Service with VPC network isolation.

Data flow:

External Source (Power Automate)
    │
    │ HTTPS POST /ingest/gcs/{path}
    │ Header: X-API-Key
    │ Body: email file (binary)
    │
    ▼
┌────────────────────────────────┐
│ Cloud Run Service              │
│ (webhook-relay)                │
│                                │
│ Internet ingress (HTTPS/TLS)   │
│     ↓                          │
│ Middleware chain:              │
│   1. Audit log                 │
│   2. Security headers          │
│   3. Request size limit        │
│   4. Per-IP rate limit         │
│   5. API key authentication    │
│   6. HTTP method enforcement   │
│     ↓                          │
│ Path validation                │
│     ↓                          │
│ GCS write (via VPC egress)     │
│                                │
│ VPC Direct Egress ─────────────┼──┐
└────────────────────────────────┘  │
                                    │
┌───────────────────────────────────┴──┐
│ VPC: webhook-relay-vpc               │
│ ┌──────────────────────────────────┐ │
│ │ Subnet: 10.100.0.0/28           │ │
│ │ Private Google Access: ON       │ │
│ │                                  │ │
│ │ Egress → Google APIs only       │ │
│ │ (no internet egress)            │ │
│ └──────────────────────────────────┘ │
│                                      │
│ Firewall: deny-all-ingress          │
└──────────────────────────────────────┘

The service does NOT:

• Store any data locally (stateless)
• Read from GCS (write-only)
• Execute or interpret received files
• Maintain sessions or cookies
• Expose admin interfaces

┌─────────────────────────────────────────────┐
│ webhook-relay-vpc                           │
│                                             │
│  Subnet: webhook-relay-subnet               │
│  CIDR:   10.100.0.0/28 (16 IPs)            │
│  Private Google Access: ENABLED             │
│                                             │
│  Firewall Rules:                            │
│    webhook-relay-vpc-deny-all-ingress       │
│    Direction: INGRESS                       │
│    Action: DENY ALL                         │
│    Source: 0.0.0.0/0                        │
│    Priority: 65534                          │
│                                             │
│  Egress: Google APIs only                   │
│    (via Private Google Access)              │
│    No internet egress possible              │
└─────────────────────────────────────────────┘

1. No internet egress: Even if the application is compromised, it cannot make outbound connections to arbitrary internet hosts. The only reachable destinations are Google APIs (GCS, Secret Manager, Cloud Logging) via Private Google Access.

2. Deny-all ingress firewall: The VPC firewall blocks all ingress traffic to the subnet. Cloud Run handles its own ingress independently of VPC firewalls, so the webhook endpoint remains reachable, but no other resources in the VPC can be accessed.

3. Minimal subnet: /28 CIDR (16 IPs) minimizes the blast radius. No other services share this network.

Cloud Run ingress is set to all because the service must receive traffic from Power Automate (Microsoft-owned IP ranges that are not predictable). Authentication is handled at the application layer (API key), not at the network layer.

• Mechanism: X-API-Key header checked against a stored secret
• Comparison: crypto/subtle.ConstantTimeCompare (timing-safe)
• Key storage: GCP Secret Manager, injected as environment variable
• Key generation: openssl rand -hex 32 (256-bit entropy)
• Key rotation: Create a new secret version, update Cloud Run, revoke old version

Power Automate's HTTP connector supports custom headers but has limited OAuth2 capabilities (especially without Entra ID app registration). An API key in a custom header is the most compatible authentication mechanism.

Standard string comparison (==) leaks information via timing differences: an attacker can determine how many bytes of the key are correct by measuring response latency. crypto/subtle.ConstantTimeCompare takes constant time regardless of which byte differs, preventing timing side-channel attacks.

All object paths are validated before reaching any backend:

• Default: 25 MB
• Enforced via http.MaxBytesReader which returns 413 if exceeded
• Prevents memory exhaustion and storage abuse

• Only POST is accepted on /ingest/ routes
• All other methods return 405 Method Not Allowed
• GET /healthz is the only non-POST endpoint (unauthenticated, returns {"status":"ok"})

Per-IP token bucket rate limiter using golang.org/x/time/rate:

1. X-Forwarded-For header (set by Cloud Run, trusted)
2. Leftmost IP taken (original client)
3. Falls back to RemoteAddr if header absent

Visitor entries are evicted after 3 minutes of inactivity to prevent memory growth from scanning traffic.

Every request is logged as structured JSON to stdout, which Cloud Run forwards to Cloud Logging:

{
  "timestamp": "2026-04-09T10:00:00Z",
  "method": "POST",
  "path": "/ingest/gcs/inbox/alert.eml",
  "remote_addr": "10.0.0.1:1234",
  "x_forwarded_for": "203.0.113.5",
  "status": 201,
  "duration_ms": 45,
  "bytes_in": 102400,
  "user_agent": "PowerAutomate/1.0"
}

• API key values (neither valid nor invalid)
• Request body content
• Response body content
• Internal error details (returned as generic "backend write failed")

The service uses Application Default Credentials (ADC) on Cloud Run, which resolves to the attached service account. No JSON key files are created, stored, or deployed.

The service account has the minimum permissions required:

Notable exclusions:

• No storage.objectViewer — the service cannot read existing objects
• No storage.objectAdmin — the service cannot delete objects
• No run.invoker — not needed (the service handles its own auth)
• No iam.serviceAccountUser — cannot impersonate other accounts