SGO/wiki/FAQ.md

Frequently Asked Questions (FAQ)

General Questions

What is SGO?

SGO (Security Groups Observatory) is a web-based tool for exploring and analyzing AWS EC2 instances and Security Groups. It provides search, filtering, detailed views, and CSV export capabilities for AWS infrastructure.

Is SGO free to use?

Yes, for personal, educational, and non-commercial use. Commercial use by businesses requires a paid license. See LICENSE for details.

Can I use SGO in production?

No, not recommended. SGO is designed for local use only and has no authentication mechanisms. It should never be exposed to the internet or production networks.

What AWS services does SGO support?

Currently, SGO supports:

• EC2 Instances
• Security Groups (with ingress/egress rules)

Future versions may add support for additional AWS services.

Installation & Setup

Do I need Docker or Podman?

Not required, but strongly recommended. You can run SGO with local Python, but containers provide easier setup and better isolation.

What are PUID and PGID?

PUID (Process User ID) and PGID (Process Group ID) ensure files created by the container have correct ownership on your host system. Set them to your user's UID/GID to avoid permission issues.

# Find your values
id -u  # PUID
id -g  # PGID

Can I use Docker volume or local directory for data?

Both are supported:

• Docker volume (default): Better for macOS/Windows, managed by Docker
• Local directory: Better for development, easy to backup

See Configuration for details.

Where are my AWS credentials stored?

AWS credentials are NOT stored by SGO. The application reads from your existing ~/.aws/ directory and only keeps temporary session tokens in memory (cached for 55 minutes).

AWS & Authentication

Do I need MFA?

Only if your AWS profile requires it. If your ~/.aws/config has mfa_serial configured for a profile, you'll need to provide an MFA code when importing.

How long does MFA session last?

AWS MFA sessions last 1 hour. SGO caches them for 55 minutes, allowing you to refresh data multiple times without re-entering MFA codes.

Can I import multiple AWS accounts?

Yes! SGO supports multiple profiles and can import them in parallel. Select all desired profiles and start imports simultaneously for maximum efficiency.

What AWS permissions do I need?

Minimum required permissions:

• ec2:DescribeInstances
• ec2:DescribeSecurityGroups
• iam:ListAccountAliases
• sts:GetCallerIdentity

See AWS Configuration for details.

Why can't I see my resources?

Common causes:

1. Wrong region: EC2 resources are region-specific
2. No permission: Verify IAM permissions
3. Import failed: Check import progress logs for errors
4. Different account: Ensure you're importing the correct profile

Features & Usage

How do I search for resources?

Type in the search box (minimum 2 characters). Search works across:

• EC2 instance names and IDs
• Security group names and IDs
• IP addresses
• Tags

Enable "Regex" checkbox for pattern matching.

What's the difference between EC2 view and SG view?

• EC2 view: Shows instance details with nested Security Groups
• SG view: Shows security group details with nested EC2 instances

Both views are interactive - click any item to see its details.

Can I export my data?

Yes! SGO provides CSV export at multiple levels:

• Search results
• Individual EC2 instance details
• Individual Security Group details
• Security group rules

All exports include proper CSV formatting and timestamps.

Does SGO modify my AWS resources?

No. SGO is read-only and never modifies AWS resources. It only uses Describe* and List* API calls.

Performance

How fast is the import?

Import speed depends on:

• Number of resources in your AWS account
• Network latency to AWS
• Number of accounts being imported

Parallel import significantly reduces total time by importing multiple accounts simultaneously.

Why is search slow with many resources?

Search is client-side (in your browser) for instant results. With thousands of resources, this can be slower. Tips:

• Use more specific search terms
• Use type filters (EC2 only, SG only)
• Disable regex when not needed

Can I improve performance?

Yes:

• Use Docker volume instead of local directory (better I/O)
• Import selectively: Only import accounts you need
• Use specific searches: Narrow down results
• Use type filters: Filter by EC2 or SG only

