vpcrawler 0.1.0__py3-none-any.whl

aws_vpc_net_tester/__init__.py

@@ -0,0 +1,3 @@
+"""AWS VPC Networking Test Tool."""
+
+__version__ = "0.1.0"

aws_vpc_net_tester/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m aws_vpc_net_tester."""
+
+from .cli import app
+
+if __name__ == "__main__":
+    app()

aws_vpc_net_tester/cli.py

@@ -0,0 +1,214 @@
+"""CLI entry point for AWS VPC Networking Test Tool."""
+
+import json
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from .config_validator import discover_vpc_targets, validate_vpc_connectivity
+from .models import CheckStatus, FullValidationResult
+from .network_tester import parse_port_target, run_dns, run_ping, run_port_check
+
+app = typer.Typer(
+    name="vpcrawler",
+    help="Validate AWS VPC connectivity configuration and run local network tests.",
+)
+console = Console()
+
+
+def _status_style(status: CheckStatus) -> str:
+    """Return rich markup for status."""
+    styles = {
+        CheckStatus.PASS: "[green]PASS[/green]",
+        CheckStatus.FAIL: "[red]FAIL[/red]",
+        CheckStatus.WARN: "[yellow]WARN[/yellow]",
+        CheckStatus.SKIP: "[dim]SKIP[/dim]",
+    }
+    return styles.get(status, str(status))
+
+
+def _run_validate(
+    config_result,
+    ping_target: Optional[str],
+    dns_target: Optional[str],
+    port_target: Optional[str],
+    output_json: bool,
+    auto_test: bool = False,
+    auto_test_max_per_vpc: int = 5,
+    auto_test_ports: list[int] | None = None,
+    profile: Optional[str] = None,
+    region: str = "us-east-1",
+    vpc_a: str = "",
+    vpc_b: str = "",
+) -> None:
+    """Shared validation logic."""
+    network_results = []
+
+    # Auto-discover targets from VPCs when --auto-test is used
+    if auto_test and not config_result.error:
+        ping_targets, port_targets = discover_vpc_targets(
+            vpc_id_a=vpc_a,
+            vpc_id_b=vpc_b,
+            profile=profile,
+            region=region,
+            max_per_vpc=auto_test_max_per_vpc,
+            ports=auto_test_ports or [22, 443],
+        )
+        for ip in ping_targets:
+            network_results.append(run_ping(ip))
+        for host, port in port_targets:
+            network_results.append(run_port_check(host, port))
+
+    if ping_target:
+        network_results.append(run_ping(ping_target))
+
+    if dns_target:
+        network_results.append(run_dns(dns_target))
+
+    if port_target:
+        parsed = parse_port_target(port_target)
+        if parsed:
+            host, port = parsed
+            network_results.append(run_port_check(host, port))
+        else:
+            console.print(f"[red]Invalid --port format: {port_target}. Use host:port[/red]")
+            raise typer.Exit(1)
+
+    full_result = FullValidationResult(
+        config_result=config_result,
+        network_results=network_results,
+    )
+
+    if output_json:
+        console.print(json.dumps(full_result.to_dict(), indent=2))
+        return
+
+    if config_result.error:
+        console.print(f"[red]Error: {config_result.error}[/red]")
+        raise typer.Exit(1)
+
+    console.print("\n[bold]VPC Configuration[/bold]")
+    console.print(f"  VPC A: {config_result.vpc_a.vpc_id} ({config_result.vpc_a.cidr_block})")
+    console.print(f"  VPC B: {config_result.vpc_b.vpc_id} ({config_result.vpc_b.cidr_block})")
+    console.print(f"  Region: {config_result.vpc_a.region}")
+
+    # IP ranges section
+    if config_result.vpc_a.cidr_block or config_result.vpc_b.cidr_block:
+        console.print("\n[bold]IP Ranges[/bold]")
+        console.print(f"  VPC A: {config_result.vpc_a.cidr_block}")
+        for s in config_result.vpc_a.subnets:
+            console.print(f"    - {s['subnet_id']}: {s['cidr']} ({s['az']})")
+        console.print(f"  VPC B: {config_result.vpc_b.cidr_block}")
+        for s in config_result.vpc_b.subnets:
+            console.print(f"    - {s['subnet_id']}: {s['cidr']} ({s['az']})")
+
+    table = Table(title="Validation Checks")
+    table.add_column("Check", style="cyan")
+    table.add_column("Status", style="bold")
+    table.add_column("Message", style="dim")
+
+    for check in config_result.checks:
+        table.add_row(check.name, _status_style(check.status), check.message)
+
+    console.print(table)
+
+    if config_result.connectivity_path_valid:
+        console.print("\n[green]Connectivity path: VALID[/green]")
+    else:
+        console.print("\n[red]Connectivity path: INVALID[/red]")
+
+    if network_results:
+        console.print("\n[bold]Local Network Tests[/bold]")
+        net_table = Table()
+        net_table.add_column("Test", style="cyan")
+        net_table.add_column("Target", style="dim")
+        net_table.add_column("Status", style="bold")
+        net_table.add_column("Message", style="dim")
+
+        for r in network_results:
+            net_table.add_row(r.test_type, r.target, _status_style(r.status), r.message)
+
+        console.print(net_table)
+
+        for r in network_results:
+            if r.output and r.status == CheckStatus.FAIL:
+                console.print(f"\n[dim]{r.test_type} output:[/dim]\n{r.output}")
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    vpc_a: str = typer.Option(..., "--vpc-a", help="First VPC ID"),
+    vpc_b: str = typer.Option(..., "--vpc-b", help="Second VPC ID"),
+    profile: Optional[str] = typer.Option(None, "--profile", help="AWS profile name"),
+    region: str = typer.Option("us-east-1", "--region", help="AWS region"),
+    auto_test: bool = typer.Option(
+        False,
+        "--auto-test",
+        help="Discover EC2 instances in VPCs and run ping/port checks automatically",
+    ),
+    max_targets_per_vpc: int = typer.Option(
+        5,
+        "--max-targets-per-vpc",
+        help="Max EC2 instances to test per VPC when using --auto-test",
+    ),
+    auto_test_ports: str = typer.Option(
+        "22,443",
+        "--auto-test-ports",
+        help="Comma-separated ports to check when using --auto-test (e.g., 22,443,8080)",
+    ),
+    ping_target: Optional[str] = typer.Option(None, "--ping", help="IP or hostname to ping"),
+    dns_target: Optional[str] = typer.Option(None, "--dns", help="Hostname to resolve via DNS"),
+    port_target: Optional[str] = typer.Option(
+        None,
+        "--port",
+        help="Host:port to test (e.g., 10.0.2.100:443)",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Output results as JSON"),
+) -> None:
+    """
+    Validate VPC connectivity configuration between two VPCs and optionally run
+    local network tests (ping, DNS, port check). Use --auto-test to discover EC2
+    instances in the VPCs and run connectivity tests automatically.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    # Parse auto-test ports
+    ports_list: list[int] | None = None
+    if auto_test:
+        try:
+            ports_list = [int(p.strip()) for p in auto_test_ports.split(",") if p.strip()]
+        except ValueError:
+            console.print("[red]Invalid --auto-test-ports. Use comma-separated integers (e.g., 22,443)[/red]")
+            raise typer.Exit(1)
+
+    config_result = validate_vpc_connectivity(
+        vpc_id_a=vpc_a,
+        vpc_id_b=vpc_b,
+        profile=profile,
+        region=region,
+    )
+
+    _run_validate(
+        config_result=config_result,
+        ping_target=ping_target,
+        dns_target=dns_target,
+        port_target=port_target,
+        output_json=output_json,
+        auto_test=auto_test,
+        auto_test_max_per_vpc=max_targets_per_vpc,
+        auto_test_ports=ports_list,
+        profile=profile,
+        region=region,
+        vpc_a=vpc_a,
+        vpc_b=vpc_b,
+    )
+
+
+
+
+if __name__ == "__main__":
+    app()

