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.

4.5 KiB Raw Blame History