Skip to main content

​
Prerequisites

Before installing AWS Security Group Auditor, ensure you have the following:
  • Python 3.x: The tool requires Python 3 or higher
  • AWS Account: An active AWS account with security groups to audit
  • AWS Permissions: IAM permissions to read security groups and various AWS services
You’ll need read permissions for EC2, ELB, RDS, ECS, EKS, and other AWS services the tool audits. For deletion capabilities, you’ll also need ec2:DeleteSecurityGroup permission.

​
Install dependencies

The AWS Security Group Auditor uses boto3, the AWS SDK for Python, to interact with AWS services.
1

Install boto3

Install boto3 using pip:
pip install boto3
If you’re using Python 3 specifically, use pip3 to ensure boto3 is installed for the correct Python version.
2

Verify installation

Verify that boto3 was installed successfully:
python3 -c "import boto3; print(boto3.__version__)"
You should see the boto3 version number printed to the console.

​
Configure AWS credentials

The tool uses boto3’s standard credential chain to authenticate with AWS. You need to configure your AWS credentials before running the auditor.
1

Choose a credential method

Boto3 supports multiple authentication methods. Choose the one that best fits your environment:
  • AWS CLI configuration files (recommended for local development)
  • Environment variables
  • IAM roles (recommended for EC2 instances)
  • AWS SSO
2

Configure using AWS CLI (recommended)

The easiest method is using the AWS CLI to configure credentials:
aws configure
Enter your credentials when prompted:
AWS Access Key ID [None]: YOUR_ACCESS_KEY
AWS Secret Access Key [None]: YOUR_SECRET_KEY
Default region name [None]: us-east-1
Default output format [None]: json
This creates credential files at ~/.aws/credentials and ~/.aws/config.
3

Alternative: Use environment variables

You can also set credentials using environment variables:
export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
export AWS_DEFAULT_REGION=us-east-1
4

Verify AWS access

Test your credentials by checking your account identity:
aws sts get-caller-identity
You should see output containing your account ID, user ID, and ARN.
Never commit AWS credentials to version control. Use environment variables, credential files, or IAM roles instead of hardcoding credentials.

​
Download the tool

Download or clone the check_sg_usage.py script to your local environment: 
# If using git
git clone <repository-url>
cd AWS-SecurityGroup-Auditor

# Or download the script directly
curl -O <script-url>/check_sg_usage.py

​
Verify installation

Ensure the script is executable and your environment is properly configured:
1

Check Python version

python3 --version
Verify you’re running Python 3.x or higher.
2

Test boto3 and AWS connection

Run a quick test to verify boto3 can connect to AWS:
python3 -c "import boto3; print('Account:', boto3.client('sts').get_caller_identity()['Account'])"
This should print your AWS account ID.
3

Check script permissions

Ensure the script is readable:
ls -l check_sg_usage.py

​
Required IAM permissions

Your AWS credentials need the following permissions to run the auditor: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeInstances",
        "ec2:DescribeVpcEndpoints",
        "ec2:DescribeVpnConnections",
        "ec2:DescribeCustomerGateways",
        "elasticloadbalancing:DescribeLoadBalancers",
        "rds:DescribeDBInstances",
        "ecs:ListClusters",
        "ecs:ListServices",
        "ecs:DescribeServices",
        "eks:ListClusters",
        "eks:ListNodegroups",
        "eks:DescribeNodegroup",
        "codebuild:ListProjects",
        "codebuild:BatchGetProjects",
        "redshift:DescribeClusters",
        "elasticache:DescribeCacheClusters",
        "kafka:ListClusters",
        "neptune:DescribeDBInstances",
        "docdb:DescribeDBClusters",
        "elasticbeanstalk:DescribeEnvironments",
        "elasticbeanstalk:DescribeEnvironmentResources",
        "sagemaker:ListEndpoints",
        "sagemaker:DescribeEndpoint",
        "transfer:ListServers",
        "transfer:DescribeServer",
        "glue:GetJobs",
        "glue:GetConnection",
        "es:ListDomainNames",
        "es:DescribeElasticsearchDomain",
        "mq:ListBrokers",
        "mq:DescribeBroker",
        "fsx:DescribeFileSystems",
        "workspaces:DescribeWorkspaceDirectories",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "ec2:DeleteSecurityGroup",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "ec2:ResourceTag/ManagedBy": "YourTeam"
        }
      }
    }
  ]
}
The deletion permission includes a condition tag as an example. Adjust this to match your organization’s security policies.

​
Next steps

You’re now ready to run your first security group audit! Continue to the Quick Start guide to learn how to use the tool.

Quick start guide

Run your first audit and identify unused security groups

Build docs developers (and LLMs) love

Get started for freeTalk to us