Documentation Index
Fetch the complete documentation index at: https://docs.osmedeus.org/llms.txt
Use this file to discover all available pages before exploring further.
Step-by-step guide for running osmedeus cloud on AWS EC2 instances.
Prerequisites
- An AWS account
- An IAM user or role with EC2 permissions
- An SSH key pair (local
~/.ssh/id_rsa and ~/.ssh/id_rsa.pub)
Required IAM Permissions
The IAM user needs these permissions (or use the AmazonEC2FullAccess managed policy):
ec2:RunInstances
ec2:TerminateInstances
ec2:DescribeInstances
ec2:DescribeImages
ec2:CreateSecurityGroup
ec2:AuthorizeSecurityGroupIngress
ec2:DeleteSecurityGroup
ec2:DescribeSecurityGroups
ec2:ImportKeyPair
ec2:DeleteKeyPair
ec2:DescribeKeyPairs
ec2:CreateTags
Get Your Credentials
- Go to IAM Console > Users > select your user
- Security credentials tab > Create access key
- Save the Access key ID and Secret access key
Or use environment variables if already configured for AWS CLI:
export AWS_ACCESS_KEY_ID=<YOUR_AWS_ACCESS_KEY_ID>
export AWS_SECRET_ACCESS_KEY=<YOUR_AWS_SECRET_ACCESS_KEY>
Configuration
Minimal Setup
# Enable cloud feature
osmedeus config set cloud.enabled true
# 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
# 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 ubuntu
# 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 health"
Instance Types
| Instance | vCPU | RAM | $/hr (on-demand) | $/hr (spot, ~70% off) | Best For |
|---|
| t3.medium | 2 | 4 GB | $0.0416 | ~$0.012 | Light scans, single targets |
| t3.large | 2 | 8 GB | $0.0832 | ~$0.025 | General scanning |
| t3.xlarge | 4 | 16 GB | $0.1664 | ~$0.050 | Heavy scans, large target lists |
| t3.2xlarge | 8 | 32 GB | $0.3328 | ~$0.100 | Parallel pipelines |
# Set instance type
osmedeus cloud config set providers.aws.instance_type t3.large
Spot Instances
Spot instances cost 60-80% less than on-demand. They can be interrupted but are fine for security scanning (stateless, can retry).
osmedeus cloud config set providers.aws.use_spot true
Regions
Pick a region close to your targets or with the lowest pricing:
| Region | Location | Code |
|---|
| US East (N. Virginia) | US | us-east-1 |
| US West (Oregon) | US | us-west-2 |
| EU (Frankfurt) | Europe | eu-central-1 |
| EU (Ireland) | Europe | eu-west-1 |
| Asia Pacific (Singapore) | Asia | ap-southeast-1 |
| Asia Pacific (Tokyo) | Asia | ap-northeast-1 |
| Asia Pacific (Mumbai) | Asia | ap-south-1 |
| Asia Pacific (Sydney) | Australia | ap-southeast-2 |
osmedeus cloud config set providers.aws.region us-east-1
Custom AMI
Use a custom AMI with tools pre-installed for faster startup:
# Find the default Ubuntu AMI for your region
# aws ec2 describe-images --owners 099720109477 --filters "Name=name,Values=ubuntu/images/hvm-ssd/ubuntu-*-amd64-*" --query 'sort_by(Images, &CreationDate)[-1].ImageId'
# Or use your own pre-built AMI
osmedeus cloud config set providers.aws.ami ami-0123456789abcdef0
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
Large-Scale Subdomain Enumeration
# targets.txt: one domain per line
osmedeus cloud run -f general -T targets.txt --instances 5 --sync-back --auto-destroy
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-aws" \
-T urls.txt --instances 10 --auto-destroy
Spot Instance Pipeline
# Configure spot
osmedeus cloud config set providers.aws.use_spot true
osmedeus cloud config set providers.aws.instance_type t3.large
# 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
Persistent Recon Campaign
# Create instances once (saves setup time on subsequent runs)
osmedeus cloud create --provider aws -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 US region
osmedeus cloud config set providers.aws.region us-east-1
osmedeus cloud run -f fast -t us-company.com --auto-destroy
# Scan APAC targets from Singapore
osmedeus cloud config set providers.aws.region ap-southeast-1
osmedeus cloud run -f fast -t apac-company.com --auto-destroy
Troubleshooting
”UnauthorizedOperation” Error
Your IAM user lacks required permissions. Attach AmazonEC2FullAccess policy or the minimal permissions listed above.
Instances Not Starting
# Check with debug output
osmedeus cloud run -f fast -t example.com --debug
# Common causes:
# - Region doesn't have the instance type available
# - vCPU limit reached (request limit increase in AWS console)
# - Spot capacity unavailable (try on-demand or different region)
SSH Connection Timeout
# Verify security group allows SSH (port 22)
# Check with verbose setup
osmedeus cloud run -f fast -t example.com --verbose-setup
Spot Instance Interrupted
Spot instances can be reclaimed by AWS. 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 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 AWS console directly:
# EC2 Console > Instances > filter by tag "osmedeus"
Cost Optimization
- Use spot instances for all non-critical scans (
use_spot: true)
- Right-size instances: t3.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 AMIs to reduce setup time (less instance-hours)
- Pick the cheapest region if target geo-location doesn’t matter (us-east-1 is usually cheapest)