aws_vpc_net_tester/config_validator.py

@@ -0,0 +1,428 @@
+"""boto3-based VPC configuration validation between two VPCs."""
+
+import ipaddress
+from typing import Any
+
+import boto3
+from botocore.exceptions import ClientError
+
+from .models import CheckStatus, ConfigValidationResult, ValidationCheck, VpcInfo
+
+
+def _get_tags(resource: dict[str, Any]) -> dict[str, str]:
+    """Extract tags as a dict from AWS resource."""
+    tags = resource.get("Tags") or []
+    return {t["Key"]: t["Value"] for t in tags}
+
+
+def _cidr_overlaps(cidr1: str, cidr2: str) -> bool:
+    """Check if two CIDR blocks overlap."""
+    try:
+        n1 = ipaddress.ip_network(cidr1)
+        n2 = ipaddress.ip_network(cidr2)
+        return n1.overlaps(n2)
+    except ValueError:
+        return False
+
+
+def _cidr_contains(cidr: str, ip: str) -> bool:
+    """Check if an IP is within a CIDR block."""
+    try:
+        network = ipaddress.ip_network(cidr)
+        addr = ipaddress.ip_address(ip)
+        return addr in network
+    except ValueError:
+        return False
+
+
+def _rule_allows_cidr(
+    rule: dict[str, Any],
+    target_cidr: str,
+    port: int | None = None,
+    protocol: str = "tcp",
+) -> bool:
+    """Check if a security group or NACL rule allows traffic to/from target CIDR."""
+    cidr = rule.get("CidrBlock") or rule.get("Ipv6CidrBlock") or ""
+    if not cidr or cidr == "0.0.0.0/0":
+        cidr = "0.0.0.0/0"
+    if cidr == "0.0.0.0/0":
+        pass  # Allow all
+    else:
+        # Check if target CIDR overlaps with rule CIDR
+        if not _cidr_overlaps(cidr, target_cidr):
+            return False
+
+    if rule.get("RuleAction") == "deny":
+        return False
+
+    # Port check for TCP/UDP
+    if port is not None and protocol in ("tcp", "udp"):
+        from_port = rule.get("FromPort")
+        to_port = rule.get("ToPort")
+        if from_port is not None and to_port is not None:
+            if not (from_port <= port <= to_port):
+                return False
+
+    return True
+
+
+def validate_vpc_connectivity(
+    vpc_id_a: str,
+    vpc_id_b: str,
+    profile: str | None = None,
+    region: str = "us-east-1",
+    check_port: int | None = 22,
+    check_protocol: str = "tcp",
+) -> ConfigValidationResult:
+    """
+    Validate VPC connectivity configuration between two VPCs.
+
+    Uses boto3 to fetch and analyze route tables, subnets, security groups,
+    NACLs, VPC peering, and Transit Gateway attachments.
+    """
+    session = boto3.Session(profile_name=profile, region_name=region)
+    ec2 = session.client("ec2")
+    checks: list[ValidationCheck] = []
+
+    try:
+        # Fetch both VPCs
+        vpcs_resp = ec2.describe_vpcs(VpcIds=[vpc_id_a, vpc_id_b])
+        vpcs = {v["VpcId"]: v for v in vpcs_resp["Vpcs"]}
+
+        if vpc_id_a not in vpcs or vpc_id_b not in vpcs:
+            missing = [v for v in [vpc_id_a, vpc_id_b] if v not in vpcs]
+            return ConfigValidationResult(
+                vpc_a=VpcInfo(vpc_id=vpc_id_a, cidr_block="", region=region),
+                vpc_b=VpcInfo(vpc_id=vpc_id_b, cidr_block="", region=region),
+                error=f"VPC(s) not found: {missing}",
+            )
+
+        vpc_a_data = vpcs[vpc_id_a]
+        vpc_b_data = vpcs[vpc_id_b]
+        cidr_a = vpc_a_data.get("CidrBlock", "")
+        cidr_b = vpc_b_data.get("CidrBlock", "")
+
+        # Subnets
+        subnets_resp = ec2.describe_subnets(
+            Filters=[{"Name": "vpc-id", "Values": [vpc_id_a, vpc_id_b]}]
+        )
+        subnets_a = [
+            {"subnet_id": s["SubnetId"], "cidr": s["CidrBlock"], "az": s["AvailabilityZone"]}
+            for s in subnets_resp["Subnets"]
+            if s["VpcId"] == vpc_id_a
+        ]
+        subnets_b = [
+            {"subnet_id": s["SubnetId"], "cidr": s["CidrBlock"], "az": s["AvailabilityZone"]}
+            for s in subnets_resp["Subnets"]
+            if s["VpcId"] == vpc_id_b
+        ]
+
+        vpc_a_info = VpcInfo(
+            vpc_id=vpc_id_a,
+            cidr_block=cidr_a,
+            region=region,
+            subnets=subnets_a,
+            tags=_get_tags(vpc_a_data),
+        )
+        vpc_b_info = VpcInfo(
+            vpc_id=vpc_id_b,
+            cidr_block=cidr_b,
+            region=region,
+            subnets=subnets_b,
+            tags=_get_tags(vpc_b_data),
+        )
+
+        # Check 1: CIDR overlap (peered VPCs must not overlap)
+        if _cidr_overlaps(cidr_a, cidr_b):
+            checks.append(
+                ValidationCheck(
+                    name="cidr_overlap",
+                    status=CheckStatus.FAIL,
+                    message="VPC CIDR blocks overlap - peering/connectivity not possible",
+                    details={"cidr_a": cidr_a, "cidr_b": cidr_b},
+                )
+            )
+        else:
+            checks.append(
+                ValidationCheck(
+                    name="cidr_overlap",
+                    status=CheckStatus.PASS,
+                    message="VPC CIDR blocks do not overlap",
+                    details={"cidr_a": cidr_a, "cidr_b": cidr_b},
+                )
+            )
+
+        # Check 2: VPC Peering
+        peering_resp = ec2.describe_vpc_peering_connections(
+            Filters=[
+                {"Name": "status-code", "Values": ["active"]},
+            ]
+        )
+        peerings = peering_resp.get("VpcPeeringConnections", [])
+        peering_exists = False
+        for p in peerings:
+            requester = p.get("RequesterVpcInfo", {}).get("VpcId")
+            accepter = p.get("AccepterVpcInfo", {}).get("VpcId")
+            if {requester, accepter} == {vpc_id_a, vpc_id_b}:
+                peering_exists = True
+                break
+
+        tgw_connected = False
+        if peering_exists:
+            checks.append(
+                ValidationCheck(
+                    name="vpc_peering",
+                    status=CheckStatus.PASS,
+                    message="Active VPC peering connection exists between the two VPCs",
+                    details={},
+                )
+            )
+        else:
+            # Check Transit Gateway as alternative
+            tgw_attachments = ec2.describe_transit_gateway_attachments(
+                Filters=[{"Name": "resource-type", "Values": ["vpc"]}]
+            )
+            tgw_vpcs: dict[str, set[str]] = {}  # tgw_id -> set of vpc_ids
+            for att in tgw_attachments.get("TransitGatewayAttachments", []):
+                if att["State"] != "available":
+                    continue
+                tgw_id = att["TransitGatewayId"]
+                vpc_id = att["ResourceId"]
+                if tgw_id not in tgw_vpcs:
+                    tgw_vpcs[tgw_id] = set()
+                tgw_vpcs[tgw_id].add(vpc_id)
+
+            tgw_connected = any(
+                vpc_id_a in vpcs_set and vpc_id_b in vpcs_set
+                for vpcs_set in tgw_vpcs.values()
+            )
+
+            if tgw_connected:
+                checks.append(
+                    ValidationCheck(
+                        name="transit_gateway",
+                        status=CheckStatus.PASS,
+                        message="Both VPCs attached to same Transit Gateway",
+                        details={},
+                    )
+                )
+            else:
+                checks.append(
+                    ValidationCheck(
+                        name="vpc_peering",
+                        status=CheckStatus.FAIL,
+                        message="No active VPC peering or Transit Gateway connection",
+                        details={},
+                    )
+                )
+                checks.append(
+                    ValidationCheck(
+                        name="transit_gateway",
+                        status=CheckStatus.FAIL,
+                        message="No shared Transit Gateway attachment",
+                        details={},
+                    )
+                )
+
+        has_peering_or_tgw = peering_exists or tgw_connected
+
+        # Check 3: Route tables - routes to peer CIDR
+        if has_peering_or_tgw:
+            rt_resp = ec2.describe_route_tables(
+                Filters=[{"Name": "vpc-id", "Values": [vpc_id_a, vpc_id_b]}]
+            )
+            route_tables = rt_resp.get("RouteTables", [])
+
+            routes_to_b_from_a = False
+            routes_to_a_from_b = False
+
+            for rt in route_tables:
+                vpc_id = rt["VpcId"]
+                for route in rt.get("Routes", []):
+                    dest = route.get("DestinationCidrBlock", "")
+                    if not dest:
+                        continue
+                    if vpc_id == vpc_id_a and _cidr_overlaps(dest, cidr_b):
+                        routes_to_b_from_a = True
+                    if vpc_id == vpc_id_b and _cidr_overlaps(dest, cidr_a):
+                        routes_to_a_from_b = True
+
+            if routes_to_b_from_a and routes_to_a_from_b:
+                checks.append(
+                    ValidationCheck(
+                        name="route_tables",
+                        status=CheckStatus.PASS,
+                        message="Route tables have routes for peer VPC CIDRs",
+                        details={
+                            "vpc_a_routes_to_b": routes_to_b_from_a,
+                            "vpc_b_routes_to_a": routes_to_a_from_b,
+                        },
+                    )
+                )
+            else:
+                checks.append(
+                    ValidationCheck(
+                        name="route_tables",
+                        status=CheckStatus.FAIL,
+                        message="Missing routes to peer VPC CIDR in one or both VPCs",
+                        details={
+                            "vpc_a_routes_to_b": routes_to_b_from_a,
+                            "vpc_b_routes_to_a": routes_to_a_from_b,
+                        },
+                    )
+                )
+
+        # Check 4: Security groups - at least one allows traffic
+        sg_resp = ec2.describe_security_groups(
+            Filters=[{"Name": "vpc-id", "Values": [vpc_id_a, vpc_id_b]}]
+        )
+        sgs = sg_resp.get("SecurityGroups", [])
+
+        sg_a_allows_from_b = False
+        sg_b_allows_from_a = False
+
+        for sg in sgs:
+            vpc_id = sg["VpcId"]
+            for perm in sg.get("IpPermissions", []):
+                for ip_range in perm.get("IpRanges", []) + perm.get("Ipv6Ranges", []):
+                    cidr = ip_range.get("CidrIp") or ip_range.get("CidrIpv6") or ""
+                    if vpc_id == vpc_id_a and _cidr_overlaps(cidr, cidr_b):
+                        sg_a_allows_from_b = True
+                    if vpc_id == vpc_id_b and _cidr_overlaps(cidr, cidr_a):
+                        sg_b_allows_from_a = True
+
+        for sg in sgs:
+            vpc_id = sg["VpcId"]
+            for perm in sg.get("IpPermissionsEgress", []):
+                for ip_range in perm.get("IpRanges", []) + perm.get("Ipv6Ranges", []):
+                    cidr = ip_range.get("CidrIp") or ip_range.get("CidrIpv6") or ""
+                    if vpc_id == vpc_id_a and _cidr_overlaps(cidr, cidr_b):
+                        sg_a_allows_from_b = True
+                    if vpc_id == vpc_id_b and _cidr_overlaps(cidr, cidr_a):
+                        sg_b_allows_from_a = True
+
+        if sg_a_allows_from_b and sg_b_allows_from_a:
+            checks.append(
+                ValidationCheck(
+                    name="security_groups",
+                    status=CheckStatus.PASS,
+                    message="Security groups allow traffic between VPC CIDRs",
+                    details={},
+                )
+            )
+        else:
+            checks.append(
+                ValidationCheck(
+                    name="security_groups",
+                    status=CheckStatus.WARN,
+                    message="Security groups may restrict traffic - verify rules allow cross-VPC access",
+                    details={
+                        "vpc_a_allows_from_b": sg_a_allows_from_b,
+                        "vpc_b_allows_from_a": sg_b_allows_from_a,
+                    },
+                )
+            )
+
+        # Check 5: Network ACLs
+        nacl_resp = ec2.describe_network_acls(
+            Filters=[{"Name": "vpc-id", "Values": [vpc_id_a, vpc_id_b]}]
+        )
+        nacls = nacl_resp.get("NetworkAcls", [])
+
+        nacl_blocks_traffic = False
+        for nacl in nacls:
+            for entry in nacl.get("Entries", []):
+                if entry.get("RuleAction") == "deny":
+                    cidr = entry.get("CidrBlock", "")
+                    if cidr == "0.0.0.0/0" or _cidr_overlaps(cidr, cidr_a) or _cidr_overlaps(cidr, cidr_b):
+                        nacl_blocks_traffic = True
+                        break
+
+        if nacl_blocks_traffic:
+            checks.append(
+                ValidationCheck(
+                    name="network_acls",
+                    status=CheckStatus.WARN,
+                    message="NACL deny rules may block cross-VPC traffic - verify rules",
+                    details={},
+                )
+            )
+        else:
+            checks.append(
+                ValidationCheck(
+                    name="network_acls",
+                    status=CheckStatus.PASS,
+                    message="No NACL rules found that explicitly block cross-VPC traffic",
+                    details={},
+                )
+            )
+
+        # Overall connectivity path
+        fail_checks = [c for c in checks if c.status == CheckStatus.FAIL]
+        connectivity_valid = len(fail_checks) == 0
+
+        return ConfigValidationResult(
+            vpc_a=vpc_a_info,
+            vpc_b=vpc_b_info,
+            checks=checks,
+            connectivity_path_valid=connectivity_valid,
+        )
+
+    except ClientError as e:
+        error_code = e.response.get("Error", {}).get("Code", "")
+        error_msg = e.response.get("Error", {}).get("Message", str(e))
+        return ConfigValidationResult(
+            vpc_a=VpcInfo(vpc_id=vpc_id_a, cidr_block="", region=region),
+            vpc_b=VpcInfo(vpc_id=vpc_id_b, cidr_block="", region=region),
+            error=f"AWS API error ({error_code}): {error_msg}",
+        )
+
+
+def discover_vpc_targets(
+    vpc_id_a: str,
+    vpc_id_b: str,
+    profile: str | None = None,
+    region: str = "us-east-1",
+    max_per_vpc: int = 5,
+    ports: list[int] | None = None,
+) -> tuple[list[str], list[tuple[str, int]]]:
+    """
+    Discover EC2 instance private IPs in both VPCs for automatic connectivity testing.
+
+    Returns:
+        (ping_targets, port_targets) - lists of IPs to ping and (host, port) tuples for port checks.
+    """
+    if ports is None:
+        ports = [22, 443]
+
+    session = boto3.Session(profile_name=profile, region_name=region)
+    ec2 = session.client("ec2")
+
+    ping_targets: list[str] = []
+    port_targets: list[tuple[str, int]] = []
+
+    try:
+        for vpc_id in [vpc_id_a, vpc_id_b]:
+            instances_resp = ec2.describe_instances(
+                Filters=[
+                    {"Name": "vpc-id", "Values": [vpc_id]},
+                    {"Name": "instance-state-name", "Values": ["running"]},
+                ]
+            )
+            ips: list[str] = []
+            for reservation in instances_resp.get("Reservations", []):
+                for instance in reservation.get("Instances", []):
+                    private_ip = instance.get("PrivateIpAddress")
+                    if private_ip:
+                        ips.append(private_ip)
+
+            # Limit targets per VPC
+            for ip in ips[:max_per_vpc]:
+                ping_targets.append(ip)
+                for port in ports:
+                    port_targets.append((ip, port))
+
+    except ClientError:
+        pass  # Return empty lists on error
+
+    return ping_targets, port_targets

