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

Advanced Usage

Understand Architecture

Workflows

Functions

Cloud

Advanced Topics & Extending Osmedeus

Reference

Documentation Index

​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

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