aws-manager

Tell your AI agent to manage your AWS. It handles the rest.

Quick Start  ·  What You Can Do  ·  Scripts  ·  Workflows  ·  For AI Agents  ·  Contributing

---

Managing AWS across multiple accounts is painful. Switching profiles, remembering CLI flags, running cost reports, onboarding teammates, auditing security — it's repetitive, error-prone, and eats your time.

aws-manager fixes this. It's an AI-agent toolkit — a structured set of scripts, configs, and workflows that any AI coding assistant can read and execute. You describe what you want in plain language. Your agent does the rest.

You:   "Scan all my AWS resources and check costs for this month"
Agent: reads config → runs scan-resources.sh → runs scan-costs.sh → presents summary

You:   "Onboard John as a developer on our production account"
Agent: follows onboard-user workflow → creates IAM user → attaches policy → relays credentials

You:   "Run a security audit across all accounts"
Agent: follows security-audit workflow → checks MFA, keys, policies, SGs → reports findings by severity

No web UI. No database. No new tools to learn. Just files that AI agents understand.

---

What You Can Do

Task	How
Scan all resources across accounts	One command, structured JSON output
Monthly cost reports with anomaly detection	Flags >20% increases automatically
Onboard a teammate with the right permissions	Pick a role, agent handles the rest
Bootstrap a new project (Terraform backend, secrets, IAM)	Full workflow, 5 minutes
Security audit (MFA, stale keys, open SGs, public S3)	Findings ranked by severity
SSH into a server to diagnose disk, services, or costs	Follow the triage runbook
Tear down a project cleanly	Correct dependency order, with confirmation
Track everything	Every action logged to state/history.jsonl

Works with Claude Code, Antigravity, Cursor, Windsurf, GitHub Copilot, or any AI agent with shell access. Also works manually — every script runs standalone.

---

Quick Start

Prerequisites: AWS CLI v2 and jq (brew install jq).

# 1. Login to AWS
aws login

# 2. Clone aws-manager
git clone https://github.com/cyphercodes/aws-manager.git
cd aws-manager

# 3. Tell your AI agent: "Set up aws-manager for my AWS account"

That's it. Your agent auto-detects your account ID, region, IAM users, and creates the config for you. No manual editing.

Then just ask for what you need:

• "Scan all my AWS resources"
• "How much am I spending this month?"
• "Onboard John as a developer"
• "Run a security audit"

Multiple accounts? Just aws login --profile other-account and tell your agent to set up that account too. It handles switching between them.

---

