cloudy

Cloudy

Agent-led AWS cloud red team tool. A Claude Code plugin that autonomously validates leaked credentials, enumerates permissions, identifies attack paths, and demonstrates impact — all within the rules of your engagement.

Cloudy orchestrates four security tools through MCP tool servers, with Claude as the decision engine:

• Pacu — AWS exploitation framework
• CloudFox — AWS situational awareness
• enumerate-iam — brute-force permission discovery
• aws-consoler — console URL generation from access keys

Prerequisites

• Claude Code CLI installed
• Python 3.11+
• AWS CLI configured
• One or more of the security tools installed:
  • pip install pacu
  • CloudFox releases (Go binary)
  • pip install enumerate-iam
  • aws-consoler releases (Go binary)

Install

# Clone the repo
git clone [email protected]:mccabe615/cloudy.git
cd cloudy

# Install Python dependencies
pip install -e .

# Install as a Claude Code plugin
claude plugin add ./

Usage

1. Create an engagement config

Copy the example and edit for your engagement:

cp templates/engagement.yaml.example engagement.yaml

engagement:
  name: "acme-corp-2026-q2"
  target_account: "123456789012"

credentials:
  source: "environment"  # environment | profile | explicit
  # profile: "pentest-acme"  # uncomment if source is "profile"

scope:
  regions: ["us-east-1", "us-west-2"]  # or ["all"]
  services: ["iam", "s3", "lambda", "ec2", "sts", "secretsmanager"]

aggression: "create-and-cleanup"  # read-only | create-and-cleanup | create-and-leave
mode: "interactive"  # interactive | autonomous

guardrails:
  max_actions_per_minute: 10
  excluded_resources: []
  require_approval:
    - "iam:CreateUser"
    - "iam:CreateAccessKey"
    - "lambda:CreateFunction"

2. Set credentials

# Option A: Environment variables
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..."  # if using temporary creds

# Option B: AWS CLI profile (set source to "profile" in engagement.yaml)
aws configure --profile pentest-acme

3. Run Cloudy

# Launch Claude Code and invoke the skill
claude

# Then in Claude Code:
/cloudy engagement.yaml

Cloudy will:

1. Validate credentials — confirm they work via sts get-caller-identity
2. Enumerate permissions — brute-force and policy-based discovery across all tools
3. Analyze attack paths — identify privilege escalation, lateral movement, data access
4. Demonstrate impact — execute or describe actions based on your aggression level
5. Generate report — structured findings in report/ with executive summary, evidence, and cleanup manifest

Execution Modes

• Interactive (mode: "interactive") — pauses before every mutating action, explains what it will do and why, waits for your approval
• Autonomous (mode: "autonomous") — runs end-to-end, only pauses for actions listed in guardrails.require_approval

Aggression Levels

Level	Behavior
read-only	Enumerate and report only. No mutations. Proves "I could have done X" without doing it.
create-and-cleanup	Creates artifacts (IAM users, keys, roles) to prove impact, then automatically reverts everything.
create-and-leave	Creates artifacts and leaves them as evidence. Generates a cleanup manifest for the client.

Report Output

After a run, Cloudy generates a report/ directory:

report/
  engagement-summary.md    # Narrative report for the client
  findings.json            # Machine-readable findings
  manifest.json            # Every action taken with reversal commands
  evidence/                # Permission maps, attack path data

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

Disclaimer

Cloudy is designed for authorized penetration testing engagements only. Always obtain proper authorization before testing. The operator is responsible for ensuring all testing is conducted within the scope of their engagement agreement.