osmedeus/docs/cloud/cloud-usage-examples.md

# Cloud Usage Examples

Practical examples for running distributed security scans and custom commands on cloud infrastructure.

## Getting Started

### First Scan in 5 Minutes

```bash
# Step 0: Enable cloud feature
osmedeus config set cloud.enabled true

# Step 1: Configure AWS credentials
osmedeus cloud config set providers.aws.access_key_id ${AWS_ACCESS_KEY_ID}
osmedeus cloud config set providers.aws.secret_access_key ${AWS_SECRET_ACCESS_KEY}
osmedeus cloud config set providers.aws.region ap-southeast-1
osmedeus cloud config set defaults.provider aws

# Step 2: SSH keys
osmedeus cloud config set ssh.private_key_path ~/.ssh/id_rsa
osmedeus cloud config set ssh.public_key_path ~/.ssh/id_rsa.pub

# Step 3: Clean the setup scripts first, then add setup commands for workers
osmedeus cloud config set setup.commands.clear ""
osmedeus cloud config set setup.commands.add "curl -fsSL https://www.osmedeus.org/install.sh | bash"
osmedeus cloud config set setup.commands.add "osmedeus install base --preset"

# Step 4: Run your first scan
osmedeus cloud run -f fast -t example.com --auto-destroy
```

This provisions 1 AWS instance, installs osmedeus + tools, runs the `fast` flow against `example.com`, streams output to your terminal, and destroys the instance when done.

### Verify Configuration

```bash
# View all settings
osmedeus cloud config list

# View with secrets visible
osmedeus cloud config list --show-secrets
```

## Workflow Mode Examples

### Single Target

```bash
# Run a flow
osmedeus cloud run -f fast -t example.com

# Run a specific module
osmedeus cloud run -m enum-subdomain -t example.com

# With timeout
osmedeus cloud run -f general -t example.com --timeout 2h

# With specific provider
osmedeus cloud run -f fast -t example.com --provider digitalocean
```

### Multiple Targets

```bash
# Distribute targets across 5 workers
osmedeus cloud run -f fast -T targets.txt --instances 5

# 10 targets per worker (auto-calculates worker count)
osmedeus cloud run -f fast -T targets.txt --instances 10 --chunk-size 10

# Split into exactly 3 chunks
osmedeus cloud run -f fast -T targets.txt --instances 5 --chunk-count 3
```

### Full Lifecycle

```bash
# Provision, scan, sync results back, then destroy
osmedeus cloud run -f fast -t example.com --sync-back --auto-destroy

# Same with multiple targets
osmedeus cloud run -f fast -T targets.txt --instances 3 --sync-back --auto-destroy
```

### Reusing Infrastructure

```bash
# First run: provision and scan
osmedeus cloud run -f fast -t target1.com

# Second run: reuse same instances for a different target
osmedeus cloud run -f fast -t target2.com --reuse

# Reuse specific machines by IP
osmedeus cloud run -f fast -t target3.com --reuse-with "1.2.3.4,5.6.7.8"

# When done, destroy manually
osmedeus cloud destroy <infra-id>
```

## Custom Command Examples

### Basic Usage

```bash
# Run a single command
osmedeus cloud run --custom-cmd "nmap -sV {{Target}}" -t example.com

# Run on existing infrastructure
osmedeus cloud run --custom-cmd "whoami && id" -t example.com --reuse
```

### Recon Pipeline

```bash
# Subdomain enumeration → HTTP probing → screenshot
osmedeus cloud run \
  --custom-cmd "subfinder -d {{Target}} -o /tmp/osm-custom/subs.txt" \
  --custom-cmd "cat /tmp/osm-custom/subs.txt | httpx -o /tmp/osm-custom/live.txt" \
  --custom-cmd "cat /tmp/osm-custom/live.txt | gowitness scan -o /tmp/osm-custom/screenshots" \
  --sync-path "/tmp/osm-custom/" \
  -t example.com --auto-destroy
```

### Vulnerability Scanning

```bash
# Nuclei scan with custom templates
osmedeus cloud run \
  --custom-cmd "nuclei -u {{Target}} -t cves/ -o /tmp/osm-custom/cves.txt" \
  --custom-cmd "nuclei -u {{Target}} -t exposures/ -o /tmp/osm-custom/exposures.txt" \
  --custom-post-cmd "cat /tmp/osm-custom/cves.txt /tmp/osm-custom/exposures.txt | sort -u > /tmp/osm-custom/all-findings.txt" \
  --sync-path "/tmp/osm-custom/all-findings.txt" \
  -t example.com
```

