Skip to main content
Step-by-step guide for running osmedeus cloud on Google Cloud Platform Compute Engine instances.

​
Prerequisites

  • A GCP account with a project
  • A service account with Compute Engine permissions
  • A service account key file (JSON)
  • An SSH key pair (local ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub)

​
Required IAM Permissions

The service account needs these roles (or use the Compute Admin role): 
compute.instances.create
compute.instances.delete
compute.instances.get
compute.instances.list
compute.instances.setMetadata
compute.firewalls.create
compute.firewalls.delete
compute.firewalls.get
compute.networks.get
compute.subnetworks.use
compute.disks.create
compute.images.get
compute.images.useReadOnly
The simplest approach is to assign the Compute Admin (roles/compute.admin) role to your service account.

​
Create a Service Account and Key

  1. Go to IAM & Admin > Service Accounts > Create Service Account
  2. Name it osmedeus-cloud (or similar)
  3. Grant it the Compute Admin role
  4. Go to the service account > Keys > Add Key > Create new key > JSON
  5. Save the JSON file (e.g., ~/.gcp/osmedeus-sa.json)
Or via gcloud CLI: 
# Create service account
gcloud iam service-accounts create osmedeus-cloud \
  --display-name="Osmedeus Cloud Scanner"

# Grant Compute Admin role
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:osmedeus-cloud@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/compute.admin"

# Create and download key file
gcloud iam service-accounts keys create ~/.gcp/osmedeus-sa.json \
  --iam-account=osmedeus-cloud@YOUR_PROJECT_ID.iam.gserviceaccount.com
You can also export the credentials file path as an environment variable: 
export GCP_PROJECT_ID=your-project-id
export GCP_CREDENTIALS_FILE=~/.gcp/osmedeus-sa.json

​
Configuration

​
Minimal Setup

# Enable cloud feature
osmedeus config set cloud.enabled true

# Credentials
osmedeus cloud config set providers.gcp.project_id ${GCP_PROJECT_ID}
osmedeus cloud config set providers.gcp.credentials_file ${GCP_CREDENTIALS_FILE}
osmedeus cloud config set providers.gcp.region us-central1
osmedeus cloud config set providers.gcp.zone us-central1-a
osmedeus cloud config set defaults.provider gcp

# SSH
osmedeus cloud config set ssh.private_key_path ~/.ssh/id_rsa
osmedeus cloud config set ssh.public_key_path ~/.ssh/id_rsa.pub
osmedeus cloud config set ssh.user root

# Clean the setup scripts first
osmedeus cloud config set setup.commands.clear ""

# Worker setup
osmedeus cloud config set setup.commands.add "sudo apt-get update"
osmedeus cloud config set setup.commands.add "sudo apt-get install -y -qq curl git tmux unzip jq rsync"
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"

​
Machine Types

Machine TypevCPURAM$/hr (on-demand)$/hr (preemptible, ~80% off)Best For
e2-medium24 GB$0.0335~$0.010Light scans, single targets
n1-standard-227.5 GB$0.0950~$0.019General scanning (default)
n1-standard-4415 GB$0.1900~$0.038Heavy scans, large target lists
n2-standard-228 GB$0.0971~$0.019General scanning (newer gen)
n2-standard-4416 GB$0.1942~$0.039Parallel pipelines
c2-standard-4416 GB$0.2088~$0.042CPU-intensive scans
# Set machine type
osmedeus cloud config set providers.gcp.machine_type n1-standard-2

​
Preemptible Instances

Preemptible VMs cost up to 80% less than on-demand. They last at most 24 hours and can be reclaimed, but are ideal for security scanning workloads. 
osmedeus cloud config set providers.gcp.use_preemptible true

​
Regions and Zones

Pick a region close to your targets or with the lowest pricing:
RegionLocationCodeZone Example
IowaUSus-central1us-central1-a
South CarolinaUSus-east1us-east1-b
OregonUSus-west1us-west1-b
FrankfurtEuropeeurope-west3europe-west3-a
LondonEuropeeurope-west2europe-west2-a
SingaporeAsiaasia-southeast1asia-southeast1-a
TokyoAsiaasia-northeast1asia-northeast1-a
MumbaiAsiaasia-south1asia-south1-a
SydneyAustraliaaustralia-southeast1australia-southeast1-a
osmedeus cloud config set providers.gcp.region us-central1
osmedeus cloud config set providers.gcp.zone us-central1-a
Note: The zone must be within the selected region.

​
Custom Image Family

Use a custom image family with tools pre-installed for faster startup: 
# Default is ubuntu-2204-lts from the ubuntu-os-cloud project
# Use your own custom image family if you have one
osmedeus cloud config set providers.gcp.image_family my-osmedeus-image

​
Cost Limits

osmedeus cloud config set limits.max_hourly_spend 1.00
osmedeus cloud config set limits.max_total_spend 10.00
osmedeus cloud config set limits.max_instances 10

​
Examples

​
Quick Domain Recon

osmedeus cloud run -f fast -t example.com --auto-destroy
Cost: ~$0.03 (1 x e2-medium x 1 hour)