aws_vpc_net_tester/models.py

@@ -0,0 +1,114 @@
+"""Data classes for VPC and connectivity validation results."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class CheckStatus(str, Enum):
+    """Status of a validation check."""
+
+    PASS = "pass"
+    FAIL = "fail"
+    WARN = "warn"
+    SKIP = "skip"
+
+
+@dataclass
+class ValidationCheck:
+    """Single validation check result."""
+
+    name: str
+    status: CheckStatus
+    message: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class VpcInfo:
+    """Basic VPC information."""
+
+    vpc_id: str
+    cidr_block: str
+    region: str
+    subnets: list[dict[str, Any]] = field(default_factory=list)
+    tags: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class ConfigValidationResult:
+    """Result of VPC configuration validation between two VPCs."""
+
+    vpc_a: VpcInfo
+    vpc_b: VpcInfo
+    checks: list[ValidationCheck] = field(default_factory=list)
+    connectivity_path_valid: bool = False
+    error: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to JSON-serializable dict."""
+        return {
+            "vpc_a": {
+                "vpc_id": self.vpc_a.vpc_id,
+                "cidr_block": self.vpc_a.cidr_block,
+                "region": self.vpc_a.region,
+                "subnets": self.vpc_a.subnets,
+                "tags": self.vpc_a.tags,
+            },
+            "vpc_b": {
+                "vpc_id": self.vpc_b.vpc_id,
+                "cidr_block": self.vpc_b.cidr_block,
+                "region": self.vpc_b.region,
+                "subnets": self.vpc_b.subnets,
+                "tags": self.vpc_b.tags,
+            },
+            "checks": [
+                {
+                    "name": c.name,
+                    "status": c.status.value,
+                    "message": c.message,
+                    "details": c.details,
+                }
+                for c in self.checks
+            ],
+            "connectivity_path_valid": self.connectivity_path_valid,
+            "error": self.error,
+        }
+
+
+@dataclass
+class NetworkTestResult:
+    """Result of a local network connectivity test."""
+
+    test_type: str  # ping, dns, port
+    target: str
+    status: CheckStatus
+    message: str
+    output: str = ""
+    duration_ms: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to JSON-serializable dict."""
+        return {
+            "test_type": self.test_type,
+            "target": self.target,
+            "status": self.status.value,
+            "message": self.message,
+            "output": self.output,
+            "duration_ms": self.duration_ms,
+        }
+
+
+@dataclass
+class FullValidationResult:
+    """Combined result of config validation and network tests."""
+
+    config_result: ConfigValidationResult
+    network_results: list[NetworkTestResult] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to JSON-serializable dict."""
+        return {
+            "config": self.config_result.to_dict(),
+            "network_tests": [r.to_dict() for r in self.network_results],
+        }

