FAQs

A collection of frequently asked questions along with explanations of common errors and how to resolve them.

1. General

What is Osmedeus?

Show Answer

Osmedeus is a workflow engine for security automation. It executes YAML-defined workflows with support for multiple execution environments (host, Docker, SSH), scheduling, and distributed scanning.

What are the system requirements?

Hide Answer

The Osmedeus core engine is lightweight and can run anywhere with almost any specs.
However, if you plan to use it for reconnaissance (which is the main use case), it is recommended to use a modern Linux, macOS, or Windows system with WSL.
Since running reconnaissance generates heavy network traffic, it is also recommended to run Osmedeus in a cloud environment, such as a VM, Compute Engine, or EC2, to achieve the best performance.

How do I install Osmedeus?

Show Answer

# Build from source
make build

# Install to $GOBIN
make install

# Install security tools
osmedeus install binary --all

2. Binary Installation

Why do I need to install external binary?

Hide Answer

Osmedeus is a standalone Golang binary and works perfectly fine on its own. However, when using Osmedeus to run YAML workflows for security automation, it often needs to call external tools like httpx, nuclei, ffuf, etc. These tools must be installed and available on your system for those workflows to function properly.

I encountered an error when installing the binary or running `osmedeus health`. What should I do?

Hide Answer

Not all binaries listed in the registry are required for every workflow. Your scans may still function correctly even if some tools are missing.

Do I need to install all the binaries in the registry using `osmedeus install binary --all --install-optional` ?

Hide Answer

No. Installing all tools is completely optional. The registry includes additional tools that are commonly used in YAML workflows, but you only need the ones required for your specific workflow. Installing everything is not necessary for running a basic workflow.

I tried everything I can but still haven't managed to install the required binaries. What should I do?

Hide Answer

Like I said above, not all binaries listed in the registry are required for every workflow. Your scans may still function correctly even if some tools are missing.If you would like the ideal setup then I recommend using Docker to run Osmedeus and its workflows. This ensures that all dependencies are met and eliminates any compatibility issues. See the Docker Setup for more details.

3. Workflows

What is the difference between a flow and a module?

Hide Answer

Module: A single workflow unit containing steps that execute sequentially
Flow: Orchestrates multiple modules, allowing parallel execution and dependencies between modules

Where are workflows stored?

Hide Answer

Workflows are stored in ~/osmedeus-base/workflows/:

flows/ - Flow workflows
modules/ - Module workflows

How do I create a custom workflow?

Hide Answer

Create a YAML file in the workflows directory:

name: my-workflow
kind: module
description: My custom workflow
params:
  - name: target
    required: true
steps:
  - name: scan-target
    type: bash
    command: nmap {{target}}

What step types are available?

Hide Answer

Type	Description
`bash`	Execute shell commands
`function`	Execute JavaScript utility functions
`parallel-steps`	Run steps concurrently
`foreach`	Iterate over items
`remote-bash`	Execute in Docker or via SSH
`http`	Make HTTP requests
`llm`	Execute LLM API calls

4. Running Scans

How do I run a basic scan?

Hide Answer

# Run a flow workflow
osmedeus run -f general -t example.com

# Run a module workflow
osmedeus run -m vulnerability-scan -t example.com

How do I scan multiple targets?

Hide Answer

# From command line
osmedeus run -f fast -t target1.com -t target2.com

# From file
osmedeus run -f fast -T targets.txt -c 5

How do I set a timeout?

Hide Answer

osmedeus run -m port-scan -t example.com --timeout 2h

Where are scan results stored?

Hide Answer

Results are stored in workspaces at ~/workspaces-osmedeus/<target>/.

Where should I put my token (Github, Shodan, etc)?

Hide Answer

All you need to do is follow this guide to setup the token

How can I setup to send notification?

Hide Answer

All you need to do is follow this guide to setup notification

Where I can get a live support?

Hide Answer

You can Join https://discord.gg/mtQG2FQsYA to see if anyone can help. I might answer from time to time but I couldn’t promise to answer every single of them.

