aws-skill

What this skill does

# AWS Skill

A CLI wrapper over AWS that encodes our patterns: customer-tagged resources, safe defaults, multi-account auth, intent-level commands. Use it instead of the AWS console for routine ops.

## When to use this skill

- Any AWS read (ec2, s3, iam, rds, lambda, vpc, route53, cloudwatch, ecr, eks)
- Cost lookups (last-30d, by-service, by-tag, per-customer report)
- Provisioning a static-IP jump host for a customer engagement (`jumphost`)
- Generating a Terraform module from an intent op (`terraform jumphost`)
- Running a security audit (open SGs, public S3, old IAM keys, no-MFA users, public RDS)
- Hunting untagged resources (`cleanup untagged`)
- Cross-service inventory by customer or tag
- First-time AWS setup on this machine (`setup` subcommand)

**Do NOT use for:**
- IAM writes (do those in console / Terraform — too easy to break things)
- Bulk S3 sync (use `aws s3 sync` directly — built for it)
- Cluster creation / deletion (Terraform / eksctl — declarative beats imperative)

## First-time setup

```bash
python3 ~/.claude/skills/aws-skill/aws_skill.py setup
```

Walks through `aws configure --profile epoch` and validates with STS. The skill defaults to the `epoch` profile; `--profile NAME` overrides.

```bash
pip install -r ~/.claude/skills/aws-skill/requirements.txt
```

## Universal flags

```
--profile NAME           AWS profile (default: epoch, or AWS_PROFILE env)
--region REGION          override profile region
--format FMT             json (default), table, markdown, ids
--confirm                required for write operations
--confirm-delete         required for destructive operations (separate flag)
--dry-run                preview, don't execute
```

Reads are free. Writes require `--confirm`. Deletes require `--confirm-delete` — intentionally a different flag from `--confirm` to prevent muscle-memory mistakes.

## Service commands

### IAM (read-only)

```bash
aws_skill.py iam who-am-i               # STS GetCallerIdentity + account alias
aws_skill.py iam list-users
aws_skill.py iam list-roles
aws_skill.py iam list-policies          # customer-managed by default
aws_skill.py iam list-policies --scope AWS
```

### EC2

```bash
# reads
aws_skill.py ec2 list                              # running + pending only
aws_skill.py ec2 list --all                        # include stopped/terminated
aws_skill.py ec2 list --customer dmatrix
aws_skill.py ec2 describe i-0abcd1234
aws_skill.py ec2 addresses --customer dmatrix      # Elastic IPs

# writes (--confirm)
aws_skill.py ec2 start i-0abcd1234 --confirm
aws_skill.py ec2 stop  i-0abcd1234 --confirm
aws_skill.py ec2 alloc-eip --confirm
aws_skill.py ec2 associate-eip --allocation-id eipalloc-xxx --instance-id i-xxx --confirm

# deletes (--confirm-delete)
aws_skill.py ec2 terminate i-0abcd1234 --confirm-delete
aws_skill.py ec2 release-eip eipalloc-xxx --confirm-delete
```

### S3

```bash
aws_skill.py s3 ls-buckets
aws_skill.py s3 ls my-bucket [--prefix path/]
aws_skill.py s3 head my-bucket some/key
aws_skill.py s3 get my-bucket some/key --out ~/Downloads/file
aws_skill.py s3 put my-bucket some/key ~/local/path --confirm
aws_skill.py s3 rm my-bucket some/key --confirm-delete
aws_skill.py s3 public-status my-bucket          # exposure assessment
```

### RDS

```bash
aws_skill.py rds list [--customer NAME]
aws_skill.py rds describe my-db
aws_skill.py rds snapshot my-db --confirm
aws_skill.py rds list-snapshots [--instance-id my-db]
```

### Lambda

```bash
aws_skill.py lambda list [--customer NAME]
aws_skill.py lambda get my-function
aws_skill.py lambda invoke my-function --payload '{"x":1}' --confirm
aws_skill.py lambda invoke my-function --payload @./payload.json --confirm
aws_skill.py lambda logs my-function --since 30m --limit 100
```

### VPC

```bash
aws_skill.py vpc list
aws_skill.py vpc subnets [--vpc-id vpc-xxx]
aws_skill.py vpc route-tables [--vpc-id vpc-xxx]
aws_skill.py vpc nat [--vpc-id vpc-xxx]
```

