141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
# 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.
|