aws_vpc_net_tester/network_tester.py

@@ -0,0 +1,173 @@
+"""Local network connectivity tests (ping, DNS, port check)."""
+
+import platform
+import shutil
+import socket
+import subprocess
+import time
+
+from .models import CheckStatus, NetworkTestResult
+
+
+def _run_command(
+    cmd: list[str],
+    timeout: int = 10,
+) -> tuple[bool, str, float | None]:
+    """
+    Run a command and return (success, output, duration_ms).
+    """
+    try:
+        start = time.perf_counter()
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        duration_ms = (time.perf_counter() - start) * 1000
+        output = (result.stdout or "") + (result.stderr or "")
+        return result.returncode == 0, output.strip(), duration_ms
+    except subprocess.TimeoutExpired:
+        return False, "Command timed out", None
+    except FileNotFoundError:
+        return False, f"Command not found: {cmd[0]}", None
+    except Exception as e:
+        return False, str(e), None
+
+
+def run_ping(target: str, count: int = 4, timeout: int = 15) -> NetworkTestResult:
+    """
+    Run ping to target from local machine.
+    Uses platform-appropriate flags (Linux/macOS: -c, Windows: -n).
+    """
+    system = platform.system().lower()
+    if system == "windows":
+        cmd = ["ping", "-n", str(count), target]
+    else:
+        cmd = ["ping", "-c", str(count), target]
+
+    success, output, duration_ms = _run_command(cmd, timeout=timeout)
+
+    if success:
+        return NetworkTestResult(
+            test_type="ping",
+            target=target,
+            status=CheckStatus.PASS,
+            message="Ping successful",
+            output=output,
+            duration_ms=duration_ms,
+        )
+    return NetworkTestResult(
+        test_type="ping",
+        target=target,
+        status=CheckStatus.FAIL,
+        message="Ping failed",
+        output=output,
+        duration_ms=duration_ms,
+    )
+
+
+def run_dns(hostname: str, timeout: int = 10) -> NetworkTestResult:
+    """
+    Resolve hostname via dig (preferred) or nslookup.
+    """
+    # Prefer dig if available (more parseable output)
+    if shutil.which("dig"):
+        cmd = ["dig", "+short", hostname]
+        success, output, duration_ms = _run_command(cmd, timeout=timeout)
+    elif shutil.which("nslookup"):
+        cmd = ["nslookup", hostname]
+        success, output, duration_ms = _run_command(cmd, timeout=timeout)
+    else:
+        return NetworkTestResult(
+            test_type="dns",
+            target=hostname,
+            status=CheckStatus.FAIL,
+            message="Neither dig nor nslookup found - cannot resolve DNS",
+            output="",
+        )
+
+    if success and output:
+        return NetworkTestResult(
+            test_type="dns",
+            target=hostname,
+            status=CheckStatus.PASS,
+            message="DNS resolution successful",
+            output=output,
+            duration_ms=duration_ms,
+        )
+    return NetworkTestResult(
+        test_type="dns",
+        target=hostname,
+        status=CheckStatus.FAIL,
+        message="DNS resolution failed or returned empty",
+        output=output,
+        duration_ms=duration_ms,
+    )
+
+
+def _port_check_socket(host: str, port: int, timeout: int) -> tuple[bool, float]:
+    """Test TCP connectivity using Python socket. Returns (success, duration_ms)."""
+    start = time.perf_counter()
+    try:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(timeout)
+        sock.connect((host, port))
+        sock.close()
+        duration_ms = (time.perf_counter() - start) * 1000
+        return True, duration_ms
+    except (socket.timeout, socket.error, OSError):
+        return False, (time.perf_counter() - start) * 1000
+
+
+def run_port_check(host: str, port: int, timeout: int = 5) -> NetworkTestResult:
+    """
+    Test TCP connectivity to host:port using nc (netcat) or Python socket.
+    """
+    target_str = f"{host}:{port}"
+
+    # Prefer nc (netcat) - more commonly available on macOS/Linux
+    if shutil.which("nc"):
+        cmd = ["nc", "-zv", "-w", str(timeout), host, str(port)]
+        success, output, duration_ms = _run_command(cmd, timeout=timeout + 2)
+    else:
+        # Fallback to Python socket - no external deps, works everywhere
+        success, duration_ms = _port_check_socket(host, port, timeout)
+        output = ""
+
+    if success:
+        return NetworkTestResult(
+            test_type="port",
+            target=target_str,
+            status=CheckStatus.PASS,
+            message="Port is reachable",
+            output=output,
+            duration_ms=duration_ms,
+        )
+    return NetworkTestResult(
+        test_type="port",
+        target=target_str,
+        status=CheckStatus.FAIL,
+        message="Port is not reachable",
+        output=output,
+        duration_ms=duration_ms,
+    )
+
+
+def parse_port_target(target: str) -> tuple[str, int] | None:
+    """
+    Parse 'host:port' string. Returns (host, port) or None if invalid.
+    """
+    if ":" not in target:
+        return None
+    parts = target.rsplit(":", 1)
+    if len(parts) != 2:
+        return None
+    host, port_str = parts
+    try:
+        port = int(port_str)
+        if 1 <= port <= 65535:
+            return host.strip(), port
+    except ValueError:
+        pass
+    return None

