AWS Resource Mapper

A powerful Python tool for visualizing AWS infrastructures by automatically discovering and mapping resources to generate comprehensive network diagrams using PlantUML.

Overview

AWS Resource Mapper uses boto3 to enumerate your AWS resources, maps the relationships between them, and generates visual representations of your infrastructure. It can create both detailed diagrams (showing every individual resource) and high-level network diagrams that provide a clearer overview of your architecture.

The tool leverages Claude AI to intelligently categorize resources into logical groups, making complex AWS environments more understandable.

Features

• Automatic Resource Discovery: Scans your AWS account to find VPCs, subnets, EC2 instances, RDS databases, ECS clusters, Lambda functions, S3 buckets, security groups, load balancers, and more
• Intelligent Resource Categorization: Uses Claude AI to group resources into logical categories
• Dual Diagram Generation:
  • Detailed diagrams showing all individual resources
  • High-level network diagrams showing the architectural overview
• Highly Customizable: Configure which services to include, diagram styles, and output formats
• Infrastructure-as-Code Compatible: Generate diagrams that can be maintained alongside your IaC resources
• Environment Variable Support: Works with AWS CLI profiles or environment variables for authentication

Prerequisites

• Python 3.8+
• An AWS account with appropriate read permissions
• An Anthropic API key for Claude AI integration
• PlantUML for rendering the diagrams (optional, online rendering also available)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/aws-resource-mapper.git
   cd aws-resource-mapper

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Create a .env file with your Anthropic API key:

   ANTHROPIC_API_KEY=your_api_key_here
   

Configuration

Edit the config.json file to customize your resource discovery:

{
  "aws": {
    "profile": "default",
    "region": "us-east-2",
    "services": [
      "ec2",
      "rds",
      "s3",
      "lambda",
      "apigateway",
      "iam",
      "ecs",
      "elb",
      "elbv2"
    ],
    "discovery_depth": 2
  },
  "anthropic": {
    "model": "claude-3-sonnet-20240229",
    "max_tokens": 4000
  },
  "output": {
    "plantuml_file": "aws_infrastructure.puml",
    "network_diagram_file": "aws_network_diagram.puml",
    "json_file": "aws_infrastructure.json",
    "include_tags": true,
    "group_by_category": true
  },
  "visualization": {
    "show_resource_ids": true,
    "color_scheme": "default",
    "include_load_balancers": true,
    "include_gateways": true,
    "exclude_iam": true
  }
}

Usage

1. Set up your AWS credentials using one of these methods:

   • Configure AWS CLI profiles: aws configure
   • Set environment variables:

     export AWS_ACCESS_KEY_ID=your_access_key
     export AWS_SECRET_ACCESS_KEY=your_secret_key
     export AWS_SESSION_TOKEN=your_session_token  # If using temporary credentials

2. Verify your setup:

   python setup.py --verify

3. Run the mapper:

   python aws_resource_mapper.py

4. View the generated diagrams:

   • Use PlantUML to render the diagrams:

     java -jar plantuml.jar aws_network_diagram.puml
     java -jar plantuml.jar -tpng aws_network_diagram.puml  # For PNG output

   • Or upload the .puml files to the PlantUML online server

Output Examples

High-Level Network Diagram

The tool generates a high-level network diagram that shows:

• VPCs with public and private subnet groupings
• Load balancers and API gateways in public subnets
• Application services grouped by family (e.g., prod-f1, prod-f2)
• Databases grouped by type
• Lambda functions
• S3 storage buckets grouped by category
• Key connections between components

Detailed Resource Diagram

For in-depth analysis, the detailed diagram shows every individual AWS resource and their precise relationships, including:

• Security groups
• Individual ECS tasks and services
• Container images
• Every RDS instance
• All S3 buckets
• And much more

Understanding the Diagrams

The diagrams use different colors and styles to represent different AWS resource types:

• Blue: VPCs and networking components
• Green: RDS databases and storage
• Purple: API Gateways and API-related services
• Orange: S3 buckets and storage resources
• Red: Lambda functions and serverless components
• Light Blue: Load balancers and routing components

Connections between resources represent their relationships, such as "contains," "secures," "routes to," etc.

Troubleshooting

• Missing AWS Credentials: Ensure your AWS credentials are properly configured either via profile or environment variables
• Region Issues: Verify you're using the correct AWS region in your config.json file
• Permission Errors: Ensure your AWS credentials have appropriate read permissions for all services you're trying to discover
• Claude API Issues: Verify your Anthropic API key is valid and properly set in your .env file

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.