Setup guide

Grants the ec2:Describe* actions used to inventory VPCs, subnets, route tables, security groups, NACLs, endpoints, peering connections, and Transit Gateway attachments during triage.

↳ For read-only triage this is already close to minimal; a tighter inline policy can list just ec2:DescribeVpcs, ec2:DescribeSubnets, ec2:DescribeRouteTables, ec2:DescribeSecurityGroupRules, ec2:DescribeNetworkAcls, ec2:DescribeNetworkInterfaces, ec2:DescribeVpcEndpoints.

Reads individual security group rules including the referenced source security group id, which describe-security-groups summarises less precisely.

↳ Cannot be resource-scoped; ec2:Describe* actions only support Resource: "*".

Adds routes to a route table when wiring NAT egress, peering, or Transit Gateway paths. Always exercised with --dry-run first and behind an explicit confirmation gate.

↳ Scope to specific route tables with Resource: arn:aws:ec2:<region>:<account-id>:route-table/rtb-xxxx and add a Condition on aws:RequestTag or ec2:Vpc to pin the VPC.

Opens a destination port to a source security group id or CIDR when triage proves the ingress rule is the blocker.

↳ Scope to arn:aws:ec2:<region>:<account-id>:security-group/sg-xxxx and deny 0.0.0.0/0 on admin ports with a Condition on ec2:SourceInstanceARN or an SCP.

Creates per-AZ NAT gateways for private-subnet egress. Billed hourly plus per GB, so it is always cost-flagged and confirmation-gated.

↳ Pair with ec2:AllocateAddress and restrict with a Condition on aws:RequestTag/Environment so only tagged non-production subnets are targetable.

Creates gateway endpoints for S3/DynamoDB and interface (PrivateLink) endpoints so private subnets reach AWS services without NAT.

↳ Constrain with a Condition on ec2:VpceServiceName to an allow-list of service names, and scope Resource to the target VPC arn.

Enables VPC Flow Logs on a VPC, subnet, or ENI so ACCEPT/REJECT records can prove where packets are dropped.

↳ Also needs iam:PassRole for the flow-log delivery role; scope that PassRole to the single delivery role arn with a Condition on iam:PassedToService = vpc-flow-logs.amazonaws.com.

Runs VPC Reachability Analyzer to identify the exact component blocking a path instead of inferring it.

↳ Must be paired with tiros:CreateQuery and tiros:GetQueryAnswer (Resource: "*") or the analysis fails with AccessDeniedException.

Reads ALB/NLB target health and the TargetHealth.Reason code, which distinguishes a security group block from an application failure.

↳ Read-only and cannot be resource-scoped meaningfully; grant arn:aws:iam::aws:policy/ElasticLoadBalancingReadOnly instead of full access.

Creates or updates alias/A records pointing a hostname at a load balancer. Treated as destructive because UPSERT overwrites existing records.

↳ Scope Resource to arn:aws:route53:::hostedzone/<zone-id> and add a Condition on route53:ChangeResourceRecordSetsRecordTypes and route53:ChangeResourceRecordSetsActions to limit to CREATE of A records.

Confirms which mutating network actions the current principal is actually allowed before proposing a change, avoiding half-applied edits.

↳ Scope Resource to the caller's own principal arn so the skill cannot probe other identities.

Prints the account id, ARN, and user id that every safety check and report header depends on. Implicitly allowed for all principals but list it so audits see it.

Cause: The calling principal lacks the specific ec2 action, or an SCP/permissions boundary denies it. Returned by --dry-run probes as well as real calls.

Fix: Run `aws iam simulate-principal-policy --policy-source-arn $(aws sts get-caller-identity --query Arn --output text) --action-names <action>` to confirm, then attach the missing action. Newer responses include an encoded authorization message decodable with `aws sts decode-authorization-message --encoded-message <blob>`.

Cause: Not a failure. This is the expected success signal from a --dry-run mutating call.

Fix: Treat as authorization confirmed, present the confirmation gate, then re-run without --dry-run.

Cause: Temporary STS or IAM Identity Center credentials passed their expiry (commonly 1-12 hours).

Fix: Re-authenticate with `aws sso login --profile <profile>` or re-run `aws sts assume-role`. Confirm with `aws sts get-caller-identity` before continuing.

Cause: AWS_ACCESS_KEY_ID is wrong, deleted, or belongs to a different partition; or stale AWS_SESSION_TOKEN is set alongside a long-lived AKIA key.

Fix: `unset AWS_SESSION_TOKEN` when using a static AKIA key pair, or regenerate the key. Verify with `aws configure list` that the credential source is what you expect.

Cause: The requested subnet CIDR overlaps an existing subnet in the same VPC.

Fix: List used ranges with `aws ec2 describe-subnets --filters Name=vpc-id,Values=<vpc> --query 'Subnets[].CidrBlock'` and pick a non-overlapping block, or add a secondary VPC CIDR with `aws ec2 associate-vpc-cidr-block`.

Cause: create-route was called for a destination CIDR the route table already covers exactly.

Fix: Use `aws ec2 replace-route` to retarget it — but treat replace-route as destructive and gate it behind explicit confirmation after snapshotting the current route.

Cause: The security group, subnet, IGW, or VPC is still attached to an ENI or referenced by another security group rule.

Fix: Find holders with `aws ec2 describe-network-interfaces --filters Name=group-id,Values=sg-0abc` and `aws ec2 describe-security-groups --filters Name=ip-permission.group-id,Values=sg-0abc`, then detach or re-point them first.

Cause: authorize-security-group-ingress was issued for a rule already present, often from a retried or concurrently applied change.

Fix: Treat as idempotent success. Verify with `aws ec2 describe-security-group-rules --filters Name=group-id,Values=<sg>` rather than retrying.

Cause: The account hit the per-region Elastic IP quota (5 by default) while allocating an EIP for a NAT gateway.

Fix: Release unassociated EIPs (`aws ec2 describe-addresses --filters Name=association-id,Values=` then `aws ec2 release-address`) or raise the quota via Service Quotas code L-0263D0A3.

Cause: The peering request is still `pending-acceptance`, was rejected, or routes are being added before the accepter side accepted it.

Fix: `aws ec2 describe-vpc-peering-connections --vpc-peering-connection-ids pcx-0abc --query 'VpcPeeringConnections[].Status'`, accept from the peer account with `aws ec2 accept-vpc-peering-connection`, then add routes on BOTH sides.

Cause: route53 change-resource-record-sets targeted a hosted zone that does not own the record name, or an alias target hosted zone id is wrong.

Fix: Resolve the correct zone with `aws route53 list-hosted-zones-by-name --dns-name example.com`, and for ALB aliases use the load balancer's CanonicalHostedZoneId from `aws elbv2 describe-load-balancers`.

Cause: The principal has the ec2:*NetworkInsights* actions but is missing tiros:CreateQuery / tiros:GetQueryAnswer, which Reachability Analyzer calls on your behalf.

Fix: Attach an inline policy allowing tiros:CreateQuery, tiros:GetQueryAnswer, tiros:GetQueryExplanation on Resource "*" and retry.