eddie/SGO
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

simple readme

Browse source
This commit is contained in:
Eduardo Figueroa 2025-11-20 14:32:14 -08:00
parent e38d74f6d8
commit ff19326100
No known key found for this signature in database
GPG key ID: E4B7BBE6F7D53330
1 changed files with 6 additions and 261 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

267
README.md
View file

@ -5,21 +5,18 @@ A web-based tool for exploring AWS EC2 instances and Security Groups with direct
## Quick Start ## Quick Start
```bash ```bash
# 1. Create .env file with your AWS credentials path 1. Setup container files
cat > .env << EOF wget https://codeberg.org/edfig/SGO/src/branch/main/docker-compose.yml
AWS_CONFIG_PATH=$HOME/.aws cp .env.example .env
PUID=$(id -u) # edit the .env as needed
PGID=$(id -g)
EOF
# 2. Start the container # 2. Start the container
docker-compose up --build docker-compose up
# or with Podman: # or with Podman:
podman-compose up --build podman-compose up
# 3. Open browser to http://localhost:5000 # 3. Open browser to http://localhost:5000
# 4. Select AWS profiles, enter MFA codes, and import!
``` ```
## ⚠️ Security Warning ## ⚠️ Security Warning
@ -33,62 +30,8 @@ podman-compose up --build
**Always run on localhost (127.0.0.1) only. Never expose port 5000 to external networks.** **Always run on localhost (127.0.0.1) only. Never expose port 5000 to external networks.**
## 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 ### 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:** **Available Options:**
| Variable | Description | Required | Default | | Variable | Description | Required | Default |
@ -101,204 +44,6 @@ EOF
| `DEBUG` | Enable Flask debug logging | No | `false` | | `DEBUG` | Enable Flask debug logging | No | `false` |
| `FLASK_ENV` | Flask environment | No | `production` | | `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`:
```bash
docker-compose -f docker-compose.local.yml up --build
# or
podman-compose -f docker-compose.local.yml up --build
```
Or edit `docker-compose.yml` and swap the volume configuration as indicated in comments.
### User/Group Configuration
To avoid permission issues, set `PUID` and `PGID` to match your host user:
```bash
# Find your IDs
id -u # Your PUID
id -g # Your PGID
# Add to .env file
echo "PUID=$(id -u)" >> .env
echo "PGID=$(id -g)" >> .env
```
### Stopping the Application
```bash
# Stop with Ctrl+C, or:
docker-compose down # Docker
podman-compose down # Podman
# To also remove the data volume:
docker-compose down -v
```
## Quick Start (Local Python)
If you prefer to run without containers:
### 1. Install Dependencies
```bash
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```
### 2. Start the Application
```bash
python app.py
```
### 3. Open Browser
Navigate to `http://localhost:5000`
## Important Notes
- **⚠️ LOCAL USE ONLY**: Never expose this application to the internet. It has no authentication and provides access to sensitive AWS data.
- **Database Persistence**: When using containers, the database persists in the `./data` directory
- **Session Caching**: AWS sessions are cached for 55 minutes, allowing multiple refreshes without re-authentication
- **Parallel Import**: All selected AWS accounts are imported simultaneously for maximum speed
## AWS Configuration
### MFA Device Setup
For profiles that require MFA, add your MFA device ARN to `~/.aws/config`:
```ini
[profile nonprod-p1p2-admin]
region = us-west-2
mfa_serial = arn:aws:iam::131340773912:mfa/your-username
```
### Finding Your MFA Device ARN
1. Go to AWS IAM Console
2. Navigate to Users → Your User → Security Credentials
3. Copy the ARN from "Assigned MFA device"
### How MFA Works in the GUI
1. The import page shows all profiles from `~/.aws/config`
2. Select the profiles you want to import
3. Enter MFA codes in the text boxes (one per profile)
4. Click "Start Import" to begin
5. Real-time progress shows authentication and data fetching
6. MFA session is valid for 1 hour - refresh without re-entering codes during this window
## Usage
### Search
1. Type in the search box (minimum 2 characters)
2. Results appear instantly as you type
3. Filter by resource type using the buttons: **All Resources** | **EC2 Instances** | **Security Groups**
4. **Enable Regex**: Check the "Regex" box to use regular expressions
- Example: `^prod-.*-\d+$` finds names starting with "prod-" and ending with numbers
- Example: `(dev|test|qa)` finds names containing dev, test, or qa
- Example: `10\.0\.\d+\.\d+` finds IP addresses in the 10.0.x.x range
### View Details
**EC2 Instance View:**
- Click on any EC2 instance from search results
- Main card shows EC2 details (Instance ID, IP, State, Account, Tags)
- Nested cards show all attached Security Groups with their details
**Security Group View:**
- Click on any Security Group from search results
- Main card shows SG details (Group ID, Name, Ingress Rules, Wave, Tags)
- Nested cards show all EC2 instances using this Security Group
### View Security Group Rules
When viewing security groups (either attached to an EC2 or directly):
1. Click the **View Rules** button on any security group card
2. A modal opens showing all ingress and egress rules
3. Switch between **Ingress** and **Egress** tabs
4. Use the search box to filter rules by protocol, port, source, or description
5. Rules are displayed in a compact table format with:
- Protocol (TCP, UDP, ICMP, All)
- Port Range
- Source Type (CIDR, Security Group, Prefix List)
- Source (IP range or SG ID)
- Description
### Navigate
- Click **← Back to Search** to return to search results
- Perform a new search at any time
- Click outside the rules modal to close it
### Export to CSV
SGO provides comprehensive CSV export capabilities:
**Search Results Export:**
- Click the **💾 Export** button in the view controls (top right)
- Exports all current search results with filters applied
- Includes: Type, Name, ID, Account, State, IP, Security Groups count, Wave, Git info
**EC2 Instance Details Export:**
- Click the **💾 Export** button in any EC2 detail card
- Exports complete EC2 information including:
- Instance details (ID, name, state, IP, account info)
- All AWS tags
- Attached security groups with their details
**Security Group Details Export:**
- Click the **💾 Export** button in any SG detail card
- Exports complete SG information including:
- Group details (ID, name, wave, rule counts)
- All AWS tags
- Attached EC2 instances with their details
**Security Group Rules Export:**
- Click the **💾 Export** button in the rules modal
- Exports all ingress and egress rules with:
- Rule details (direction, protocol, ports, source)
- Group ID, account ID
- Git file and commit information from tags
All exports include timestamps in filenames and proper CSV escaping.
## Data Structure
### Security Groups Table
- Account ID & Name
- Group ID & Name
- Tag Name
- Wave Tag
- Git Repo Tag
- Ingress Rule Count
### EC2 Instances Table
- Account ID & Name
- Instance ID
- Tag Name
- State (running, stopped, etc.)
- Private IP Address
- Security Groups (IDs and Names)
- Git Repo Tag
## File Structure ## File Structure