vpcrawler-0.1.0.dist-info/METADATA

@@ -0,0 +1,372 @@
+Metadata-Version: 2.4
+Name: vpcrawler
+Version: 0.1.0
+Summary: A CLI tool to validate AWS VPC connectivity configuration between two VPCs
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: boto3>=1.28
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# AWS VPC Networking Test Tool
+
+A Python CLI tool that validates AWS VPC connectivity configuration between two VPCs and runs local network connectivity tests. Use it to troubleshoot cross-VPC connectivity, verify peering and Transit Gateway setup, and test reachability from your local machine to targets inside your VPCs.
+
+## Overview
+
+The tool combines two capabilities:
+
+1. **Configuration validation** — Uses the AWS API (boto3) to analyze route tables, security groups, network ACLs, VPC peering, and Transit Gateway attachments. It determines whether the *configuration* allows traffic to flow between two VPCs.
+
+2. **Connectivity testing** — Runs ping, DNS resolution, and TCP port checks from your local machine to verify actual reachability. Targets can be specified manually or discovered automatically from EC2 instances in the VPCs.
+
+All commands run from your local machine using your AWS profile. No agents or deployments inside AWS are required.
+
+## Features
+
+- **VPC configuration analysis** — CIDR overlap, route tables, security groups, NACLs, peering, Transit Gateway
+- **IP range reporting** — VPC and subnet CIDR blocks with availability zones
+- **Auto-discovery** — Find running EC2 instances in both VPCs and test them automatically
+- **Local network tests** — Ping, DNS (dig/nslookup), TCP port checks
+- **JSON output** — Machine-readable output for scripting and CI/CD
+- **Cross-platform** — Works on macOS, Linux, and Windows
+
+## Requirements
+
+- Python 3.9+
+- AWS credentials configured (profile or environment)
+- Network access to AWS APIs and to targets you test (VPN, bastion, or direct if testing public endpoints)
+
+## Installation
+
+```bash
+# Clone or navigate to the project
+cd vpcrawler
+
+# Install in editable mode
+pip install -e .
+
+# Or install dependencies only
+pip install -r requirements.txt
+```
+
+### Dependencies
+
+- **boto3** — AWS SDK for Python
+- **typer** — CLI framework
+- **rich** — Formatted console output
+
+## Quick Start
+
+```bash
+# Validate configuration between two VPCs
+vpcrawler --vpc-a vpc-0abc123 --vpc-b vpc-0def456 --profile myprofile
+
+# Validate and automatically test EC2 instances in both VPCs
+vpcrawler --vpc-a vpc-0abc123 --vpc-b vpc-0def456 --profile myprofile --auto-test
+```
+
+## Usage Modes
+
+### 1. Configuration Validation Only
+
+Validates that the AWS configuration allows connectivity between two VPCs. No network tests are run.
+
+```bash
+vpcrawler --vpc-a vpc-0abc123 --vpc-b vpc-0def456 --profile myprofile --region us-east-1
+```
+
+Use this to:
+- Audit peering or Transit Gateway setup
+- Verify route tables and security groups
+- Check for CIDR overlap before peering
+
+### 2. Auto-Test Mode
+
+Discovers running EC2 instances in both VPCs and automatically runs ping and port checks against their private IPs.
+
+```bash
+vpcrawler --vpc-a vpc-0abc123 --vpc-b vpc-0def456 --profile myprofile --auto-test
+```
+
+With options:
+
+```bash
+vpcrawler --vpc-a vpc-0abc123 --vpc-b vpc-0def456 --auto-test \
+  --max-targets-per-vpc 3 \
+  --auto-test-ports 22,443,8080
+```
+
+**Note:** Auto-test requires your local machine to reach the EC2 private IPs (e.g., via VPN or bastion host). If you cannot reach private IPs from your machine, use manual targets instead.
+
+### 3. Manual Connectivity Tests
+
+Specify exact targets for ping, DNS, and port checks.
+
+```bash
+vpcrawler --vpc-a vpc-0abc123 --vpc-b vpc-0def456 \
+  --ping 10.0.1.50 \
+  --dns internal.example.com \
+  --port 10.0.2.100:443
+```
+
+You can use any combination of `--ping`, `--port`, and `--dns`.
+
+### 4. Combined Usage
+
+Auto-test and manual targets can be used together. All tests run and appear in the output.
+
+```bash
+vpcrawler --vpc-a vpc-0abc123 --vpc-b vpc-0def456 --auto-test \
+  --ping 10.0.1.1 \
+  --dns api.internal.example.com
+```
+
+## Command Reference
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `--vpc-a` | Yes | — | First VPC ID |
+| `--vpc-b` | Yes | — | Second VPC ID |
+| `--profile` | No | `AWS_PROFILE` env | AWS profile name |
+| `--region` | No | `us-east-1` | AWS region |
+| `--auto-test` | No | `false` | Discover EC2 instances and run ping/port checks |
+| `--max-targets-per-vpc` | No | `5` | Max instances to test per VPC with `--auto-test` |
+| `--auto-test-ports` | No | `22,443` | Ports to check with `--auto-test` (comma-separated) |
+| `--ping` | No | — | IP or hostname to ping |
+| `--dns` | No | — | Hostname to resolve via DNS |
+| `--port` | No | — | `host:port` to test (e.g., `10.0.2.100:443`) |
+| `--json` | No | `false` | Output results as JSON |
+
+## Configuration Validation
+
+The tool runs these checks to determine if connectivity *should* work between the two VPCs:
+
+### CIDR Overlap
+
+VPC peering and Transit Gateway require non-overlapping CIDR blocks. If the VPCs overlap, peering cannot be established.
+
+- **PASS** — CIDRs do not overlap
+- **FAIL** — CIDRs overlap; connectivity not possible
+
+### VPC Peering
+
+Checks for an active VPC peering connection between the two VPCs.
+
+- **PASS** — Active peering exists
+- **FAIL** — No peering (and no Transit Gateway fallback)
+
+### Transit Gateway
+
+If no peering exists, checks whether both VPCs are attached to the same Transit Gateway.
+
+- **PASS** — Both VPCs attached to same TGW
+- **FAIL** — No shared Transit Gateway
+
+### Route Tables
+
+When peering or TGW exists, verifies that route tables in both VPCs have routes for the peer VPC’s CIDR.
+
+- **PASS** — Routes exist in both directions
+- **FAIL** — Missing routes in one or both VPCs
+
+### Security Groups
+
+Checks whether any security groups allow traffic between the VPC CIDRs (ingress and egress).
+
+- **PASS** — Rules allow cross-VPC traffic
+- **WARN** — May restrict traffic; manual verification recommended
+
+### Network ACLs
+
+Looks for NACL deny rules that could block cross-VPC traffic.
+
+- **PASS** — No blocking rules found
+- **WARN** — Deny rules may block traffic; manual verification recommended
+
+### Connectivity Path
+
+Overall result: **VALID** if no checks fail, **INVALID** if any check fails.
+
+## Local Connectivity Tests
+
+Tests run from your local machine. Your machine must have network path to the targets (VPN, bastion, or direct access).
+
+### Ping
+
+- **Command:** `ping -c 4` (Linux/macOS) or `ping -n 4` (Windows)
+- **Purpose:** ICMP reachability
+- **Timeout:** 15 seconds
+
+### DNS
+
+- **Command:** `dig +short` (preferred) or `nslookup`
+- **Purpose:** Hostname resolution
+- **Timeout:** 10 seconds
+- **Note:** Requires `dig` or `nslookup` on your system
+
+### Port Check
+
+- **Command:** `nc -zv` (netcat) or Python socket fallback
+- **Purpose:** TCP connectivity
+- **Timeout:** 5 seconds
+- **Note:** Uses `nc` when available; otherwise uses a built-in socket check
+
+## Output
+
+### Console Output
+
+- **VPC Configuration** — VPC IDs, CIDR blocks, region
+- **IP Ranges** — VPC and subnet CIDRs with availability zones
+- **Validation Checks** — Table of checks with PASS/FAIL/WARN
+- **Connectivity Path** — Overall VALID or INVALID
+- **Local Network Tests** — Table of ping, DNS, and port results
+
+Failed network tests include the raw command output for debugging.
+
+### JSON Output
+
+Use `--json` for machine-readable output:
+
+```bash
+vpcrawler --vpc-a vpc-0abc123 --vpc-b vpc-0def456 --json
+```
+
+Structure:
+
+```json
+{
+  "config": {
+    "vpc_a": { "vpc_id": "...", "cidr_block": "...", "subnets": [...] },
+    "vpc_b": { "vpc_id": "...", "cidr_block": "...", "subnets": [...] },
+    "checks": [{ "name": "...", "status": "pass|fail|warn", "message": "..." }],
+    "connectivity_path_valid": true,
+    "error": null
+  },
+  "network_tests": [
+    { "test_type": "ping", "target": "...", "status": "pass", "message": "...", "duration_ms": 123 }
+  ]
+}
+```
+
+## AWS Permissions
+
+The tool uses these EC2 API operations:
+
+- `DescribeVpcs`
+- `DescribeSubnets`
+- `DescribeRouteTables`
+- `DescribeSecurityGroups`
+- `DescribeNetworkAcls`
+- `DescribeVpcPeeringConnections`
+- `DescribeTransitGatewayAttachments`
+- `DescribeInstances` (when using `--auto-test`)
+
+A minimal IAM policy:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ec2:DescribeVpcs",
+        "ec2:DescribeSubnets",
+        "ec2:DescribeRouteTables",
+        "ec2:DescribeSecurityGroups",
+        "ec2:DescribeNetworkAcls",
+        "ec2:DescribeVpcPeeringConnections",
+        "ec2:DescribeTransitGatewayAttachments",
+        "ec2:DescribeInstances"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+## Troubleshooting
+
+### "VPC(s) not found"
+
+- Confirm VPC IDs are correct
+- Ensure `--region` matches the VPCs
+- Verify AWS credentials and profile
+
+### "No active VPC peering or Transit Gateway connection"
+
+- Check that peering is in `active` state
+- For Transit Gateway, ensure both VPCs are attached to the same TGW
+
+### Ping/port checks fail from local machine
+
+- Private IPs are only reachable from within the VPC or via VPN/bastion
+- Ensure your machine has a path to the target (VPN, SSH tunnel, etc.)
+- Firewall or security groups may block ICMP or the tested ports
+
+### DNS resolution fails
+
+- `dig` or `nslookup` must be installed
+- Private hostnames require DNS resolution that can reach your private zones (e.g., Route 53 Resolver, VPN split-tunnel DNS)
+
+## Limitations
+
+- **Single region** — Both VPCs must be in the same region (cross-region peering not yet supported)
+- **Local tests** — Connectivity tests run from your machine; they do not test traffic between instances inside the VPCs
+- **Private IPs** — Auto-test uses private IPs; your machine must be able to reach them (VPN, etc.)
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+```
+
+### Project Structure
+
+```
+vpcrawler/
+├── src/aws_vpc_net_tester/
+│   ├── cli.py              # CLI entry point
+│   ├── config_validator.py # boto3 VPC analysis + EC2 discovery
+│   ├── models.py           # Data classes
+│   └── network_tester.py   # Ping, DNS, port checks
+├── tests/
+├── pyproject.toml
+└── requirements.txt
+```
+
+## Publishing to PyPI
+
+Releases are published automatically via [GitHub Actions](https://github.com/marketplace/actions/pypi-publish) when you push a version tag.
+
+### Setup (one-time)
+
+1. **Create a PyPI project** — Register `vpcrawler` on [pypi.org](https://pypi.org) if it does not exist.
+
+2. **Configure trusted publishing** — In your PyPI project settings, add a trusted publisher:
+   - Publisher: GitHub Actions
+   - Owner: your GitHub org/username
+   - Repository: your repo name
+   - Workflow: `publish.yml`
+   - Environment: `pypi`
+
+3. **Create the `pypi` environment** — In your GitHub repo: Settings → Environments → New environment → name it `pypi`.
+
+### Releasing
+
+1. Update the version in `pyproject.toml`.
+2. Commit, then create and push a tag:
+
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+3. The workflow builds the package and publishes to PyPI. No API tokens are required when using trusted publishing.

vpcrawler-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+aws_vpc_net_tester/__init__.py,sha256=n3kSbcrlYfswhECc3O8l_k9ifQhYSDBlvfPkMqR-XF8,59
+aws_vpc_net_tester/__main__.py,sha256=lZWyRP3_kCed7zfmMnBQCsnmioCEPvRJzLtjh-s6xuE,113
+aws_vpc_net_tester/cli.py,sha256=KhXfHFfG35YSnf0B4hOU12xMLaCpLHDn5FD8NEmQrck,7308
+aws_vpc_net_tester/config_validator.py,sha256=-PSJzOF-w02k9K048SXmvi8-I_swLOCYwIdZkWR20wM,15596
+aws_vpc_net_tester/models.py,sha256=yll4iEjy8XRv6YlGfFjjR7TedyfPvXdbvVpiNkO56Gc,3109
+aws_vpc_net_tester/network_tester.py,sha256=kiYCzDHjjZaOBXkMghm26mmwHV1oNacq8iAtzD-3hCk,5280
+vpcrawler-0.1.0.dist-info/METADATA,sha256=Te7c5_SwHZxw6rZkBN2ZujNNafBsffav_FanK2Kt8O0,11395
+vpcrawler-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+vpcrawler-0.1.0.dist-info/entry_points.txt,sha256=TI8qKVzTP1w4hpPcB_mrvkKsUPUuC55SK0ydVLQCAJU,57
+vpcrawler-0.1.0.dist-info/top_level.txt,sha256=IIfuJwiw1qmBwfqZXmNfvMB0WbSR-OR23yxj8ObvgFc,19
+vpcrawler-0.1.0.dist-info/RECORD,,

vpcrawler-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vpcrawler-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vpcrawler = aws_vpc_net_tester.cli:app

vpcrawler-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aws_vpc_net_tester