SGO: Security Groups Observatory

A web-based tool for exploring AWS EC2 instances and Security Groups with direct AWS import, MFA support, and CSV export capabilities.

Quick Start

# 1. Create .env file with your AWS credentials path
cat > .env << EOF
AWS_CONFIG_PATH=$HOME/.aws
PUID=$(id -u)
PGID=$(id -g)
EOF

# 2. Start the container
docker-compose up --build
# or with Podman:
podman-compose up --build

# 3. Open browser to http://localhost:5000

# 4. Select AWS profiles, enter MFA codes, and import!

Features

• Direct AWS Import: Import data directly from AWS using ~/.aws/config with MFA/OTP support
• Parallel Import: Import from multiple AWS accounts simultaneously
• Search & Filter: Search by EC2 name, SG name, instance ID, group ID, or IP address
• Regex Search: Enable regex checkbox for advanced pattern matching
• Filter by Type: View all resources, only EC2 instances, or only Security Groups
• CSV Export: Export search results, EC2 details, SG details, and security group rules to CSV
• Detailed Views:
  • EC2 View: Shows EC2 instance details with nested boxes for attached Security Groups
  • Security Group View: Shows SG details with nested boxes for all attached EC2 instances
• Security Group Rules: View and search ingress/egress rules for any security group
• Statistics Dashboard: Quick overview of total SGs, EC2s, and accounts

Quick Start (Container - Recommended)

The easiest way to run SGO is using Docker or Podman. Works on Linux, macOS, and Windows.

Prerequisites

Install either:

• Docker: https://docs.docker.com/get-docker/
• Podman: https://podman.io/getting-started/installation

Run the Application

# Docker
docker-compose up --build

# Podman
podman-compose up --build

Environment Variables

SGO supports configuration through environment variables. Create a .env file:

# Copy the example file
cp .env.example .env

# Edit with your settings
nano .env  # or your preferred editor

Or create it manually:

cat > .env << EOF
AWS_CONFIG_PATH=$HOME/.aws
PUID=$(id -u)
PGID=$(id -g)
EOF

Available Options:

Variable	Description	Required	Default
AWS_CONFIG_PATH	Absolute path to AWS credentials directory	Yes	None
PUID	User ID for file permissions	No	1000
PGID	Group ID for file permissions	No	1000
DATA_PATH	Path for database storage (local mode)	No	./data
SGO_PORT	Port to expose on host	No	5000
DEBUG	Enable Flask debug logging	No	false
FLASK_ENV	Flask environment	No	production

Data Storage Options

Option 1: Docker Volume (Default - Recommended)

• Data stored in Docker-managed volume sgo-data
• Survives container restarts and rebuilds
• Better performance on macOS/Windows
• Use default docker-compose.yml

Option 2: Local Directory

• Data stored in ./data directory
• Easy to backup and access
• Better for development
• Use docker-compose.local.yml:

File Structure

sgo/
├── app.py                      # Flask web application
├── import_from_aws.py          # AWS direct import functions
├── requirements.txt            # Python dependencies
├── Dockerfile                  # Container image definition
├── docker-compose.yml          # Container orchestration (Docker volume)
├── docker-compose.local.yml    # Alternative with local directory storage
├── entrypoint.sh               # Container entrypoint with PUID/PGID support
├── .dockerignore               # Files to exclude from container
├── .env.example                # Example environment configuration
├── .gitignore                  # Git ignore patterns
├── README.md                   # This file
├── data/                       # Local data directory (if using local mode)
│   └── aws_export.db           # SQLite database
├── static/                     # CSS and images
└── templates/                  # HTML

License

This project is dual-licensed:

• FREE for individual, personal, educational, and non-commercial use
• PAID LICENSE REQUIRED for commercial use by businesses and organizations

You may NOT modify this software for the purpose of selling or commercially distributing it.

See the LICENSE file for full details.

For commercial licensing inquiries, please open an issue in this repository.