### Port Scanning at Scale

```bash
# Distribute an IP list across 10 workers for masscan + nmap
osmedeus cloud run \
  --custom-cmd "cat {{Target}} | while read ip; do masscan \$ip -p1-65535 --rate 1000 -oG /tmp/osm-custom/masscan-\$(echo \$ip | tr '.' '-').txt; done" \
  --custom-post-cmd "cat /tmp/osm-custom/masscan-*.txt > /tmp/osm-custom/all-ports.txt" \
  --sync-path "/tmp/osm-custom/" \
  -T ip-list.txt --instances 10 --auto-destroy
```

### SAST Scanning

```bash
# Clone a repo and run semgrep
osmedeus cloud run \
  --custom-cmd "git clone https://github.com/org/repo.git /tmp/osm-custom/repo" \
  --custom-cmd "semgrep --config auto /tmp/osm-custom/repo --sarif -o /tmp/osm-custom/semgrep.sarif" \
  --sync-path "/tmp/osm-custom/semgrep.sarif" \
  -t org/repo --auto-destroy
```

### Custom Sync Destination

```bash
# Download to a specific local directory
osmedeus cloud run \
  --custom-cmd "nmap -sV {{Target}} -oA /tmp/osm-custom/nmap" \
  --sync-path "/tmp/osm-custom/" \
  --sync-dest "./nmap-results" \
  -t example.com

# Results land in: ./nmap-results/<worker-name>-<ip>/tmp/osm-custom/nmap.*
```

### Using Worker Variables

```bash
# Log worker info alongside scan results
osmedeus cloud run \
  --custom-cmd "echo 'Worker {{worker_name}} ({{public_ip}}) scanning {{Target}}' > /tmp/osm-custom/info.txt" \
  --custom-cmd "nmap -sV {{Target}} -oA /tmp/osm-custom/nmap" \
  --sync-path "/tmp/osm-custom/" \
  -t example.com
```

## Real-World Scenarios

### Bug Bounty: Enumerate Multiple Programs

```bash
# targets.txt contains: hackerone.com, bugcrowd.com, intigriti.com, ...
osmedeus cloud run \
  -f general -T targets.txt --instances 5 \
  --sync-back --auto-destroy --provider digitalocean
```

### Scan a Large IP Range

```bash
# ip-ranges.txt contains CIDR ranges, one per line
osmedeus cloud run \
  --custom-cmd "cat {{Target}} | nmap -iL - -sV -oA /tmp/osm-custom/scan" \
  --sync-path "/tmp/osm-custom/" \
  -T ip-ranges.txt --instances 10 --auto-destroy
```

### Persistent Campaign

```bash
# Create infrastructure once
osmedeus cloud create --provider aws -n 3

# Run multiple scans over time
osmedeus cloud run -f fast -t target1.com --reuse
osmedeus cloud run -f fast -t target2.com --reuse
osmedeus cloud run --custom-cmd "nuclei -u target3.com -o /tmp/osm-custom/nuclei.txt" \
  --sync-path "/tmp/osm-custom/" -t target3.com --reuse

# Destroy when the campaign is over
osmedeus cloud destroy all --force
```

### Multi-Provider Strategy

```bash
# Use Hetzner for cheap bulk scanning
osmedeus cloud run -f fast -T targets.txt --instances 10 --provider hetzner

# Use AWS for targets requiring specific geo-location
osmedeus cloud run -f fast -t us-target.com --provider aws
```

## Provider Configuration Examples

### AWS

```bash
osmedeus cloud config set providers.aws.access_key_id ${AWS_ACCESS_KEY_ID}
osmedeus cloud config set providers.aws.secret_access_key ${AWS_SECRET_ACCESS_KEY}
osmedeus cloud config set providers.aws.region ap-southeast-1
osmedeus cloud config set providers.aws.instance_type t3.medium
osmedeus cloud config set providers.aws.use_spot true
osmedeus cloud config set defaults.provider aws
```

See [AWS Provider Guide](./cloud-provider-aws.md) for detailed setup and examples.

### Hetzner