How It Works

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Account Configs │────▶│    AI Agent       │────▶│    Scripts       │
│  accounts/*.json │     │  reads workflow   │     │  scripts/*.sh   │
└─────────────────┘     │  decides actions  │     └────────┬────────┘
                        └──────────────────┘              │
┌─────────────────┐              ▲                        ▼
│  Workflows       │──────────────┘               ┌─────────────────┐
│  workflows/*.md  │                              │    State         │
└─────────────────┘                              │  state/*.json   │
                                                  └─────────────────┘
                                                  Next session picks
                                                  up where you left off

Everything is a file. Configs are JSON. Workflows are Markdown. Scripts are Bash. State is JSON. AI agents read files natively — no SDKs, no APIs, no adapters.

---

Project Structure

accounts/       → Your AWS account configs (one JSON file per account)
scripts/        → Shell scripts the AI executes
workflows/      → Step-by-step Markdown instructions for multi-step tasks
policies/       → Reusable IAM policy templates (developer, read-only, terraform)
state/          → Resource snapshots + action history (gitignored)
examples/       → Example configs to get started
config.yaml     → Global settings (budget alerts, safety, scan preferences)
.agent/         → AI agent skill files (the operating contract)

---

Scripts

12 scripts, each does one thing well:

Script	What It Does	Usage
init-account.sh	Auto-detect and configure an AWS account from your session	./scripts/init-account.sh [alias]
use-account.sh	Switch AWS account and validate credentials	./scripts/use-account.sh acme-prod
whoami.sh	Show current AWS identity and context	./scripts/whoami.sh
scan-resources.sh	Inventory EC2, RDS, ECS, Lambda, S3, VPCs, and more	./scripts/scan-resources.sh [alias]
scan-costs.sh	Cost breakdown: MTD, forecast, by-service, daily trend	./scripts/scan-costs.sh [alias] [--month 2026-04]
scan-iam.sh	IAM users with policies, access keys, MFA status	./scripts/scan-iam.sh [alias]
create-iam-user.sh	Create IAM user with login + programmatic access	./scripts/create-iam-user.sh john --policy policies/developer.json
grant-policy.sh	Attach policy to existing user (file or ARN)	./scripts/grant-policy.sh john --policy policies/developer.json
create-tf-backend.sh	Bootstrap S3 + DynamoDB for Terraform state	./scripts/create-tf-backend.sh my-project --region us-east-1
create-secret.sh	Create or generate a Secrets Manager secret	./scripts/create-secret.sh app/api-key --generate
log-action.sh	Log any action to the audit trail	./scripts/log-action.sh acme create-user john
common.sh	Shared utilities (sourced by all scripts)	—

Every script: validates inputs, handles errors gracefully, logs actions, outputs structured JSON.

---

Workflows

AI agents follow these step-by-step. Each workflow references the exact scripts to run.

Workflow	When to Use It
new-project-setup.md	Bootstrap a new project: TF backend, secrets, team permissions
onboard-user.md	Add a teammate with the right access level
cost-audit.md	Monthly cost review across all accounts, flag anomalies
resource-inventory.md	Full resource scan, diff against previous state, spot waste
security-audit.md	Check MFA, stale keys, open SGs, public S3, root usage
teardown-project.md	Cleanly delete all project resources (with confirmation)
server-triage.md	SSH into a server to debug disk, services, networking, egress

---

Policies

Three ready-to-use IAM policy templates:

Policy	For	What It Allows
developer.json	Team members	Deploy Lambda/ECS, read S3/Secrets, push to ECR, full CloudWatch
read-only.json	Auditors / viewers	Get/Describe/List across all common services
terraform-full-access.json	CI/CD / infra leads	Full provisioning (EC2, RDS, VPC, etc.) with IAM guardrails

Each policy includes explicit deny statements to prevent privilege escalation.

---

Account Config

One JSON file per AWS account in accounts/:

{
  "name": "My Company Production",
  "alias": "my-prod",
  "account_id": "123456789012",
  "primary_region": "us-east-1",
  "additional_regions": ["eu-west-1"],
  "profile": "my-prod",
  "projects": [
    {
      "name": "web-app",
      "region": "us-east-1",
      "iac": "terraform",
      "services": ["ecs", "rds", "s3", "alb"]
    }
  ],
  "iam_users": ["alice", "bob"]
}

Account configs are gitignored — your AWS details stay private. See examples/acme-corp.json to get started.

---

Configuration

config.yaml controls global behavior:

budget:
  mode: warn              # off | warn | block
  monthly_alert_usd: 500  # Alert when monthly spend approaches this

safety:
  require_confirmation: true   # Agents must confirm before destructive actions
  require_tags: true           # All resources should have Name + Project tags
  log_all_actions: true        # Every action written to state/history.jsonl

---

For AI Agents

Entry point: .agent/workflows/aws-manager.md

Platform-specific files (CLAUDE.md, CURSOR.md, CODEX.md, .cursorrules) all redirect there. Antigravity and any agent with file access will also discover it automatically. The guide includes:

• How to discover accounts and check state
• Every script with usage and arguments
• Every workflow with when to use it
• Decision announcement contract — agents must state what they'll do and the estimated cost before executing
• Safety rules — always confirm destructive actions, never store credentials, log everything

Agent reads .agent/workflows/aws-manager.md
  → discovers accounts/ configs
  → checks state/ for current snapshots
  → follows workflows/ for multi-step tasks
  → calls scripts/ for individual operations
  → logs everything to state/history.jsonl

---

State & History

Every action is logged to state/history.jsonl:

{"ts":"2026-04-11T16:03:00Z","account":"acme-prod","action":"create-s3-bucket","target":"my-app-tf-state","region":"us-east-1","agent":"claude-code","conversation":"abc123","result":"success"}

Resource scans, cost reports, and IAM snapshots are saved to state/<account>/ so your next session has full context without re-scanning.

state/ssh-hosts.md tracks all known SSH hosts, their connection details, and which AWS resource they correspond to. Agents check this before SSH-ing into any server.

---

Contributing

See CONTRIBUTING.md. The short version:

• Scripts follow the pattern in scripts/common.sh — source it, validate inputs, log actions
• Workflows are Markdown with exact script commands
• Run make validate before submitting

---

License

MIT — use it however you want.