# 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

```bash
# 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

```bash
# Docker
docker-compose up --build

# Podman
podman-compose up --build
```

### Environment Variables

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

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

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

Or create it manually:

```bash
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](LICENSE) file for full details.

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