```bash
osmedeus cloud config set providers.hetzner.token ${HETZNER_API_TOKEN}
osmedeus cloud config set providers.hetzner.location fsn1
osmedeus cloud config set providers.hetzner.server_type cx22
osmedeus cloud config set defaults.provider hetzner
```

See [Hetzner Provider Guide](./cloud-provider-hetzner.md) for detailed setup and examples.

### DigitalOcean

```bash
osmedeus cloud config set providers.digitalocean.token ${DO_TOKEN}
osmedeus cloud config set providers.digitalocean.region sgp1
osmedeus cloud config set providers.digitalocean.size s-2vcpu-4gb
osmedeus cloud config set defaults.provider digitalocean
```

### GCP

```bash
osmedeus cloud config set providers.gcp.project_id ${GCP_PROJECT}
osmedeus cloud config set providers.gcp.credentials_file /path/to/sa-key.json
osmedeus cloud config set providers.gcp.region us-central1
osmedeus cloud config set providers.gcp.zone us-central1-a
osmedeus cloud config set providers.gcp.machine_type n1-standard-2
osmedeus cloud config set providers.gcp.use_preemptible true
osmedeus cloud config set defaults.provider gcp
```

### Linode

```bash
osmedeus cloud config set providers.linode.token ${LINODE_TOKEN}
osmedeus cloud config set providers.linode.region ap-south
osmedeus cloud config set providers.linode.type g6-standard-2
osmedeus cloud config set defaults.provider linode
```

### Azure

```bash
osmedeus cloud config set providers.azure.subscription_id ${AZURE_SUB_ID}
osmedeus cloud config set providers.azure.tenant_id ${AZURE_TENANT_ID}
osmedeus cloud config set providers.azure.client_id ${AZURE_CLIENT_ID}
osmedeus cloud config set providers.azure.client_secret ${AZURE_CLIENT_SECRET}
osmedeus cloud config set providers.azure.location southeastasia
osmedeus cloud config set providers.azure.vm_size Standard_B2s
osmedeus cloud config set defaults.provider azure
```

## Advanced Topics

### Custom Snapshots

Pre-install tools on a VM, snapshot it, then use the snapshot for faster boot:

```bash
# 1. Create and set up a VM manually via your provider's console
# 2. Install osmedeus + all tools
# 3. Create a snapshot/image in the provider console
# 4. Configure osmedeus to use it

# AWS
osmedeus cloud config set providers.aws.ami ami-0123456789abcdef0

# DigitalOcean
osmedeus cloud config set providers.digitalocean.snapshot_id 12345678

# Hetzner
osmedeus cloud config set providers.hetzner.image 12345678
```

Boot time drops from ~5 minutes to ~30 seconds.

### Custom Worker Setup

```bash
# Add setup commands (run in order on each worker)
osmedeus cloud config set setup.commands.add "apt-get update && apt-get install -y nmap masscan"
osmedeus cloud config set setup.commands.add "go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest"

# Add post-setup commands (with per-worker variable expansion)
osmedeus cloud config set setup.post_commands.add "echo '{{worker_name}} at {{public_ip}}' >> /tmp/workers.txt"
```

### Ansible Setup

```bash
osmedeus cloud config set setup.ansible.enabled true
osmedeus cloud config set setup.ansible.playbook_path /path/to/setup.yaml
osmedeus cloud run -f fast -t example.com --ansible
```

### Environment Variable Expansion

All config values support `${ENV_VAR}` syntax:

```bash
osmedeus cloud config set providers.aws.access_key_id '${AWS_ACCESS_KEY_ID}'
osmedeus cloud config set providers.aws.secret_access_key '${AWS_SECRET_ACCESS_KEY}'
```

Values are expanded at runtime from your shell environment.

## Troubleshooting

### Workers not connecting
```bash
osmedeus cloud run -f fast -t example.com --verbose-setup  # See SSH output
osmedeus cloud run -f fast -t example.com --debug          # Full debug logs
```

### Orphaned infrastructure
```bash
osmedeus cloud list                    # Check what's running
osmedeus cloud destroy all --force     # Emergency cleanup
```

### Cost limit exceeded
```bash
osmedeus cloud config set limits.max_hourly_spend 5.00   # Increase limit
```

### Custom command failed
- Check if the tool is installed in your setup commands
- Use `--verbose-setup` to verify setup completed
- Test with a simple command first: `--custom-cmd "which nmap"`