Merge pull request #11 from aws-samples/feat/enforce-network-policy

feat(security): enforce per-tenant NetworkPolicy via Amazon VPC CNI (ADR-0008)

Author: snese

.gitignore

@@ -18,3 +18,4 @@ cdk/cdk.json.usw2
 cdk/cdk.json.use1
 cdk/cdk-us-east-1.json
 screenshots/
+.playwright-mcp/

README.md

@@ -139,13 +139,32 @@ Sign up at `https://<your-domain>/auth/` with an email matching your `allowedEma
 | Signup | AWS WAF Bot Control (opt-in) + email domain restriction + rate limiting |
 | Network | Internet-facing ALB with CF-only SG (pl-82a045eb) + AWS WAF + HTTPS |
 | Auth | Amazon Cognito signup + local token auth + 3-layer origin protection |
-| Tenant | Namespace isolation + NetworkPolicy + ABAC |
+| Tenant | Namespace isolation + NetworkPolicy (enforced via VPC CNI, see below) + ABAC |
 | Secrets | exec SecretRef -- fetched on-demand, never persisted |
 | LLM | Amazon Bedrock via Pod Identity -- zero API keys |
 | Cost | Per-tenant monthly budget with per-model pricing |
 | Data | PVC persists across scale-to-zero (Amazon EFS, multi-AZ) |
 | Audit | CloudTrail + Amazon S3 + Athena + Amazon EKS control plane logging |
 
+### Security model
+
+Each isolation layer buys something specific — and honestly does not buy
+something else. The per-tenant NetworkPolicy is **actually enforced**: the
+stack enables the Amazon VPC CNI network policy agent (off by default on
+Amazon EKS), giving tenants an HTTPS-only egress posture (443 to public,
+Pod Identity/IMDS/DNS allowed, cross-tenant and VPC-internal blocked).
+Exfiltration over permitted HTTPS remains out of scope for L3/L4 policy —
+the upgrade path (AWS Network Firewall FQDN filtering, DNS-aware CNI) is
+documented as a non-goal. Note also that enforcement runs in *standard mode*:
+a brand-new pod is default-allow for the brief window before its policies
+attach, so NetworkPolicy is not a startup-time exfiltration boundary (see
+ADR-0008 for strict mode).
+
+Details and trade-offs:
+
+- [ADR-0007 — gVisor runtime tier + runtime tier extension contract](docs/adr/0007-gvisor-runtime-tier.md)
+- [ADR-0008 — Enforced per-tenant egress control](docs/adr/0008-enforce-network-policy-egress.md)
+
 ## Cost
 
 | Resource | 3 tenants | 100 tenants |

cdk/lib/eks-cluster-stack.ts

@@ -164,13 +164,25 @@ export class EksClusterStack extends cdk.Stack {
     });
 
     // ── Other EKS Add-ons (no special IAM needed) ───────────────────────────
-    for (const addonName of ['eks-pod-identity-agent', 'vpc-cni', 'coredns', 'kube-proxy']) {
+    for (const addonName of ['eks-pod-identity-agent', 'coredns', 'kube-proxy']) {
       new eks.CfnAddon(this, addonName.replace(/-/g, ''), {
         clusterName: cluster.clusterName,
         addonName,
       });
     }
 
+    // VPC CNI with NetworkPolicy enforcement enabled (ADR-0008). Without this,
+    // the per-tenant NetworkPolicy objects shipped by the Helm chart are stored
+    // by the API server but NOT enforced — the Amazon VPC CNI network policy agent is
+    // off by default on Amazon EKS.
+    // https://docs.aws.amazon.com/eks/latest/userguide/cni-network-policy.html
+    new eks.CfnAddon(this, 'vpccni', {
+      clusterName: cluster.clusterName,
+      addonName: 'vpc-cni',
+      configurationValues: JSON.stringify({ enableNetworkPolicy: 'true' }),
+      resolveConflicts: 'OVERWRITE',
+    });
+
     // ── CloudWatch Container Insights ─────────────────────────────────────
     const cwObsRole = new iam.Role(this, 'CwObservabilityRole', {
       assumedBy: new iam.ServicePrincipal('pods.eks.amazonaws.com'),

docs/adr/0008-enforce-network-policy-egress.md

@@ -0,0 +1,90 @@
+# ADR-0008: Enforce per-tenant egress control via Amazon VPC CNI NetworkPolicy
+
+- **Status:** Accepted
+- **Date:** 2026-07-14
+- **Deciders:** HC Lo (hclo)
+- **Depends on:** [ADR-0007](0007-gvisor-runtime-tier.md)
+
+## Context
+
+For multi-tenant agent workloads, the highest-leverage isolation control is not
+the container runtime — it is **egress control**. Credential exfiltration and
+lateral movement use perfectly normal syscalls that any runtime (runc, gVisor,
+microVM) permits; only the network layer can stop them (see the mechanism table
+in ADR-0007).
+
+The Helm chart has always shipped a per-tenant `NetworkPolicy`
+(`networkPolicy.enabled: true` by default) that is effectively default-deny:
+
+- **Egress allowed:** DNS, Amazon EKS Pod Identity Agent (`169.254.170.23`), IMDS,
+  TCP 443 to public IPs (except `10.0.0.0/8`), same-namespace pods.
+- **Everything else denied:** cross-tenant traffic, VPC-internal addresses,
+  non-443 protocols.
+
+**However, on Amazon EKS these objects were stored but not enforced.** The Amazon VPC
+CNI's NetworkPolicy support is disabled by default and must be enabled
+explicitly on the add-on; nothing in this stack did so. The policy was
+decorative.
+
+## Decision
+
+1. Enable NetworkPolicy enforcement on the `vpc-cni` managed add-on via
+   `configurationValues: {"enableNetworkPolicy": "true"}` (CDK).
+2. Keep the existing per-tenant policy as-is (HTTPS-only egress posture).
+3. Treat FQDN-level egress filtering as a documented **non-goal** with an
+   upgrade path (below), not a platform feature.
+
+## What this changes for agent behavior
+
+| Tenant/agent behavior | After enforcement |
+|-----------------------|-------------------|
+| HTTPS APIs and sites (Amazon Bedrock, AWS Secrets Manager, ghcr.io, npm, web tools over 443) | Unchanged |
+| Pod Identity, IMDS, DNS, same-namespace | Unchanged (explicit allows) |
+| Amazon EFS mounts | Unchanged (NFS mount runs in the node network namespace, not the pod's) |
+| Plain-HTTP (`http://`, port 80) external sites | **Blocked** |
+| Non-443 protocols (SSH/git :22, custom :8080, SMTP) | **Blocked** |
+| VPC-internal / cross-tenant addresses (`10.0.0.0/8`) | **Blocked** |
+
+## Residual risk (stated honestly)
+
+Egress to **any** public host on TCP 443 remains allowed. An agent that is
+prompt-injected into exfiltrating data over HTTPS is *not* stopped by this
+policy. Kubernetes `NetworkPolicy` is L3/L4 and cannot express hostnames.
+
+## Upgrade path (non-goals for this sample)
+
+- **AWS Network Firewall** — VPC-level FQDN/SNI allowlisting; cluster-wide
+  granularity, no chart changes.
+- **CNI with DNS-aware policy (e.g. Cilium)** — per-tenant FQDN allowlists;
+  requires replacing the CNI, too heavy for this sample.
+- **Egress proxy (allowlist + audit)** — strongest auditability; requires the
+  agent tool-chain to honor proxy configuration.
+
+## Options considered
+
+- **Enforce existing policy (chosen):** one add-on setting; per-tenant
+  granularity; zero new components.
+- **AWS Network Firewall now:** rejected for the sample — cost + VPC redesign,
+  and cluster-level (not per-tenant) granularity.
+- **Do nothing:** rejected — shipping an unenforced NetworkPolicy misleads
+  adopters about the actual security posture.
+
+## Consequences
+
+**Positive**
+- The documented tenant isolation model ("Namespace isolation + NetworkPolicy +
+  ABAC") becomes true.
+- Blocks metadata-service and cross-tenant lateral movement paths.
+
+**Negative / caveats**
+- Agent tools that need port-80 or non-443 endpoints require an explicit
+  per-tenant policy exception.
+- Adopters whose VPC CIDR is outside `10.0.0.0/8` should adjust the `except`
+  block to their VPC CIDR (documented in `values.yaml`).
+- Enforcement behavior at pod startup is *standard mode* (default-allow until
+  policies attach); see the EKS docs if strict mode is required.
+
+## References
+
+- https://docs.aws.amazon.com/eks/latest/userguide/cni-network-policy.html
+- https://docs.aws.amazon.com/eks/latest/userguide/cni-network-policy-configure.html

helm/charts/openclaw-platform/values.yaml

@@ -43,6 +43,12 @@ ingress:
     alb.ingress.kubernetes.io/scheme: internal
     alb.ingress.kubernetes.io/target-type: ip
 
+# Per-tenant egress control (ADR-0008). Enforced only when the cluster enables
+# the Amazon VPC CNI network policy agent (this stack's CDK does). Posture: HTTPS-only
+# egress — DNS / Pod Identity / IMDS / TCP 443-to-public allowed; plain HTTP
+# (:80), non-443 protocols, and VPC-internal (10.0.0.0/8) blocked.
+# If your VPC CIDR is not within 10.0.0.0/8, adjust the egress `except` block
+# in templates/networkpolicy.yaml to your VPC CIDR.
 networkPolicy:
   enabled: true