| name | ecs-security |
| description | Security and compliance guidance for Amazon ECS — "ECS was unable to assume the role", task role vs execution role, iam:PassRole, confused-deputy aws:SourceArn trust, Fargate vs EC2 shared responsibility, injecting Secrets Manager/SSM secrets (trailing-colon JSON-key gotcha), readonlyRootFilesystem / non-root / drop capabilities, ECS Exec governance, security-group-per-task, VPC endpoint policies, GuardDuty ECS Runtime Monitoring, ECR Inspector scanning, image signing, Fargate FIPS, or PCI/HIPAA/FedRAMP. Walks a discovery-driven 7-layer stack plus the AWS-canonical baseline and a 30/60/90 roadmap. Trigger even if "compliance" is never said — any ECS hardening, task-trust fix, or secrets-injection qualifies. Skip for EKS/Kubernetes (eks-security), GenAI/GPU security (ecs-genai), App Runner/Lambda, auditing a live estate's operational posture (ecs-operation-review — "audit my ECS security posture" matches both), or account-level security with no ECS angle. |
ECS Security & Compliance
End-to-end, opinionated security and compliance guidance for Amazon ECS, structured as a 7-layer stack plus a compliance-regime cross-cutting view. This skill is discovery-driven — the right hardening stack is a function of (launch type × compliance regime × workload sensitivity × audit timeline × team skill × network topology × operational-overhead tolerance). The single biggest ECS-specific variable is launch type (Fargate vs EC2 vs Managed Instances vs ECS Anywhere), because it moves the shared-responsibility line and changes which controls are even available. Skipping discovery makes the recommendation wrong about half the time.
The AWS-published foundation for every recommendation is the ECS Best Practices: Security guide (task & container security, network security, IAM roles) and the ECS security documentation set (IAM, shared-responsibility, Fargate FIPS, infrastructure security). For "which launch/deployment model should I use" (non-security) use ecs-architect; for auditing a live estate's operational posture use ecs-operation-review.
The accuracy bar (non-negotiable for this skill). Compliance is the one domain where customers validate every claim against an auditor. Compliance status changes over time — always defer to the live AWS Services in Scope page before quoting program coverage in any customer-facing document; the ECS-specific pointer is Compliance validation for Amazon ECS. Never state a cryptographic-module status, FedRAMP boundary, or certification you cannot cite to an AWS-published source. When you can't ground a claim, say so — do not synthesize.
When to Use This Skill
Activate when the user wants to:
- Fix the #1 recurring ECS error — "ECS was unable to assume the role …" (task/execution-role trust misconfiguration)
- Get the task role vs task execution role vs container instance role vs infrastructure role distinction right, and least-privilege each one
- Add confused-deputy protection (
aws:SourceArn / aws:SourceAccount) to a task-role trust policy, or scope iam:PassRole
- Understand the Fargate vs EC2 vs Managed Instances shared-responsibility split for a security/audit conversation
- Inject secrets from Secrets Manager / SSM Parameter Store into a task definition (and dodge the trailing-colon JSON-key gotcha)
- Harden containers —
readonlyRootFilesystem, non-root user, privileged: false, drop Linux capabilities, distroless images
- Isolate the network —
awsvpc security-group-per-task, private subnets, VPC endpoints for ECR/S3/Secrets Manager/CloudWatch
- Add runtime detection (GuardDuty ECS Runtime Monitoring + Extended Threat Detection) and image supply-chain controls (ECR enhanced scanning, AWS Signer + Notation signing)
- Prepare an ECS workload for a PCI-DSS / HIPAA / FedRAMP / SOC 2 / ISO audit, or turn on Fargate FIPS
Don't use this skill for:
- EKS / Kubernetes container security (RBAC, Pod Identity/IRSA, PSA, NetworkPolicy, kube-bench) →
eks-security
- GenAI / GPU / ML-workload security specifically (model-artifact provenance, GPU-node compliance) →
ecs-genai (or eks-genai on EKS)
- AWS App Runner / Lambda / Batch — different services with different security models
- AWS account-level / org-wide security with no ECS-specific angle (SCPs, SSO, org GuardDuty) → Security guidance, not this skill
- Choosing a launch/deployment model with no security driver (→
ecs-architect), auditing live operational posture (→ ecs-operation-review), or discovery/inventory of an estate (→ ecs-recon, once available)
Discovery First — the Required Questions
Do NOT recommend a hardening stack before answering these. The single most common mistake is prescribing controls without confirming the launch type — a Fargate answer and an ECS-on-EC2 answer differ at Layers 1, 3, 5, and 6. The first four answers determine ~80% of the recommendation.
- Launch type(s)? AWS Fargate / ECS on EC2 / ECS Managed Instances / ECS Anywhere (external) / mixed. (This is the ECS-specific first question — it sets the shared-responsibility line.)
- Compliance regime(s)? None / SOC 2 / HIPAA / PCI-DSS / FedRAMP Moderate / FedRAMP High / GDPR / ISO 27001 / NIST 800-53/171 / IL4-IL5 — rank primary/secondary if multiple.
- Workload sensitivity? Public / internal / PII / PHI (HIPAA) / cardholder data (PCI) / federal.
- Audit timeline? None / <3 mo (urgent) / 3-6 mo / 6-12 mo / continuous.
- Network topology? Public subnets + IGW / private subnets + NAT / fully private + VPC endpoints; single vs multi-account; multi-region; GovCloud.
- Secrets & config posture? Plaintext env vars (bad) / Secrets Manager / SSM Parameter Store / hybrid; rotation requirement.
- Team ECS/security skill? Low / moderate / high / mixed.
- Current security tooling baseline? None / AWS-native / third-party CNAPP / OSS / hybrid.
Full required + recommended question set, adoption-challenge archetypes, and the response framework: references/engagement-and-response.md.
The 7-Layer Security & Compliance Stack
Walk the layers bottom-up on a first engagement; each layer's controls compound on the previous. The AWS-canonical default column assumes a new commercial Fargate workload — the launch-type substitutions are noted per layer.
| Layer | Focus | AWS-canonical default | Reference |
|---|
| 1 — Compute / Shared Responsibility | Who secures what; node OS | Fargate (AWS manages OS/kernel/runtime — smallest customer surface); on EC2/Managed Instances, harden the container instance (ECS-optimized AL2023 or Bottlerocket, patch cadence, IMDSv2, lock down IMDS from tasks) | shared-responsibility.md |
| 2 — Identity & Access | Role trust & least privilege | Task role (app → AWS) + task execution role (agent → ECR/logs/secrets) as separate least-privileged roles; confused-deputy aws:SourceArn/aws:SourceAccount on trust policies; scoped iam:PassRole | identity-and-access.md |
| 3 — Task & Container Hardening | What a container may do | readonlyRootFilesystem: true + non-root user + privileged: false + drop Linux capabilities + distroless image + CPU/memory limits | task-container-hardening.md |
| 4 — Image Supply Chain | Trust what you run | ECR Enhanced Scanning (Amazon Inspector) + immutable tags + AWS Signer + Notation signing + CMK-encrypted repos | image-supply-chain.md |
| 5 — Network Isolation | What a task may reach | awsvpc mode + security-group-per-service + private subnets + VPC endpoints (ECR api/dkr, S3 gateway, Secrets Manager, CloudWatch Logs) + no public IPs | |
The AWS-canonical reference stack for a new commercial Fargate service: Fargate (L1) + separate least-privileged task role & execution role with confused-deputy-scoped trust (L2) + readonlyRootFilesystem/non-root/privileged:false/dropped-capabilities/distroless (L3) + ECR Enhanced Scanning + immutable tags + AWS Signer signing (L4) + awsvpc SG-per-service in private subnets + VPC endpoints (L5) + GuardDuty ECS Runtime Monitoring + Extended Threat Detection (L6) + CloudTrail + Container Insights + Config + Security Hub ECS controls (L7). The ECS-on-EC2 path adds container-instance OS hardening + IMDS lockdown at L1/L5 and loses Fargate's per-task kernel isolation (see the boundary note below). Managed Instances loses GuardDuty Runtime Monitoring support at L6.
Cross-cutting concerns (span every layer, aligned to the AWS ECS Best Practices security areas): secrets & data encryption (Secrets Manager/SSM injection, the JSON-key syntax, at-rest/in-transit, EBS volume & ephemeral-storage encryption, Fargate FIPS) → encryption-and-secrets.md; incident response & forensics (the runbook when a detection fires) → incident-response-and-forensics.md; and the shared-responsibility model itself → shared-responsibility.md. Each reference includes its per-layer shared-responsibility split.
The one boundary you must state precisely (verified, verbatim from AWS docs): "Containers are not a security boundary and the use of task IAM roles does not change this." On Fargate, each task has its own isolation boundary — no shared kernel, CPU, memory, or ENI with another task. On EC2, ECS Managed Instances, and ECS Anywhere there is no task isolation: a compromised container can reach credentials for co-located tasks, the container instance role, and instance metadata (IMDS). For strict workload isolation, use Fargate; on EC2, lock down IMDS access from tasks. Source: ECS task IAM role.
Compliance-Regime Scope (cross-cutting)
Amazon ECS and AWS Fargate are broadly in scope for AWS's major compliance programs (PCI-DSS, HIPAA eligibility, SOC 1/2/3, ISO, FedRAMP, and more) — but program scope changes over time and is not the same across services or Regions, so this skill does not quote a fixed ECS scope table from memory. Instead, defer to the authoritative live pages every time: AWS Services in Scope by Compliance Program and the ECS-specific Compliance validation for Amazon ECS. Per-regime nuance, the verify-against-live-page discipline, and worked HIPAA/PCI/FedRAMP scenarios: references/compliance-regimes.md.
Always include the disclaimer in customer-facing output: "Compliance status changes over time — verify on the live AWS Services in Scope page before quoting program coverage." And precision matters: ECS/Fargate are HIPAA-eligible (with a signed BAA), not "HIPAA-compliant"; Fargate FIPS 140-3 is GovCloud (US) only, LINUX + X86_64 + platform version 1.4.0+, and off by default (verified: Fargate FIPS-140).
Security Baseline (non-negotiable — every recommendation includes this)
Regardless of regime, every ECS hardening recommendation MUST include:
- Separate task role and task execution role, each least-privileged — never one over-broad shared role, never static AWS keys in the container
- Confused-deputy protection (
aws:SourceArn scoped to your account via the all-clusters wildcard arn:aws:ecs:region:acct:*, plus aws:SourceAccount) on the ecs-tasks.amazonaws.com trust policy for cross-service roles — cluster/task scoping in aws:SourceArn is not supported (task IAM role)
- Scoped
iam:PassRole — grant it only for the specific execution/task/infrastructure role ARNs, never Resource: "*"
- Secrets via Secrets Manager or SSM Parameter Store injected through the task definition
secrets block (execution role needs the retrieval permission) — never plaintext in environment env vars
- Container hardening —
readonlyRootFilesystem: true, non-root user, privileged: false (privileged is unsettable on Fargate anyway), drop unneeded Linux capabilities (on Fargate the only addable capability is SYS_PTRACE), distroless/minimal base image, explicit CPU/memory limits, immutable ECR tags. Note the ECS Exec interplay: readonlyRootFilesystem: true is incompatible with ECS Exec (the SSM agent must write to the container filesystem), and ECS Exec sessions run as root regardless of the container user — govern Exec accordingly (below). Windows: readonlyRootFilesystem, user, and Linux-capability drops don't apply — see the Layer 3/6 caveats
awsvpc network mode with a least-privilege security group per service, tasks in private subnets, no auto-assigned public IPs, and VPC endpoints for ECR (api + dkr), S3 (gateway, for layers), Secrets Manager, and CloudWatch Logs- ECR Enhanced Scanning (Amazon Inspector) on all production repositories; image signing (AWS Signer + Notation) where the regime requires provenance
- GuardDuty ECS Runtime Monitoring (Fargate + EC2 — not Managed Instances, Windows, or ECS Anywhere; see Layer 3/6 caveats) + (automatic, no additional cost atop paid GuardDuty); route findings to . On a — the GuardDuty-created VPC endpoint plus the S3 managed prefix list (for the agent/sidecar image) — or detection silently goes dark
Hardening Roadmap (30 / 60 / 90)
- Days 1-30 (baseline, non-disruptive): enable CloudTrail (if not already) + GuardDuty ECS Runtime Monitoring + ECR Enhanced Scanning + Security Hub (AWS FSBP + the ECS controls) + Container Insights. Establish the baseline and the finding inventory. Caveat: enabling Runtime Monitoring does not retroactively cover already-running Fargate tasks — the security sidecar is injected only at task start, so existing tasks stay uncovered until they are restarted/redeployed (plan a rolling redeploy). On a locked-down network, also allow the GuardDuty telemetry path (its VPC endpoint + the S3 managed prefix list) or coverage reports "Unhealthy."
- Days 31-60 (identity + secrets): split any over-broad shared role into least-privileged task role + execution role; add confused-deputy conditions to trust policies; scope
iam:PassRole; migrate plaintext env-var secrets to Secrets Manager/SSM injection; lock down IMDS from tasks on EC2.
- Days 61-90 (workload + network + image): roll out
readonlyRootFilesystem/non-root/privileged:false/dropped-capabilities (test first — read-only rootfs breaks apps that expect to write); move tasks to private subnets + VPC endpoints + SG-per-service; enable immutable tags + image signing; enable the applicable AWS Config conformance pack (HIPAA/PCI/NIST/FedRAMP) + validate Security Hub against it (Audit Manager existing setups only — maintenance mode; see compliance-accelerators.md).
- Greenfield: deploy the full 7-layer stack in the task definition and service at creation, not retrofitted.
Top Guardrails (the high-cost mistakes)
- Don't recommend a stack before confirming launch type — the #1 ECS mistake; Fargate vs EC2 vs Managed Instances changes Layers 1, 3, 5, and 6.
- Don't confuse the task role with the execution role. The execution role grants the ECS/Fargate agent permission to pull images, write logs, and fetch secrets at launch; the task role vends credentials to your application code at runtime. Putting app permissions on the execution role (or ECR/secrets permissions only on the task role) is a classic misconfiguration.
- Don't leave the "ECS was unable to assume the role" error unresolved by guessing — it is almost always (a) a missing/incorrect trust policy (
Principal: ecs-tasks.amazonaws.com + sts:AssumeRole), (b) a deleted/renamed role, or (c) an over-restrictive confused-deputy condition. See identity-and-access.md and re:Post: ECS unable to assume role.
- Don't forget the trailing colons in a secret ARN. The full
valueFrom syntax is arn:aws:secretsmanager:region:acct:secret:name:json-key:version-stage:version-id; the last three fields are optional but if you omit them you must still include the colons to select defaults. A single JSON key requires Fargate platform version 1.4.0+ (Linux) or EC2 agent 1.37.0+. Source: Pass Secrets Manager secrets via env vars.
- Don't claim GuardDuty Runtime Monitoring covers Managed Instances — it covers Fargate and EC2 container instances; Runtime Monitoring does not support ECS Managed Instances (verified). Injected env-var secrets are also not auto-rotated — the container gets the value only at start; use SSM Parameter Store programmatic retrieval or force a new deployment to refresh.
- Don't treat containers as a security boundary on EC2 — no task isolation there; a compromised container can reach co-located tasks' credentials, the instance role, and IMDS. Use Fargate for strict isolation, or lock down IMDS.
- Don't promise "HIPAA-compliant" — ECS/Fargate are HIPAA-eligible; a signed BAA is required and the customer owns workload-level controls.
- Don't claim Fargate FIPS in commercial Regions — Fargate FIPS 140-3 is and must be explicitly enabled.
Escalation
Create a SpecReq / escalate for: first-time certification on a mission-critical regulated workload; XXL+ segment; FedRAMP High / GovCloud; IL4/IL5; ECS Anywhere inside a compliance boundary (customer owns the on-prem host entirely); multi-tenant SaaS with cross-tenant PHI/cardholder/federal isolation on shared EC2 container instances; customer-vs-auditor disagreement on AWS-managed-control acceptability; or any claim you cannot ground. Full criteria: references/engagement-and-response.md.
How to Use the References
Progressive disclosure — the essentials are above; load a reference only when the task needs that depth:
| Reference | Load when the task is about… |
|---|
| engagement-and-response.md | Full discovery question set, adoption-challenge archetypes, response framework, escalation criteria |
| shared-responsibility.md | Layer 1 — Fargate vs EC2 vs Managed Instances vs Anywhere responsibility split; container-instance AMI hardening (AL2023/Bottlerocket); IMDS lockdown; patch cadence |
| identity-and-access.md | Layer 2 — task vs execution vs instance vs infrastructure roles; the "unable to assume the role" error; confused-deputy trust (all-clusters wildcard); iam:PassRole; credential delivery; ECS Exec governance; operator-side/cluster-admin IAM (ABAC, MFA) |
| task-container-hardening.md | Layer 3 — readonlyRootFilesystem, non-root user, privileged, Linux capabilities, dockerSecurityOptions, distroless, CPU/memory limits, Security Hub ECS controls |
| image-supply-chain.md | Layer 4 — ECR Enhanced (Inspector) vs basic scanning, immutable tags, CMK-encrypted repos, AWS Signer + Notation signing, third-party scanners |
| network-isolation.md | Layer 5 — awsvpc mode, SG-per-task/service, private subnets, VPC endpoints (incl. ssmmessages/kms for Exec, ECS control-plane endpoints on EC2), VPC Flow Logs, WAF/Shield, multi-tenancy isolation, ingress via ALB/NLB, egress control |
| runtime-security.md | Layer 6 — GuardDuty ECS Runtime Monitoring (Fargate/EC2 coverage, the Managed-Instances exclusion), Extended Threat Detection, Security Hub, third-party CNAPP |
| audit-logging.md |
Sources
