Cloud Usage Examples - Osmedeus Docs

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

Getting Started

First Scan in 5 Minutes

# 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

# View all settings
osmedeus cloud config list

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

Workflow Mode Examples

Single Target

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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 for detailed setup and examples.

Hetzner

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 for detailed setup and examples.

DigitalOcean

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

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

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

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:

# 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

# 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

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:

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

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

osmedeus cloud list                    # Check what's running
osmedeus cloud destroy all --force     # Emergency cleanup

Cost limit exceeded

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"

​Getting Started

​First Scan in 5 Minutes

​Verify Configuration

​Workflow Mode Examples

​Single Target

​Multiple Targets

​Full Lifecycle

​Reusing Infrastructure

​Custom Command Examples

​Basic Usage

​Recon Pipeline

​Vulnerability Scanning

​Port Scanning at Scale

​SAST Scanning

​Custom Sync Destination

​Using Worker Variables

​Real-World Scenarios

​Bug Bounty: Enumerate Multiple Programs

​Scan a Large IP Range

​Persistent Campaign

​Multi-Provider Strategy

​Provider Configuration Examples

​AWS

​Hetzner

​DigitalOcean

​GCP

​Linode

​Azure

​Advanced Topics

​Custom Snapshots

​Custom Worker Setup

​Ansible Setup

​Environment Variable Expansion

​Troubleshooting

​Workers not connecting

​Orphaned infrastructure

​Cost limit exceeded

​Custom command failed