Osmedeus: A YAML Orchestration Engine for Security Workflows

Who Osmedeus is for, and the problem it removes

The project describes itself as "a security focused declarative orchestration engine that simplifies complex workflow automation into auditable YAML definitions." That sentence is the whole pitch, and it is worth taking literally. The unit of work is not a scan; it is a workflow file. Reconnaissance against a single domain usually means running a subdomain tool, feeding its output into an HTTP prober, feeding that into a screenshotter, then into a vulnerability scanner, with each stage writing files the next stage has to find. Osmedeus exists to make those handoffs explicit and repeatable instead of living in a shell script that only its author can read.

The audience follows from that. It is aimed at people who already know which tools they want to run and are tired of gluing them together: bug bounty hunters running the same sequence against many targets, internal pentest teams that need to show what a scan actually did, and platform engineers who want scheduled recon without writing a scheduler. The README also claims it is "built for both beginners and experts," but the beginner path is really the preset workflow install, not the engine itself. Nothing here replaces a scanner. Osmedeus decides what runs and in what order; the tools it invokes still do the finding.

How the engine executes a workflow: runners, hooks and routing

A workflow is YAML. The README lists what that YAML can express: hooks, decision routing, module exclusion and conditional branching, executed across multiple runners (host, Docker, SSH). So a single workflow can run one step directly on the machine, another inside a container, and a third over SSH on a remote box, without the author writing three different scripts.

Execution is split between modules and flows. The Quick Start shows `osmedeus run -m recon -t example.com` for a module workflow and `osmedeus run -f general -t example.com` for a flow workflow, which suggests modules are the reusable building blocks and flows compose them. Exclusion is handled at run time rather than by editing the file: `-x portscan` drops a named module, and `-X vuln` drops anything matching that substring. That is a small feature with real consequences, because it means one canonical flow can serve several scan profiles.

Underneath, results land in a workspace and are queryable. The CLI exposes `osmedeus assets` for discovered assets, `osmedeus query vulns`, `osmedeus query runs` and `osmedeus query steps`, plus `osmedeus db list --table runs`. The dependency list in go.mod includes SQLite and MinIO, which is consistent with a local database plus object storage for artifacts, though the README does not spell out the storage layout. Distributed execution is described as a Redis-based master-worker pattern with a queue, webhook triggers and file sync across workers.

Installing Osmedeus and running a first workflow

Two install paths are documented. The first is a shell installer, the second is an npm package that ships prebuilt binaries for Linux and macOS on x64 and arm64.

curl -sSL http://www.osmedeus.org/install.sh | bash

npm install -g @j3ssie/osmedeus

Either way you end up with an `osmedeus` binary on your PATH. The README points to the Quickstart page for setup and an Installation page for advanced configurations, and the documentation is where the details of `osm-settings.yaml` live rather than the README.

Before running anything against a live target, install the preset content. The README shows two separate installs, one for base data and one for workflows:

osmedeus install base --preset
osmedeus install workflow --preset

Adding `--keep-setting` preserves an existing `osm-settings.yaml`, which matters on a machine where you have already tuned configuration.

Now preview a flow without executing it:

osmedeus run -f general -t example.com --dry-run

The dry-run flag is the safest first command because it shows the plan rather than the scan. When you are satisfied, drop the flag. For a list of targets with concurrency:

osmedeus run -m recon -T targets.txt -c 5

After a run, inspect what was collected. `osmedeus assets -w example.com` lists the assets for a workspace, `osmedeus assets --stats` summarizes technologies, sources and types, and `osmedeus assets --source httpx --type web --json` filters and emits JSON you can pipe elsewhere. `osmedeus workflow list` shows what is installed.

The function library, agent steps and where the abstraction leaks

The README claims 80+ utility functions, and names nmap integration, tmux sessions, SSH execution, TypeScript and Python scripting, SARIF parsing, and CDN/WAF classification. You can call them outside a workflow: `osmedeus func eval 'log_info("hello")'` evaluates a single expression, and `osmedeus func eval -e 'http_get("https://example.com")' -T targets.txt -c 10` runs one against a target list with concurrency. Platform variables such as `PlatformOS` and `PlatformArch` are available inside eval, which is how a workflow can branch on the operating system.

