# Clone or download repository
cd sg-auditor

# Create virtual environment with Python 3.10+
python3.11 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

aws configure

export AWS_ACCESS_KEY_ID="your_key"
export AWS_SECRET_ACCESS_KEY="your_secret"
export AWS_DEFAULT_REGION="us-east-1"

ANTHROPIC_API_KEY=sk-ant-xxx

# Audit default region
python audit.py

# Audit specific region
python audit.py --region us-west-2

# Skip AI analysis
python audit.py --no-ai

# Custom output directory
python audit.py --output-dir /path/to/reports

{
  "mcpServers": {
    "security-group-auditor": {
      "command": "/path/to/sg-auditor/venv/bin/python",
      "args": ["/path/to/sg-auditor/src/mcp_server.py"]
    }
  }
}

from src.audit_core import run_audit

result = run_audit(region='us-east-1')
print(f"Findings: {result['summary']['total_findings']}")

sg-auditor/
├── audit.py                 # CLI entry point
├── requirements.txt         # Python dependencies
├── src/
│   ├── audit_core.py       # Core audit logic (shared)
│   ├── sg_collector.py     # AWS Security Group collector (boto3)
│   ├── rule_analyzer.py    # Dangerous rule detector
│   ├── ai_agent.py         # Optional AI analysis (CLI only)
│   ├── mcp_server.py       # MCP server (Claude Desktop)
│   └── report_generator.py # Markdown report generator
└── reports/                # Generated audit reports

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ec2:DescribeSecurityGroups",
      "ec2:DescribeRegions"
    ],
    "Resource": "*"
  }]
}

python audit.py --region us-east-1 --no-ai
if [ $? -eq 2 ]; then
    echo "CRITICAL findings - blocking deployment"
    exit 1
fi

for region in us-east-1 us-west-2 eu-west-1; do
    python audit.py --region $region
done

sts = boto3.client('sts')
assumed_role = sts.assume_role(
    RoleArn='arn:aws:iam::ACCOUNT_ID:role/SecurityAuditor',
    RoleSessionName='SecurityAudit'
)
credentials = assumed_role['Credentials']
self.ec2_client = boto3.client(
    'ec2',
    aws_access_key_id=credentials['AccessKeyId'],
    aws_secret_access_key=credentials['SecretAccessKey'],
    aws_session_token=credentials['SessionToken']
)

CRITICAL_PORTS = {
    22: "SSH",
    3389: "RDP",
    8080: "Custom Application",
}