GCP Provider Guide

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

Go to IAM & Admin > Service Accounts > Create Service Account
Name it osmedeus-cloud (or similar)
Grant it the Compute Admin role
Go to the service account > Keys > Add Key > Create new key > JSON
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 Type	vCPU	RAM	$/hr (on-demand)	$/hr (preemptible, ~80% off)	Best For
e2-medium	2	4 GB	$0.0335	~$0.010	Light scans, single targets
n1-standard-2	2	7.5 GB	$0.0950	~$0.019	General scanning (default)
n1-standard-4	4	15 GB	$0.1900	~$0.038	Heavy scans, large target lists
n2-standard-2	2	8 GB	$0.0971	~$0.019	General scanning (newer gen)
n2-standard-4	4	16 GB	$0.1942	~$0.039	Parallel pipelines
c2-standard-4	4	16 GB	$0.2088	~$0.042	CPU-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:

Region	Location	Code	Zone Example
Iowa	US	`us-central1`	`us-central1-a`
South Carolina	US	`us-east1`	`us-east1-b`
Oregon	US	`us-west1`	`us-west1-b`
Frankfurt	Europe	`europe-west3`	`europe-west3-a`
London	Europe	`europe-west2`	`europe-west2-a`
Singapore	Asia	`asia-southeast1`	`asia-southeast1-a`
Tokyo	Asia	`asia-northeast1`	`asia-northeast1-a`
Mumbai	Asia	`asia-south1`	`asia-south1-a`
Sydney	Australia	`australia-southeast1`	`australia-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

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

Getting Started

Advanced Usage

Understand Architecture

Workflows

Functions

Cloud

Advanced Topics & Extending Osmedeus

Reference

Prerequisites

Required IAM Permissions

Create a Service Account and Key

Configuration

Minimal Setup

Machine Types

Preemptible Instances

Regions and Zones

Custom Image Family

Cost Limits

Examples

Quick Domain Recon

Large-Scale Subdomain Enumeration

Custom Nmap Scan

Distributed Nuclei Scanning

Preemptible Instance Pipeline

Persistent Recon Campaign

Multi-Region Scanning

Troubleshooting

”Permission denied” or “403 Forbidden”

“Credentials file not found”

Instances Not Starting

”Compute Engine API has not been used” Error

SSH Connection Timeout

Preemptible Instance Terminated

Cleaning Up

Cost Optimization

​Prerequisites

​Required IAM Permissions

​Create a Service Account and Key

​Configuration

​Minimal Setup

​Machine Types

​Preemptible Instances

​Regions and Zones

​Custom Image Family

​Cost Limits

​Examples

​Quick Domain Recon

​Large-Scale Subdomain Enumeration

​Custom Nmap Scan

​Distributed Nuclei Scanning

​Preemptible Instance Pipeline

​Persistent Recon Campaign

​Multi-Region Scanning

​Troubleshooting

​”Permission denied” or “403 Forbidden”

​“Credentials file not found”

​Instances Not Starting

​”Compute Engine API has not been used” Error

​SSH Connection Timeout

​Preemptible Instance Terminated

​Cleaning Up

​Cost Optimization

Prerequisites

Required IAM Permissions

Create a Service Account and Key

Configuration

Minimal Setup

Machine Types

Preemptible Instances

Regions and Zones

Custom Image Family

Cost Limits

Examples

Quick Domain Recon

Large-Scale Subdomain Enumeration

Custom Nmap Scan

Distributed Nuclei Scanning

Preemptible Instance Pipeline

Persistent Recon Campaign

Multi-Region Scanning

Troubleshooting

”Permission denied” or “403 Forbidden”

“Credentials file not found”

Instances Not Starting

”Compute Engine API has not been used” Error

SSH Connection Timeout

Preemptible Instance Terminated

Cleaning Up

Cost Optimization