Newer versions add LLM steps. The README describes tool-calling agent loops with sub-agent orchestration, memory management and structured output, plus ACP subprocess agents for Claude Code, Codex, OpenCode and Gemini. There is an interactive entry point, `osmedeus agent "analyze this codebase"`, and `--agent codex` selects a specific backend while `--list` enumerates them. This is the part of the project changing fastest, and it is also the part with the least stable contract: an agent step that calls a model is nondeterministic in a way that a nmap step is not, so a workflow containing one cannot be replayed with the same confidence.

The abstraction leaks in predictable places. Workflow YAML is only as good as the tools it wraps, so a missing binary fails at run time, not at lint time, even though `osmedeus workflow lint` exists. The README does not document rollback for a partially completed run, and it does not describe how a workflow is resumed after a worker dies mid-step. Distributed mode depends on Redis, which is infrastructure you now have to operate. And the cloud features provision machines on DigitalOcean, AWS, GCP, Linode, Azure and Hetzner, which means credentials for those providers live somewhere in your configuration.

Osmedeus compared with a general-purpose workflow tool

The obvious alternative is a generic orchestrator such as n8n, Airflow or a CI runner, or simply a Makefile plus cron. The difference is not the scheduling; it is the vocabulary. A generic orchestrator knows about tasks, retries and dependencies. Osmedeus knows about targets, workspaces, assets, vulnerabilities and steps, and it ships a function library whose primitives are HTTP probing, nmap invocation and CDN/WAF classification. You can build the same pipeline in Airflow, but you will write the asset model, the storage layout and the recon helpers yourself.

The trade-off runs the other way too. A generic orchestrator has a far larger ecosystem of operators and integrations, mature retry and backfill semantics, and a user base that has already hit the failure modes you will hit. Osmedeus is narrower by design, and its documentation is concentrated on the project's own site rather than in the README. If your pipeline is mostly non-security data movement with one scanning step at the end, a general orchestrator is the better host and Osmedeus is the wrong tool. If nearly every step is a security tool invocation, the specialized vocabulary pays for itself.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the most recent push was on 2026-08-08, the same day as the v5.1.0 release. The release cadence visible in the repository is roughly one minor or patch release every one to two months across 2026. That is a project still moving, and moving projects have upgrade costs. The major version is already at 5, which tells you the workflow format has been through breaking changes before. Before upgrading, run `osmedeus workflow lint` against your own workflows, because a lint pass is cheaper than discovering a renamed function mid-scan.

Osmedeus is MIT licensed. In practical terms that is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and licence text are preserved. MIT says nothing about the tools your workflows invoke, and those are separate programs with their own licences and their own restrictions on use. If you package Osmedeus into a product, the licence of the scanner it shells out to is a separate question, and one worth raising with counsel rather than assuming. The README does not address this.

The operational cost is the part that is easy to underestimate. A single-machine install is a binary and a settings file. Distributed mode adds Redis, workers and file synchronization between them. Cloud mode adds provider credentials, instance lifecycle and the cleanup logic the README mentions. Each of those is a component that can fail independently of your scan.

Frequently asked questions about Osmedeus

The questions below are drawn from what people actually search for about this project, plus a few that follow from the README. Answers are limited to what the repository and its documentation state.

Editorial conclusion

Adopt Osmedeus if you already chain recon tools by hand and want those chains expressed as reviewable YAML with per-run storage and a queryable database. Skip it if you want a scanner with a click-to-start button, or if you cannot run Redis for the distributed worker mode. Before committing, install it, run the dry-run preview against one domain, and confirm that the function library covers the tools your pipeline depends on.

Frequently asked questions

Official sources

1. j3ssie/osmedeus on GitHub
2. License: MIT
3. Project website
4. README
5. Releases