### Route 53

```bash
aws_skill.py route53 zones
aws_skill.py route53 records --zone-id ZONE_ID
aws_skill.py route53 upsert --zone-id ZONE --name foo.example. --type A --value 1.2.3.4 --confirm
aws_skill.py route53 delete --zone-id ZONE --name foo.example. --type A --value 1.2.3.4 --confirm-delete
```

### CloudWatch

```bash
aws_skill.py cloudwatch log-groups [--prefix /aws/lambda/]
aws_skill.py cloudwatch logs /aws/lambda/my-fn --since 1h --limit 500 [--filter "ERROR"]
aws_skill.py cloudwatch metric --namespace AWS/EC2 --name CPUUtilization --days 1
```

### ECR

```bash
aws_skill.py ecr list                            # repositories
aws_skill.py ecr images my-repo --limit 50
aws_skill.py ecr login                           # docker login command + token
```

### EKS

```bash
aws_skill.py eks list [--customer NAME]
aws_skill.py eks kubeconfig my-cluster --confirm        # writes ~/.kube/config
```

### Cost Explorer

```bash
aws_skill.py cost last-30d                              # total spend
aws_skill.py cost by-service                            # grouped by AWS service
aws_skill.py cost by-tag --key Customer                 # grouped by Customer tag
aws_skill.py cost report --customer dmatrix --days 30   # detailed per-customer report (intent)
```

> **Cost-allocation tag note:** `by-tag` and `report --customer` require the `Customer` tag to be activated as a cost-allocation tag in the AWS Billing console. Otherwise totals come back zero.

## Intent commands

### Jumphost (provision / teardown)

```bash
aws_skill.py jumphost provision \
    --customer dmatrix \
    --allowed-ip 1.2.3.4/32 \
    --confirm

aws_skill.py jumphost teardown --customer dmatrix --confirm-delete
```

Creates: SSH key pair (saved locally), security group with port-22 ingress restricted to `--allowed-ip`, EC2 instance (Ubuntu 22.04 LTS, t4g.small default), Elastic IP, and association. Everything is tagged with `Customer`, `Project=jumphost`, `Owner`, `Environment`, `ManagedBy=zerg-aws-skill`.

Customer-specific config (region, allowed-ingress, instance type, key path) lives at `customers/<name>.json`. Copy `templates/customer-config.example.json` to start a new customer.

### Inventory

```bash
aws_skill.py inventory --customer dmatrix       # all skill-touchable resources for a customer
aws_skill.py inventory --tag-key Project --tag-value jumphost
```

### Cleanup (untagged-resource hunter)

```bash
# Report only — never deletes
aws_skill.py cleanup untagged

# Auto-delete safe categories (unattached EIPs, stopped instances older than 7 days)
aws_skill.py cleanup auto --confirm-delete --older-than-days 7

# Preview what auto would do
aws_skill.py cleanup auto --dry-run
```

### Security audit

```bash
aws_skill.py audit                              # all checks
aws_skill.py audit --key-age-days 60 --format table
```

Checks:
- Security groups with `0.0.0.0/0` ingress on non-web ports (SSH = high; web = info)
- S3 buckets with public ACL grants or missing public-access-block
- IAM access keys older than `--key-age-days` (default 90)
- IAM users with passwords but no MFA
- RDS instances with `PubliclyAccessible = true`
- Resources missing required tags (delegates to `cleanup untagged`)

Output groups by severity (high/medium/low/info) with a recommendation per finding.

### Per-customer cost report

```bash
aws_skill.py cost report --customer dmatrix --days 30
```

Returns total + per-AWS-service breakdown + last-6-months trend, all filtered to the `Customer` tag.

## Terraform integration

Render an intent op as a stand-alone Terraform module instead of executing it via boto3:

```bash
aws_skill.py terraform jumphost --customer dmatrix
```

Writes `terraform/<customer>/{main.tf,variables.tf,outputs.tf,user-data.sh}`. Then:

```bash
cd ~/.claude/skills/aws-skill/terraform/dmatrix
terraform init && terraform plan && terraform apply
```

Same intent — different execution path. Use boto3 path for fast, scriptable provisioning; use Terraform path for declarative, drift-aware infrastructure with shared state.