Data & Privacy

Is my data sent anywhere?

No. SGO runs entirely locally. Data flows:

1. AWS → Your local SGO instance
2. Stored in local SQLite database
3. Never leaves your machine

Can others see my AWS data?

Only if they have access to:

• Your computer while SGO is running
• Your SQLite database file
• Your Docker volume

Never expose SGO to the internet.

How is data stored?

Data is stored in a local SQLite database:

• Default location: Docker volume sgo-data
• Alternative: ./data/aws_export.db (local mode)

Can I backup my data?

Yes:

Docker volume backup:

docker run --rm -v sgo-data:/data -v $(pwd):/backup alpine tar czf /backup/sgo-backup.tar.gz -C /data .

Local directory backup:

cp ./data/aws_export.db ./backups/

How do I clear all data?

Remove database and start fresh:

# Docker volume mode
docker-compose down -v

# Local directory mode
rm -rf ./data

Troubleshooting

Import fails silently

Check the import progress logs in the UI. Common issues:

• Invalid AWS credentials
• Expired MFA code
• Missing IAM permissions
• Network connectivity

Container won't start

Common causes:

1. Port 5000 already in use
2. Docker/Podman not running
3. Missing .env file
4. Invalid AWS_CONFIG_PATH

See Troubleshooting for detailed solutions.

AWS profiles not showing up

Ensure:

• ~/.aws/config exists and is readable
• Profiles are properly formatted
• AWS_CONFIG_PATH in .env is correct
• Container has been restarted after config changes

Development & Customization

Can I modify SGO?

Yes, under the license terms:

• ✅ Modify for personal use
• ✅ Contribute improvements back
• ❌ Modify to sell or redistribute commercially

Can I contribute to SGO?

Yes! Contributions are welcome. See CONTRIBUTING.md for guidelines.

Does SGO support other clouds?

Not currently. SGO is AWS-specific. Support for other cloud providers may be added in the future.

Can I add custom tags or fields?

SGO imports all AWS tags automatically. Custom application-level tags are not currently supported but could be added in future versions.

Security

Is SGO secure?

SGO is secure for local use only:

• ✅ Read-only access to AWS
• ✅ Uses standard AWS SDK authentication
• ✅ Local data storage
• ❌ NO authentication/authorization
• ❌ NOT safe for network exposure

Should I use SGO on a shared server?

No. Use SGO only on your personal workstation. Anyone with access to the running application can view all imported AWS data.

Can I add authentication?

Not currently supported. SGO is designed for single-user local use. Adding authentication would significantly complicate the setup for the primary use case.

What about HTTPS?

Not needed for local use. Since SGO runs on localhost and should never be exposed to networks, HTTPS is unnecessary.

Updates & Versioning

How do I update SGO?

# Pull latest changes
git pull

# Rebuild container
docker-compose down
docker-compose up --build

Will updates break my data?

Database schema is designed for forward compatibility. Major version updates will include migration instructions if needed.

How do I check my version?

Check the repository for version tags or commits:

git log -1 --oneline

License & Commercial Use

Can my company use SGO?

Commercial use requires a paid license. Open an issue in the repository for licensing inquiries.

What counts as commercial use?

Using SGO at a company, for business purposes, or as part of commercial operations requires a license. Personal/educational use is free.

Can I sell a modified version?

No. The license explicitly prohibits modifying SGO for resale or commercial distribution.

Getting More Help

Where can I get support?

1. Check this FAQ
2. Read Troubleshooting
3. Search existing issues in the repository
4. Open a new issue with details

How do I report a bug?

Open an issue in the repository with:

• Description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Logs from docker-compose logs
• Your environment (OS, Docker version)

Can I request features?

Yes! Open a feature request issue. Include:

• Use case description
• Why the feature is needed
• How you envision it working

Is there a community chat?

Check the repository for links to community discussions or chat platforms.