Does it support Proxy?

Hide Answer

Nope, natively it doesn’t support proxy. But since the design of the tool is running other 3rd party tools and a lot of them don’t support proxy by default. I’ve already considered proxychains but it makes it extremely slow and breaks a lot of things.

Why was my scan stuck at portscan?

Hide Answer

It will stay there because it got a sudo password prompt. Some special tools require root permission to run like nmap. Make sure you allow nmap can be run without sudo password prompt.

Why did my scan such as vulnerability scanning, port scanning, or content discovery take so long?

Hide Answer

It’s probably because the thing you put in was really big. Think about trying to run the content discovery against 2000 different hosts. That’s why it takes a long time.

Why Osmedeus didn't find any vulnerability even when I scan it with the intentionally vulnerable app?

Hide Answer

Again it very much depends on your target. Osmedeus really shines on large scope targets, not the single intentionally vulnerable web app. Just scan some random VDP then you will see the result. The reason it won’t find any vulnerability on the intentionally vulnerable app is the vulnscan module won’t support it. But you’re always welcome to customize the workflow to do so.

I found a new tool that is pretty awesome. Can you add it in Osmedeus?

Hide Answer

Yes, just follow this guide to add it to your workflow.

Does the X scan run tool Y or not?

Hide Answer

Read the flow and module files to determine what a step actually runs
Seriously, read the flow and module files.
Remember that you were warned twice about reading the flow and module files.
Search for the tool command in the workflow folder to confirm whether it is used or not (e.g: rg -F 'nuclei' ~/osmedeus-base/workflows/)

Where can I find the password for the Web UI?

Hide Answer

Please refer to this page to start a web server and get credentials. You may need to run this command osmedeus config view server.password

How can I keep the scan or the web UI running in the background?

Hide Answer

The simplest way to do it is running the process under https://tmuxcheatsheet.com/ . Other than that you can setup a service to run the osmedeus web server as a background process.

What should I do if Osmedeus found a vulnerability X?

Hide Answer

Read the vulnerability X description.
Seriously, read the vulnerability X description.
Remember that you were warned twice about reading the vulnerability X description.
Search for that vulnerability X name.
Manually verify the vulnerability X.
Still no results? maybe https://letmegooglethat.com/?q=what+is+a+vulnerability+X can help you.

Osmedeus found some vulnerable subdomains, but I am unable to access them?

Hide Answer

It is often the case that the availability of a subdomain found during a scan may not be the same when you attempt to manually verify it. This depends on the target and can vary.

When I run with the `--debug` flag, I've noticed that certain commands are returning errors with exit statuses such as 128, 255, or -1. Is this to be expected?

Hide Answer

Yes, it’s normal for certain commands to exhibit expected exit statuses, as they may succeed under specific conditions. However, if you’re confident that the raw bash command should succeed but is failing, please try copying the raw bash command and investigate why it’s encountering issues.

How can I determine which workflow to run for my target?

Hide Answer

You can run osmedeus workflow ls or osmedeus workflow show <workflow-name> --verbose to see the description and that would fit to the scan

5. API & Server

How do I start the API server?

Hide Answer

osmedeus server

The server starts on port 8002 by default.

How do I authenticate with the API?

Hide Answer

# Get a JWT token
curl -X POST http://localhost:8002/osm/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "osmedeus", "password": "admin"}'

# Use the token
curl http://localhost:8002/osm/api/workflows \
  -H "Authorization: Bearer <token>"

How do I disable authentication?

Hide Answer

osmedeus server --no-auth

Can I use API keys instead of JWT?

Hide Answer

Yes, enable API key authentication in the server configuration. Then use the X-API-Key header instead of Authorization: Bearer.

6. Scheduling

How do I schedule a recurring scan?

Hide Answer

# Via CLI (creates a cron schedule)
osmedeus run -f subdomain-enum -t example.com --schedule "0 2 * * *"

