Skip to main content

​
Overview

This guide will walk you through running your first security group audit using AWS Security Group Auditor. You’ll learn how to execute the tool, interpret the results, and safely clean up unused security groups.
Before starting, make sure you’ve completed the installation steps and configured your AWS credentials.

​
Running your first audit

1

Navigate to the script directory

Open your terminal and navigate to the directory containing check_sg_usage.py:
cd /path/to/AWS-SecurityGroup-Auditor
2

Execute the auditor

Run the script using Python 3:
python3 check_sg_usage.py
The tool will immediately start the audit process.
3

Monitor the audit progress

As the script runs, you’ll see real-time output showing:
  • Your AWS account ID
  • Progress indicators for each security group
  • Associated resources for each security group
Example output:
Verificación de uso de grupos de seguridad para la cuenta AWS: 123456789012
------------------------------------------------
Revisando el grupo de seguridad (1/45): sg-0abc123def456 (Web Server Security Group)
    Instancia EC2 asociada: i-0abc123def, Estado: running
    ALB/NLB Asociado: my-application-lb
------------------------------------------------
Revisando el grupo de seguridad (2/45): sg-0def456abc789 (Database Security Group)
    Instancia RDS Asociada: my-database-instance
    Referenciado por otros SGs: sg-0abc123def456
------------------------------------------------
Revisando el grupo de seguridad (3/45): sg-0ghi789jkl012 (Old Dev Environment)
4

Review the log file

The tool automatically generates a detailed log file named {account_id}_sg_log.txt in the same directory.
cat 123456789012_sg_log.txt
This file contains the complete audit results for future reference.
5

Review unused security groups

After auditing all security groups, the tool displays a summary:
***RESULTADO***

Los siguientes grupos de seguridad no tienen recursos asociados: sg-0ghi789jkl012, sg-0mno345pqr678
These are security groups with no attached resources or references.
6

Decide on deletion (optional)

The tool will prompt you to confirm deletion:
¿Quieres borrar estos grupos de seguridad? (sí/no):
To delete unused security groups, type sí, si, s, yes, or y and press Enter.To keep them, type no or n and press Enter.
Deletion is immediate and cannot be undone. Always review the log file before confirming deletion.
7

Confirm deletion results

If you chose to delete, you’ll see confirmation for each security group:
Grupo de seguridad sg-0ghi789jkl012 borrado exitosamente.
Grupo de seguridad sg-0mno345pqr678 borrado exitosamente.
Or error messages if deletion fails:
Error al borrar el grupo de seguridad sg-0xyz: An error occurred (DependencyViolation)...

​
Understanding the output

The auditor checks each security group against 25+ AWS services. Here’s what different output messages mean:

​
Resource associations

When a security group is in use, you’ll see lines like:
OutputMeaning
Instancia EC2 asociada: i-0abc123def, Estado: runningAttached to an EC2 instance
ALB/NLB Asociado: my-load-balancerAttached to an Application/Network Load Balancer
ELB Clásico Asociado: my-classic-lbAttached to a Classic Load Balancer
Instancia RDS Asociada: my-databaseAttached to an RDS database
ECS Servicio Asociado: my-service en Cluster: arn:aws:ecs:...Attached to an ECS service
Referenciado por otros SGs: sg-0abc123, sg-0def456Referenced by other security groups
VPC Endpoint con SG: vpce-0abc123Attached to a VPC endpoint

​
No associations

If a security group has no output after its header, it means no resources are using it.

​
Common use cases

​
Audit-only mode

Run the tool to generate a report without deleting anything: 
python3 check_sg_usage.py
When prompted to delete, answer no. You’ll have a complete audit log without making changes.

​
Scheduled audits

Run regular audits to track security group usage over time: 
# Run weekly audit and save with timestamp
python3 check_sg_usage.py
mv *_sg_log.txt "sg_audit_$(date +%Y%m%d).txt"

​
Pre-cleanup review

Before cleaning up, review the log file to understand dependencies: 
python3 check_sg_usage.py
# Review the log
less *_sg_log.txt
# Run again and confirm deletion
python3 check_sg_usage.py

​
Services checked

The auditor examines security group associations across these services:

Compute

  • EC2 instances
  • ECS services
  • EKS node groups
  • Elastic Beanstalk

Databases

  • RDS instances
  • Neptune
  • DocumentDB clusters
  • Redshift clusters
  • ElastiCache

Networking

  • ELB (Classic)
  • ALB/NLB (ELBv2)
  • VPC Endpoints
  • VPN Connections

Analytics

  • Amazon MSK (Kafka)
  • Glue jobs
  • Elasticsearch

Development

  • CodeBuild projects
  • SageMaker endpoints

Other

  • FSx file systems
  • Amazon MQ brokers
  • Transfer Family
  • WorkSpaces

​
Troubleshooting

​
Permission errors

If you see permission errors, ensure your IAM user or role has the required read permissions: 
botocore.exceptions.ClientError: An error occurred (AccessDenied)
Solution: Review the IAM permissions section and update your policy.

​
Deletion failures

Some security groups cannot be deleted due to dependencies: 
Error al borrar el grupo de seguridad sg-xxx: An error occurred (DependencyViolation)
Common causes:
  • Security group is referenced by another security group’s rules
  • Resource using it was created after the audit started
  • Default VPC security group (cannot be deleted)
Solution: Review the log file to identify dependencies, or run the audit again to get updated information.

​
No output or hanging

If the script appears to hang on certain services:
  • Large AWS accounts may take time to audit all resources
  • Some services (like ECS) require pagination and may take longer
  • Network issues can cause timeouts
Solution: Be patient, or check your AWS region and network connectivity.

​
Best practices

Run audits regularly: Schedule monthly or quarterly audits to keep security groups clean and organized.
Review before deletion: Always examine the log file before confirming any deletions to avoid accidentally removing security groups you need.
Test in non-production first: Run your first audit in a development or staging account to understand the tool’s behavior.
Backup your configuration: Consider exporting security group configurations before deletion, especially in production environments.

​
Next steps

Now that you’ve completed your first audit, consider:
  • Setting up automated audits using cron or AWS Lambda
  • Integrating the tool into your infrastructure-as-code workflows
  • Creating custom reports from the log files
  • Implementing tagging strategies to track security group ownership

View source code

Explore the full source code and contribute to the project

Build docs developers (and LLMs) love

Get started for freeTalk to us