ECS Reconnaissance
Discover everything about an ECS environment. Run this skill to gather comprehensive context about clusters, services, and their tasks before making any decisions, changes, or recommendations. Standalone (run-task) and scheduled (EventBridge) tasks are not discovered — discovery enumerates workloads via list-services.
When to Use This Skill
Run this skill when the user:
- Asks about their ECS environment ("what clusters do I have?", "describe my ECS setup")
- Wants to understand their service configuration ("what launch type?", "how is it deployed?")
- Plans to modify a service and needs current-state context first
- Asks to document or review their ECS resources
- Needs task definition details, scaling policies, or networking config
- Mentions an ECS cluster or service and seems to need context
Also trigger this skill when:
- Another workflow needs ECS environment information as input
- User mentions ECS and needs discovery before recommendations
- You need to understand the ECS setup before giving guidance
Do NOT use this skill for:
- Cost scoring or efficiency analysis — belongs to
ecs-cost-intelligence(once available) - Security auditing or compliance scoring — belongs to
ecs-security - Best-practices evaluation or maturity ratings — belongs to
ecs-operation-review - Migration planning (replatform/refactor onto ECS) — belongs to
ecs-modernize(once available) - Amazon EKS requests — belongs to
eks-recon; this skill discovers ECS only - Creating or modifying ECS resources (this is read-only)
- Producing architecture design documents or diagrams
Access Model — READ-ONLY
This skill is strictly read-only. It CAN issue read-only calls (aws ecs describe-*/list-*, application-autoscaling describe-*, elbv2 describe-*, cloudformation describe-*/list-*, codepipeline list-*/get-*, deploy list-*/get-*, sts get-caller-identity, logs describe-*) to discover estate state, and CAN write the report file to the workspace. It CANNOT mutate any resource (no create, update, delete, register, deregister, run-task, or scale operations). If a detection would require a write, record the field as unknown instead.
Prerequisites
MCP Tools (Optional Supplement)
The Amazon ECS MCP server exists in preview (ECS MCP server docs), but its tools are diagnostics-shaped — all require a cluster_name and none enumerate clusters — so it cannot drive discovery. CLI Mode is the primary path for this skill. If the ECS MCP server is configured, its read tools may supplement drill-down diagnostics; it is in preview and subject to change — do not depend on it.
Required for CLI Mode (Primary)
| Tool | Required For |
|---|---|
aws CLI | All ECS discovery (aws ecs, aws application-autoscaling, aws elbv2, aws cloudformation) |
Verifying Access
Before running reconnaissance, verify AWS credentials are available:
bashaws sts get-caller-identity
IMPORTANT: Never give up after checking only environment variables. AWS credentials can come from ~/.aws/credentials, ~/.aws/config, instance metadata, or ECS task roles — none of which appear in env | grep AWS_. Always try aws sts get-caller-identity before concluding credentials are unavailable.
Reconnaissance Modes
| Mode | When to Use | What Happens |
|---|---|---|
| Full Recon | First engagement with ECS environment | Runs Overview Scan, then all drill-down modules |
| Selective Recon | Know what you need | Run specific modules (e.g., compute + networking) |
| Targeted Query | Quick answer | "Is this service using Fargate?" |
How to Invoke
Full reconnaissance:
"Run ECS reconnaissance in
us-west-2"
Selective reconnaissance:
"Run ECS recon but only check compute and auto scaling for service
api-prod"
Targeted query:
"What launch type does service
api-produse in clusterproduction?"
Modules and Reference Loading
Load only the references needed for the user's request — this keeps context focused. references/overview.md is always loaded first for the Overview Scan phase; it provides the cluster/service inventory all other modules depend on. For targeted queries, load only the matching row(s); for full recon, load all references.
| Module | Intent / When to Use | Reference File |
|---|---|---|
| Overview | Always loaded first — account-wide inventory of clusters, services, and their tasks (standalone/scheduled tasks not discovered) | overview.md |
| Compute | Capacity providers, launch types, task counts, Fargate vs EC2 | compute.md |
| Task Definitions | Container images, CPU/memory, family and revision | task-definitions.md |
| Deployment | Rolling update, CodeDeploy, circuit breaker, min/max percent | deployment.md |
| Auto Scaling | Scalable targets, target tracking, step scaling policies | autoscaling.md |
| Networking | Network mode, VPC config, load balancers, service connectivity | networking.md |
| Security | Task roles, execution roles, ECS Exec, secrets references | security.md |
| Observability | Log drivers, Container Insights, CloudWatch log groups | observability.md |
| IaC | Terraform, CloudFormation, CDK, Copilot detection | iac.md |
| CI/CD | CodePipeline, CodeDeploy, GitHub Actions, GitLab CI detection | cicd.md |
Quick Detection Reference
CLI Commands (Current Default)
| Detection | CLI Command |
|---|---|
| List clusters | aws ecs list-clusters --region <region> |
| Describe clusters | aws ecs describe-clusters --clusters <name> --include STATISTICS SETTINGS |
| List services | aws ecs list-services --cluster <name> --region <region> |
| Describe services | aws ecs describe-services --cluster <name> --services <svc> --region <region> |
| Describe task definition | aws ecs describe-task-definition --task-definition <arn> --query 'taskDefinition.{family:family,revision:revision,cpu:cpu,memory:memory,networkMode:networkMode,containerDefinitions:containerDefinitions[].{name:name,image:image,cpu:cpu,memory:memory,memoryReservation:memoryReservation,essential:essential}}' (the --query projection excludes containerDefinitions[].environment — plaintext values there may contain credentials) |
| List tags | aws ecs list-tags-for-resource --resource-arn <arn> |
| Auto scaling targets | aws application-autoscaling describe-scalable-targets --service-namespace ecs |
| Auto scaling policies | aws application-autoscaling describe-scaling-policies --service-namespace ecs |
| Load balancer info | aws elbv2 describe-target-groups --target-group-arns <arn> |
Running Reconnaissance
IMPORTANT: Load Reference Files
Before running each module, you MUST read its reference file (e.g.,
references/compute.md). References contain:
- Detection order and rationale
- Edge cases and how to handle them
- CLI commands with example outputs
- Output schema for structured reporting
Skipping references produces shallow results. The main skill provides orchestration; the references provide detection intelligence.
Never reproduce containerDefinitions[].environment values or non-awslogs logConfiguration.options in output or the report — they routinely contain plaintext credentials.
Step 1: Gather Prerequisites
Required: - AWS region (or detect from context/CLI) - AWS credentials (verified via sts get-caller-identity) Optional: - Specific cluster/service to target (default: discover all) - Specific modules to run (default: all) - Output file path (default: .ecs-recon-report.yaml)
Region resolution order:
- User-provided region
AWS_DEFAULT_REGIONorAWS_REGIONenvironment variableaws configure get region- If none available, ask the user
Step 2: Check Tool Availability
CLI Mode is the primary path — the ECS MCP server (preview) offers no cluster-enumeration tools, so discovery always runs on the AWS CLI. If the ECS MCP server is configured, its read tools may optionally supplement drill-down diagnostics; record tool_mode: mixed in that case, otherwise tool_mode: cli (the normal value).
Step 3: Run Overview Scan
Load references/overview.md and execute the Overview Scan:
- List all clusters (paginated — collect all pages)
- List services per cluster (paginated — collect all pages)
- Describe clusters (get task counts, capacity providers, settings)
- Present the overview map to the user
If only one cluster exists, auto-select it for drill-down. If multiple clusters exist, ask the user which to drill into (or run full recon if requested).
Step 4: User Selection
After presenting the overview map:
- If user requested full recon: proceed with all modules on all clusters
- If user picks a specific cluster/service: scope drill-down to that target
- If targeted query: run only the relevant module
Step 5: Run Drill-Down Modules
For each selected module:
- Load the reference file — REQUIRED
- Run detection commands following the reference's guidance:
- Use the CLI commands from the reference (primary path)
- ECS MCP server read tools (if configured) may supplement diagnostics
- If detection is not possible, record as unavailable with reason
- Collect output into report section using the reference's output schema
Execution order: Modules are independent — run them in any order. Each module is self-contained with its own detection commands and output schema.
Step 6: Generate Report
Write report to .ecs-recon-report.yaml and present summary to user.
Summarize facts, not verdicts — this skill must not emit health/quality judgments (that is ecs-operation-review's lane).
Report sensitivity: the report embeds account IDs, subnet/security-group IDs, IAM role ARNs, and secret ARNs. Treat it as sensitive — write it only inside the workspace, and do not commit it (recommend adding .ecs-recon-report.yaml to .gitignore).
Report Generation
The final report follows this YAML schema:
yaml# ECS Reconnaissance Report # Generated: 2026-01-15T10:30:00Z # Account: 123456789012 # Region: us-west-2 # Modules: overview, compute, task_definitions, deployment, autoscaling, networking, security, observability, iac, cicd metadata: account_id: string region: string timestamp: string # ISO 8601 UTC tool_mode: string # "cli" (normal) | "mixed" (ECS MCP server supplemented diagnostics) modules_run: list[string] coverage: regions: list[string] # Regions covered (single-region per run) scope_note: string # "services and their tasks only; standalone (run-task) and scheduled (EventBridge) tasks not discovered" clusters_discovered: int # Clusters found in the Overview Scan clusters_drilled_down: int # Clusters covered by drill-down modules overview: clusters: list[ClusterSummary] # Drill-down sections (present only if module was run) compute: ComputeOutput | UnavailableOutput task_definitions: TaskDefinitionsOutput | UnavailableOutput deployment: DeploymentOutput | UnavailableOutput autoscaling: AutoScalingOutput | UnavailableOutput networking: NetworkingOutput | UnavailableOutput security: SecurityOutput | UnavailableOutput observability: ObservabilityOutput | UnavailableOutput iac: IaCOutput | UnavailableOutput cicd: CICDOutput | UnavailableOutput
UnavailableOutput (for modules that could not complete)
yamlunavailable: true reason: string # Human-readable explanation (e.g., "Access denied on ecs:DescribeServices")
Module-level unavailable: true is reserved for total module failure. Each module's per-service entries may carry error: string | null — per-resource failures are recorded inline on the affected entry and recon continues with the rest.
Example Report
yamlmetadata: account_id: "123456789012" region: us-west-2 timestamp: "2026-01-15T10:30:00Z" tool_mode: cli modules_run: - overview - compute - task_definitions - deployment coverage: regions: - us-west-2 scope_note: "services and their tasks only; standalone (run-task) and scheduled (EventBridge) tasks not discovered" clusters_discovered: 1 clusters_drilled_down: 1 overview: clusters: - name: production arn: arn:aws:ecs:us-west-2:123456789012:cluster/production status: ACTIVE services_count: 3 running_tasks: 12 stopped_tasks: 2 # int | null (null = not collected) capacity_providers: - FARGATE - FARGATE_SPOT services: - name: api-service status: ACTIVE desired_count: 4 running_count: 4 launch_type: not_applicable # capacity provider strategy in use - name: worker-service status: ACTIVE desired_count: 2 running_count: 2 launch_type: FARGATE compute: cluster: name: production capacity_providers: - name: FARGATE type: FARGATE status: ACTIVE auto_scaling_group_arn: null - name: FARGATE_SPOT type: FARGATE_SPOT status: ACTIVE auto_scaling_group_arn: null default_capacity_provider_strategy: - provider: FARGATE weight: 1 base: 1 - provider: FARGATE_SPOT weight: 3 base: 0 services: - name: api-service launch_type: not_applicable capacity_provider_strategy: - provider: FARGATE weight: 1 base: 1 - provider: FARGATE_SPOT weight: 3 base: 0 task_counts: running: 4 desired: 4 pending: 0 - name: worker-service launch_type: FARGATE capacity_provider_strategy: [] task_counts: running: 2 desired: 2 pending: 0 task_definitions: services: - service_name: api-service family: api-service revision: 42 task_cpu: "1024" task_memory: "2048" network_mode: awsvpc containers: - name: api image: 123456789012.dkr.ecr.us-west-2.amazonaws.com/api:v1.5.0 cpu: 896 memory: 1792 memory_reservation: null essential: true - name: envoy image: public.ecr.aws/appmesh/aws-appmesh-envoy:v1.27.0 cpu: 128 memory: 256 memory_reservation: null essential: true deployment: services: - service_name: api-service controller_type: ecs_rolling # ecs_rolling | ecs_blue_green | ecs_linear | ecs_canary | code_deploy | external strategy: ROLLING # ROLLING | BLUE_GREEN | LINEAR | CANARY | null (ECS controller + deploymentConfiguration.strategy decides the ecs_* controller_type; ROLLING or absent strategy -> ecs_rolling) minimum_healthy_percent: 100 maximum_percent: 200 bake_time_in_minutes: null circuit_breaker: enabled: true rollback_enabled: true alarms: alarm_names: [] enable: false rollback: false deployments: - id: ecs-svc/1234567890 status: PRIMARY desired_count: 4 running_count: 4 rollout_state: COMPLETED
Integration with Other Workflows
Cost Intelligence Workflow
The cost intelligence workflow can invoke ecs-recon to gather baseline context:
1. Run ecs-recon modules: overview, compute, autoscaling 2. Extract: - Cluster capacity providers → cost model - Service task counts → utilization baseline - Auto scaling config → scaling efficiency
Security Audit Workflow
The security audit workflow can use ecs-recon for discovery:
1. Run ecs-recon modules: overview, security, networking 2. Extract: - Task roles → IAM analysis input - Secrets references → secrets management audit - Network config → isolation analysis
Migration Workflow
The migration workflow can use ecs-recon to understand existing state:
1. Run ecs-recon modules: all 2. Extract: - Complete environment inventory - IaC tooling → migration tooling decisions - Deployment config → migration strategy input
Sources
Facts verified 2026-07-14 against the URLs below.
- Amazon ECS MCP server (preview) — tool surface and preview status
- API_Service — service fields (launch type, capacity provider strategy, deployment controller)
- API_DeploymentConfiguration — strategy, bake time, circuit breaker, alarms
- Amazon ECS Developer Guide
