Netgraph

MCP server for AWS VPC network path analysis and security auditing

Python 3.10+ License: MIT

NetGraph enables AI assistants to analyze AWS VPC network connectivity by modeling infrastructure as a graph. Ask questions like "Can my web server reach the database on port 5432?" and get deterministic answers with full path analysis.

Why NetGraph?

Without NetGraph, debugging AWS network connectivity requires:

• Manually tracing Security Groups, NACLs, and route tables
• Checking stateful vs stateless rule semantics
• Verifying return path routing for NACLs
• Cross-referencing multiple AWS console pages

With NetGraph, your AI assistant can:

• Analyze complete network paths in seconds
• Identify exactly where traffic is blocked
• Find resources exposed to the public internet
• Discover resources by name or tags when you don't have IDs

Quick Start

Installation

pip install aws-vpc-analyzer

Or install from source:

git clone https://github.com/ayushgoel24/mcp-netgraph.git
cd mcp-netgraph
pip install -e .

For detailed setup instructions, see the Installation Guide.

Configure Your MCP Client

Add NetGraph to your MCP client configuration. Replace your-profile with your AWS CLI profile name.

{
  "mcpServers": {
    "netgraph": {
      "command": "aws-vpc-analyzer",
      "env": {
        "AWS_PROFILE": "your-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

{
  "mcpServers": {
    "netgraph": {
      "command": "uvx",
      "args": ["aws-vpc-analyzer"],
      "env": {
        "AWS_PROFILE": "your-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

{
  "mcpServers": {
    "netgraph": {
      "command": "aws-vpc-analyzer",
      "env": {
        "AWS_PROFILE": "your-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

{
  "mcpServers": {
    "netgraph": {
      "command": "aws-vpc-analyzer",
      "env": {
        "AWS_PROFILE": "your-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

For detailed setup instructions including troubleshooting, see the Installation Guide.

AWS Credentials

NetGraph uses your standard AWS credentials. Ensure you have:

1. AWS CLI configured with a profile, or
2. Environment variables set (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), or
3. IAM role attached (for EC2/Lambda environments)

Required IAM permissions: See AWS Permissions | Full IAM Policy

Tools

analyze_path

Analyze network reachability between a source and destination with hop-by-hop evaluation of Security Groups, NACLs, and route tables.

Can instance i-0abc123 reach 10.0.2.50 on port 443?

Parameters:

Returns: Path status (REACHABLE, BLOCKED, or UNKNOWN), hop-by-hop details, and blocking reason if blocked.

find_public_exposure

Scan a VPC to find resources exposed to the public internet on a specific port.

Show me all resources in vpc-12345678 exposed to SSH on port 22

Parameters:

Returns: List of exposed resources with exposure paths, allowing Security Group rules, and remediation guidance.

find_resources

Discover AWS resources by name pattern or tags. Useful when you know a resource by name but need its ID.

Find all production web servers in vpc-12345678

Parameters:

Returns: Matching resources with IDs, names, IPs, subnets, and tags.

list_vpcs

List and search VPCs in your account. Use this when you need a VPC ID but only know the name or tags.

What VPCs do I have? I'm looking for the production one.

Parameters:

Returns: List of VPCs with IDs, names, CIDRs, state, and tags.

refresh_topology

Pre-warm the cache by fetching all resources in specified VPCs. Optional optimization for faster subsequent queries.

Pre-load the topology for vpc-12345678

Parameters:

Returns: Node/edge counts, resources by type, and duration.

get_cache_stats

Get cache performance statistics.

Returns: Cache hits, misses, hit rate, TTL, and entry counts.

Configuration

Configure NetGraph via environment variables:

Example Prompts

Connectivity debugging:

Can my web server i-0abc123 reach the database at 10.0.3.50 on port 5432?

Security audit:

Find all resources in vpc-prod12345 exposed to the internet on SSH port 22

Resource discovery:

Find all instances tagged Environment=production in vpc-12345678

VPC lookup:

List my VPCs - I need to find the one named "production"

Pre-deployment validation:

Verify that i-gateway123 can reach 10.0.2.100 on port 8080

See docs/examples.md for more detailed examples.

How It Works

NetGraph models your VPC as a directed graph:

• Nodes: EC2 instances, ENIs, subnets, Internet Gateways, NAT Gateways, VPC Peering connections
• Edges: Routing relationships with CIDR destinations and prefix lengths

When you ask about connectivity, NetGraph:

1. Resolves the source to its ENI and subnet
2. Evaluates Security Group egress rules (stateful - only checks outbound)
3. Evaluates NACL outbound rules (stateless - must also check return path)
4. Traverses the route table using Longest Prefix Match (LPM)
5. Follows the path through gateways until reaching the destination
6. Evaluates destination NACL inbound and Security Group ingress rules
7. Verifies return path routing to prevent asymmetric routing failures

AWS Permissions

NetGraph requires read-only EC2 permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeNetworkInterfaces",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeNetworkAcls",
        "ec2:DescribeRouteTables",
        "ec2:DescribeInternetGateways",
        "ec2:DescribeNatGateways",
        "ec2:DescribeVpcs",
        "ec2:DescribeVpcPeeringConnections",
        "ec2:DescribeTransitGateways",
        "ec2:DescribeTransitGatewayAttachments",
        "ec2:GetManagedPrefixListEntries"
      ],
      "Resource": "*"
    }
  ]
}

For cross-account analysis, also add:

• sts:AssumeRole permission
• Trust relationship on target account roles
• Set NETGRAPH_ROLE_ARN environment variable

Documentation

• Installation Guide - Detailed setup instructions
• IAM Policy - Copy-paste IAM policies
• Examples - Detailed usage examples
• Changelog - Release notes and version history

License

MIT

Contributing

Contributions welcome! Please read our Contributing Guide for details on our development process and how to submit pull requests.