# Via API
curl -X POST http://localhost:8002/osm/api/schedules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-scan",
    "workflow_name": "subdomain-enum",
    "target": "example.com",
    "schedule": "0 2 * * *"
  }'

What cron format is used?

Hide Answer

Standard 5-field cron: minute hour day-of-month month day-of-weekExamples:

0 2 * * * - Daily at 2 AM
0 0 * * 0 - Weekly on Sunday
*/30 * * * * - Every 30 minutes

7. Runners

What runners are available?

Hide Answer

Runner	Description
`host`	Execute on local machine (default)
`docker`	Execute in Docker containers
`ssh`	Execute on remote machines via SSH

How do I run a scan in Docker?

Hide Answer

osmedeus run -m port-scan -t example.com --runner docker --docker-image osmedeus/osmedeus:latest

How do I run a scan on a remote host?

Hide Answer

osmedeus run -m port-scan -t example.com --runner ssh --ssh-host worker.example.com

8. Distributed Mode

How do I set up distributed scanning?

Hide Answer

Start the master:

osmedeus server --master

Join workers:

osmedeus worker join --master http://master:8002

How do I submit tasks to the distributed pool?

Hide Answer

curl -X POST http://localhost:8002/osm/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_name": "subdomain-enum",
    "target": "example.com"
  }'

9. Troubleshooting

How do I check if tools are installed?

Hide Answer

osmedeus install binary --all --check

How do I install missing tools?

Hide Answer

# Install specific tools
osmedeus install binary --name nuclei --name httpx

# Install all tools
osmedeus install binary --all

How do I view scan logs?

Hide Answer

Logs are stored in the workspace:

cat ~/osmedeus-base/workspaces/<target>/log/execution.log

Hide Answer

osmedeus snapshot export <workspace>

How do I import a shared workspace?

Hide Answer

osmedeus snapshot import snapshot.zip

10. Configuration

Where is the configuration file?

Hide Answer

~/osmedeus-base/osm-settings.yaml

How do I change the default port?

Hide Answer

Edit osm-settings.yaml:

server:
  port: 9000

Or use the --port flag:

osmedeus server --port 9000

How do I configure database settings?

Hide Answer

Edit osm-settings.yaml:

database:
  db_engine: sqlite3  # or postgres
  host: localhost
  port: 5432
  name: osmedeus
  username: user
  password: pass

11. Clean up & Uninstall

How do I clean up the workspace?

Hide Answer

just run the command below to clean up workspace and database and generate the default osmedeus config

rm -rf ~/osmedeus-base ~/workspaces-osmedeus
osmedeus install base --preset

How do I clean up the workspace?

Hide Answer

just run the command below to clean up workspace and database and generate the default osmedeus config

rm -rf rm -rf ~/.osmedeus ~/osmedeus-base ~/workspaces-osmedeus
rm -rf $(which osmedeus) 

How do I uninstall osmedeus?

Hide Answer

just run the command below

rm -rf ~/.osmedeus ~/osmedeus-base ~/workspaces-osmedeus
rm -rf $(which osmedeus)

Getting Started

Advanced Setup

Understand Architecture

Workflows

Functions

Advanced Topics & Extending Osmedeus

Reference

1. General

2. Binary Installation

3. Workflows

4. Running Scans

5. API & Server

6. Scheduling

7. Runners

8. Distributed Mode

9. Troubleshooting

10. Configuration

11. Clean up & Uninstall

Getting Started

Advanced Setup

Understand Architecture

Workflows

Functions

Advanced Topics & Extending Osmedeus

Reference

​1. General

​2. Binary Installation

​3. Workflows

​4. Running Scans

​5. API & Server

​6. Scheduling

​7. Runners

​8. Distributed Mode

​9. Troubleshooting

​10. Configuration

​11. Clean up & Uninstall

1. General

2. Binary Installation

3. Workflows

4. Running Scans

5. API & Server

6. Scheduling

7. Runners

8. Distributed Mode

9. Troubleshooting

10. Configuration

11. Clean up & Uninstall