​
Large-Scale Subdomain Enumeration

# targets.txt: one domain per line
osmedeus cloud run -f general -T targets.txt --instances 5 --sync-back --auto-destroy
Cost: ~$0.48 (5 x n1-standard-2 x 1 hour)

​
Custom Nmap Scan

osmedeus cloud run \
  --custom-cmd "nmap -sV -sC {{Target}} -oA /tmp/osm-custom/nmap" \
  --sync-path "/tmp/osm-custom/" \
  -t example.com --auto-destroy

​
Distributed Nuclei Scanning

osmedeus cloud run \
  --custom-cmd "cat {{Target}} | nuclei -o /tmp/osm-custom/results.txt" \
  --sync-path "/tmp/osm-custom/results.txt" \
  --sync-dest "./nuclei-gcp" \
  -T urls.txt --instances 10 --auto-destroy
Cost: ~$0.34 (10 x e2-medium x 1 hour)

​
Preemptible Instance Pipeline

# Configure preemptible
osmedeus cloud config set providers.gcp.use_preemptible true
osmedeus cloud config set providers.gcp.machine_type n1-standard-2

# Run a heavy scan for cheap
osmedeus cloud run \
  --custom-cmd "subfinder -d {{Target}} -all -o /tmp/osm-custom/subs.txt" \
  --custom-cmd "cat /tmp/osm-custom/subs.txt | httpx -td -o /tmp/osm-custom/live.txt" \
  --custom-cmd "cat /tmp/osm-custom/live.txt | nuclei -o /tmp/osm-custom/nuclei.txt" \
  --sync-path "/tmp/osm-custom/" \
  -t example.com --auto-destroy
Cost: ~$0.019 (1 x n1-standard-2 preemptible x 1 hour)

​
Persistent Recon Campaign

# Create instances once (saves setup time on subsequent runs)
osmedeus cloud create --provider gcp -n 3

# Run scans throughout the day
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 at end of day
osmedeus cloud destroy all --force

​
Multi-Region Scanning

# Scan US targets from Iowa
osmedeus cloud config set providers.gcp.region us-central1
osmedeus cloud config set providers.gcp.zone us-central1-a
osmedeus cloud run -f fast -t us-company.com --auto-destroy

# Scan APAC targets from Singapore
osmedeus cloud config set providers.gcp.region asia-southeast1
osmedeus cloud config set providers.gcp.zone asia-southeast1-a
osmedeus cloud run -f fast -t apac-company.com --auto-destroy

​
Troubleshooting

​
”Permission denied” or “403 Forbidden”

Your service account lacks required permissions. Assign the Compute Admin role: 
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:YOUR_SA@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/compute.admin"

​
“Credentials file not found”

Make sure the JSON key file path is correct and the file exists: 
# Check the file exists
ls -la ~/.gcp/osmedeus-sa.json

# Or set via environment variable
export GCP_CREDENTIALS_FILE=/absolute/path/to/key.json
osmedeus cloud config set providers.gcp.credentials_file ${GCP_CREDENTIALS_FILE}

​
Instances Not Starting

# Check with debug output
osmedeus cloud run -f fast -t example.com --debug

# Common causes:
# - Quota exceeded (check Quotas page in Cloud Console)
# - Zone doesn't have the machine type available
# - Compute Engine API not enabled (enable it in APIs & Services)
# - Preemptible capacity unavailable (try a different zone or on-demand)

​
”Compute Engine API has not been used” Error

Enable the Compute Engine API for your project: 
gcloud services enable compute.googleapis.com --project=YOUR_PROJECT_ID

​
SSH Connection Timeout

# Verify firewall rule allows SSH (port 22)
gcloud compute firewall-rules list --filter="name~osmedeus"

# Check with verbose setup
osmedeus cloud run -f fast -t example.com --verbose-setup

​
Preemptible Instance Terminated

Preemptible VMs are reclaimed after 24 hours or when GCP needs capacity. The scan will fail for that worker. Mitigation:
  • Use --auto-destroy to clean up
  • Re-run the failed targets
  • Use on-demand instances for critical or long-running scans

​
Cleaning Up

# List all infrastructure
osmedeus cloud list

# Destroy specific
osmedeus cloud destroy <infra-id>

# Nuclear option
osmedeus cloud destroy all --force

# If osmedeus state is out of sync, check GCP console directly:
# Compute Engine > VM Instances > filter by label "osmedeus"
# Or via gcloud:
gcloud compute instances list --filter="labels.osmedeus:*"

​
Cost Optimization

  1. Use preemptible instances for all non-critical scans (use_preemptible: true) — up to 80% savings
  2. Right-size machines: e2-medium is enough for most single-target scans
  3. Always use --auto-destroy to prevent forgotten instances
  4. Set cost limits to catch runaway spending
  5. Use custom images to reduce setup time (less instance-hours)
  6. Pick the cheapest region if target geo-location doesn’t matter (us-central1 is usually cheapest)
  7. GCP sustained-use discounts apply automatically for on-demand VMs running more than 25% of the month