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.
CLI Reference
Complete reference for all Osmedeus command-line commands and options.
Global Options
These options are available for all commands:
| Option | Description |
|---|
--config | Path to config file (default: ~/.osmedeus/config.yaml) |
--debug | Enable debug logging |
--quiet | Suppress non-essential output |
--no-color | Disable colored output |
--help, -h | Show help |
run
Execute workflows against targets.
Basic Usage
# Run a flow
osmedeus run -f <flow_name> -t <target>
# Run a module
osmedeus run -m <module_name> -t <target>
# Run multiple modules
osmedeus run -m <module1> -m <module2> -t <target>
# Run with target file
osmedeus run -f general -T targets.txt
Options
| Option | Short | Description |
|---|
--flow | -f | Flow workflow to run |
--module | -m | Module workflow to run (repeatable) |
--target | -t | Target to scan |
--targets | -T | File containing targets |
--params | -P | Params file (YAML) |
--param | -p | Single param (key=value, repeatable) |
--concurrency | -c | Concurrent target scans (default: 1) |
--timeout | | Run timeout (e.g., 2h, 30m) |
--repeat | | Repeat execution continuously |
--exclude | -x | Exclude modules (comma-separated) |
--threads-hold | | Override thread count |
--dry-run | | Validate without executing |
--progress-bar | -G | Show progress bar during execution (enables silent mode) |
--workspace | -w | Custom workspace name |
--resume | | Resume from previous state |
Chunk Mode Options
For distributed scanning across multiple machines:
| Option | Description |
|---|
--chunk-size N | Split targets into chunks of N targets each |
--chunk-count N | Split targets into N equal chunks |
--chunk-part M | Execute only chunk M (0-indexed) |
--chunk-threads | Override concurrency within chunk |
Advanced Options
| Option | Description |
|---|
--skip-validation | Skip target type validation from dependencies.variables |
--disable-workflow-state | Disable writing workflow YAML to output directory |
--heuristics-check | Heuristics check level: none, basic, advanced (default: basic) |
--module-url | URL to fetch module YAML from (supports GitHub private repos) |
--std-module | Read module YAML from stdin |
Examples
# Basic flow scan
osmedeus run -f general -t example.com
# Module with parameters
osmedeus run -m subdomain-enum -t example.com -p threads=20
# Multiple targets with concurrency
osmedeus run -f general -T targets.txt -c 5
# With timeout
osmedeus run -m vuln-scan -t example.com --timeout 2h
# Exclude modules in flow
osmedeus run -f general -t example.com -x port-scan,vuln-scan
# Dry run (validate only)
osmedeus run -f general -t example.com --dry-run
# With progress bar
osmedeus run -f general -t example.com -G
# Skip target validation
osmedeus run -m custom-module -t special://target --skip-validation
# Load module from URL
osmedeus run --module-url https://github.com/user/repo/blob/main/module.yaml -t example.com
# Read module from stdin
cat my-module.yaml | osmedeus run --std-module -t example.com
# Advanced heuristics checking
osmedeus run -f general -t example.com --heuristics-check advanced
Chunk Mode Examples
# Split 1000 targets into chunks of 100 (creates 10 chunks)
# Machine 1: process chunk 0 (targets 0-99)
osmedeus run -f general -T large-targets.txt --chunk-size 100 --chunk-part 0
# Machine 2: process chunk 1 (targets 100-199)
osmedeus run -f general -T large-targets.txt --chunk-size 100 --chunk-part 1
# Split into exactly 5 equal chunks
osmedeus run -f general -T large-targets.txt --chunk-count 5 --chunk-part 0
# Override concurrency within chunk
osmedeus run -f general -T large-targets.txt --chunk-size 50 --chunk-part 0 --chunk-threads 10
# View chunk info without executing (omit --chunk-part)
osmedeus run -f general -T large-targets.txt --chunk-size 100
{{ChunkIndex}}, {{ChunkSize}}, {{TotalChunks}}, {{ChunkStart}}, {{ChunkEnd}}
workflow
Manage and inspect workflows.
workflow list
List all available workflows.
osmedeus workflow list
osmedeus workflow ls
| Option | Description |
|---|
--tags | Filter by tags (comma-separated) |
--show-tags | Show tags column in output |
--verbose, -v | Show workflows with errors |
# List all workflows
osmedeus workflow ls
# Filter by tags
osmedeus workflow ls --tags recon,fast
# Show tags column
osmedeus workflow ls --show-tags
workflow show
Display workflow details.
osmedeus workflow show <workflow_name>
| Option | Description |
|---|
--verbose, -v | Show detailed variable descriptions |
--yaml | Show raw YAML with syntax highlighting |
# Show workflow details
osmedeus workflow show subdomain-enum
# Show raw YAML
osmedeus workflow show subdomain-enum --yaml
# Verbose with all variables
osmedeus workflow show subdomain-enum -v
workflow validate / lint
Validate and lint workflow YAML files.
osmedeus workflow validate <name|path|folder>
osmedeus workflow lint <name|path|folder>
| Option | Description |
|---|
--check | Exit with error code if issues found (for CI) |
--format | Output format: pretty, json, github |
--severity | Minimum severity: info, warning, error |
--disable | Disable rules (comma-separated) |
--fail-fast | Stop on first validation failure |
| Rule | Severity | Description |
|---|
missing-required-field | warning | Required fields (name, kind, type) missing |
duplicate-step-name | warning | Multiple steps with same name |
empty-step | warning | Step has no executable content |
unused-variable | info | Variable exported but never used |
undefined-variable | warning | Variable referenced but not defined |
invalid-goto | warning | Decision goto references non-existent step |
invalid-depends-on | warning | depends_on references non-existent step |
circular-dependency | warning | Circular step dependencies detected |
# Validate by workflow name
osmedeus workflow validate subdomain-enum
# Validate YAML file
osmedeus workflow lint ./my-workflow.yaml
# Validate all workflows in folder
osmedeus workflow validate /path/to/workflows/
# CI mode - exit with error if issues found
osmedeus workflow lint my-workflow.yaml --check
# JSON output for tooling
osmedeus workflow lint my-workflow.yaml --format json
# GitHub Actions annotations
osmedeus workflow lint . --format github
# Only show warnings and errors
osmedeus workflow lint . --severity warning
# Disable specific rules
osmedeus workflow lint . --disable unused-variable,empty-step
# Stop on first error
osmedeus workflow validate . --fail-fast
{
"file_path": "workflows/test.yaml",
"issues": [
{
"rule": "undefined-variable",
"severity": "warning",
"message": "Variable 'unknown_var' is not defined",
"suggestion": "Check that the variable is defined in params or a previous step's exports",
"line": 15,
"column": 12,
"field": "steps[2].command"
}
],
"errors": 0,
"warnings": 1,
"infos": 0
}
::warning file=workflows/test.yaml,line=15,col=12::undefined-variable: Variable 'unknown_var' is not defined
func
Execute and inspect utility functions.
func list
List all available utility functions.
osmedeus func list
osmedeus func ls
| Option | Description |
|---|
--category | Filter by category |
--search | Search function names/descriptions |
func execute
Execute a function expression.
osmedeus func execute '<expression>'
osmedeus func e '<expression>'
# Check file exists
osmedeus func e 'fileExists("/tmp/test.txt")'
# Count lines
osmedeus func e 'fileLength("/path/to/file.txt")'
# String operations
osmedeus func e 'trim(" hello ")'
# With variables
osmedeus func e 'log_info("{{target}}")' -p target=example.com
eval
Shorthand for osmedeus func eval. Execute function expressions directly.
osmedeus eval -e 'fileExists("/tmp/test.txt")'
osmedeus e -e 'log_info("Hello")'
e, ev, evl, evla
server
Start the REST API server.
Options:
| Option | Description |
|---|
--port | Server port (default: 8080) |
--host | Bind address (default: 0.0.0.0) |
--master | Run as distributed master |
--token | API authentication token |
# Start server
osmedeus server --port 8080
# As distributed master
osmedeus server --master --port 8080
worker
Manage distributed workers.
worker join
Join as a distributed worker.
osmedeus worker join --master <master_url>
| Option | Description |
|---|
--master | Master server URL |
--token | Authentication token |
--name | Worker name |
install
Install external binaries and configure environment.
install binary
Install security tools.
osmedeus install binary --name <binary_name>
osmedeus install binary --all
| Option | Description |
|---|
--name | Specific binary to install |
--all | Install all binaries |
--check | Check installation status |
--nix-build-install | Install via Nix |
--nix-installation | Install Nix package manager |
--list-registry-nix-build | List Nix-available binaries |
--list-registry-direct-fetch | List direct-download binaries |
# Install specific binary
osmedeus install binary --name nuclei
# Install all binaries
osmedeus install binary --all
# Check status
osmedeus install binary --name nuclei --check
# Install via Nix
osmedeus install binary --nix-build-install
# List available binaries
osmedeus install binary --list-registry-nix-build
install env
Configure shell environment.
osmedeus install env
osmedeus install env --all
| Option | Description |
|---|
--all | Add to all shell configs |
--shell | Specific shell (bash, zsh, fish) |
update
Self-update Osmedeus.
osmedeus update
osmedeus update --check
| Option | Description |
|---|
--check | Check for updates without installing |
snapshot
Export and import workspace archives.
snapshot export
Export workspace as ZIP archive.
osmedeus snapshot export <workspace>
| Option | Description |
|---|
--output | Output file path |
--include-artifacts | Include all artifacts |
snapshot import
Import workspace from archive.
osmedeus snapshot import <source>
- Local file path
- HTTP/HTTPS URL
snapshot list
List available snapshots.
Database management commands.
db list
List database entries.
osmedeus db list assets
osmedeus db list vulnerabilities
osmedeus db list workspaces
| Option | Description |
|---|
--table, -t | Table name to query |
--workspace, -w | Filter by workspace |
--columns | Comma-separated column names to display |
--all | Show all columns |
--json | Output as JSON |
--offset | Number of records to skip (default: 0) |
--limit | Maximum records to return (default: 20) |
--list-columns | List available columns for the table |
--exclude-columns | Comma-separated columns to exclude |
db export
Export database to file.
osmedeus db export --workspace <name> --output <file>
client
Interact with a remote Osmedeus server via HTTP API.
client fetch
Fetch data from a remote server.
osmedeus client fetch --table runs
osmedeus client fetch --table assets --workspace example_com
osmedeus client fetch --table vulnerabilities --severity critical
| Option | Short | Description |
|---|
--remote-url | | Remote server URL (default: $OSM_REMOTE_URL) |
--auth-key | | API authentication key (default: $OSM_REMOTE_AUTH_KEY) |
--table | -t | Table to fetch: runs, step_results, artifacts, assets, event_logs, schedules, workspaces, vulnerabilities, asset_diffs, vuln_diffs |
--workspace | -w | Filter by workspace name |
--severity | | Filter vulnerabilities by severity |
--status | | Filter runs by status |
--limit | | Maximum records (default: 20) |
--offset | | Pagination offset (default: 0) |
--refresh | | Auto-refresh interval (e.g., 5s, 1m) |
--json | | Output as JSON instead of table |
client run
Create or cancel runs on a remote server.
osmedeus client run --workflow general --target example.com
osmedeus client run --cancel --run-id abc123
client exec
Execute functions on a remote server.
osmedeus client exec -e 'fileLength("/path/to/file")'
health
Check system health and configuration.
Checks performed:
- Configuration file status
- Database connectivity
- External binaries availability
- Workflows loaded count
- Disk space
- Network connectivity
Usage Examples
Show all usage examples.
This displays comprehensive examples for all major use cases.
Environment Variables
| Variable | Description |
|---|
OSM_CONFIG | Config file path |
OSM_BASE | Base folder path |
OSM_WORKSPACES | Workspaces folder path |
OSM_DEBUG | Enable debug mode |
OSM_TOKEN | API authentication token |
OSM_REMOTE_URL | Remote server URL for client commands |
OSM_REMOTE_AUTH_KEY | API authentication key for client commands |
