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](../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.

```bash
# 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](Configuration.md#data-storage-options) 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](AWS-Configuration.md#required-iam-permissions) 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**:
```bash
docker run --rm -v sgo-data:/data -v $(pwd):/backup alpine tar czf /backup/sgo-backup.tar.gz -C /data .
```

**Local directory backup**:
```bash
cp ./data/aws_export.db ./backups/
```

### How do I clear all data?

**Remove database and start fresh**:
```bash
# 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](Troubleshooting.md) 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](../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?

```bash
# 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:
```bash
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](Troubleshooting.md)
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.