National Cyber Warfare Foundation (NCWF)login

Osmedeus for declarative security workflow automation


0 user ratings
2026-11-21 13:29:25
milo
Red Team (CNA)
"Osmedeus

Osmedeus is a Go-based declarative orchestration engine that turns reconnaissance and vulnerability scanning into auditable YAML workflows for authorized penetration testers and bug bounty professionals.








Toolj3ssie/osmedeus — declarative security orchestration engine with distributed execution and agentic LLM steps
CategoryWorkflow orchestration / reconnaissance automation (Go, MIT license)
Primary UseComposing repeatable YAML-defined recon and scanning pipelines across authorized targets, with nmap integration, SARIF parsing, and multi-runner dispatch
Safe UseRunning workflow-driven reconnaissance and vulnerability assessment exclusively against assets you own or are contractually authorized to test, such as bug bounty scope, lab environments, and internal attack surface management
Telemetry NoteThe engine is noisy by design: distributed workers, cloud provisioning, and Redis-based queues generate DNS, HTTP, and scan traffic that authorized blue teams can correlate; workflows and results persist in local database tables queryable via osmedeus db list, leaving an internal audit trail

Osmedeus, hosted at j3ssie/osmedeus, describes itself as a security-focused declarative orchestration engine that reduces complex workflow automation into auditable YAML definitions. Written in Go and released under the MIT license with over 6,600 stars, the project sits at an interesting intersection of the recon-tooling and devops-pipeline worlds. Rather than being yet another scanner, it positions itself as infrastructure: a place where you describe what should happen to a target, and the engine handles parsing, dispatch, execution, and result storage. The README emphasizes encrypted data handling, secure credential management, and sandboxed execution, signaling that the maintainers are thinking about operator safety as a first-class concern rather than an afterthought.


The core abstraction is the workflow, a YAML document supporting hooks, decision routing, module exclusion, and conditional branching. Workflows come in two flavors in the CLI: module workflows invoked with -m (for example osmedeus run -m recon -t example.com) and flow workflows invoked with -f (such as osmedeus run -f general -t example.com). This split lets operators compose coarse-grained flows from finer-grained modules, and the --dry-run flag previews what a run would do before anything touches the network. That dry-run capability is exactly the kind of guardrail an authorized engagement needs when you want to validate scope boundaries before execution.


The architecture diagram in the README is unusually detailed for a tool of this genre. Entry points include the CLI, a REST API server started with osmedeus serve, a scheduler, and a distributed mode. All of them feed into a common pipeline: CONFIG → PARSER → EXECUTOR → STEP DISPATCHER → RUNNER. Step executors cover a wide spectrum: bash, function, parallel, foreach, remote-bash, http, llm, agent, agent-acp, and SARIF/SAST handling. Hooks wrap the main steps with pre_scan_steps and post_scan_steps, giving operators deterministic setup and teardown semantics inside every workflow run.


Execution isolation is handled by three runner types: HostRunner, DockerRunner, and SSHRunner. This is a meaningful design decision, because it lets an operator choose how much blast radius each step carries — running untrusted parsing logic inside Docker while keeping privileged coordination on the host, or spreading steps across remote machines via SSH. The Docker path is also the simplest way for a defender or researcher to experiment safely: docker run --rm j3ssie/osmedeus:latest against lab targets keeps the engine and its dependencies contained, with output mounted to a local directory.


Distribution is built on a Redis-based master-worker pattern with a queue system, webhook triggers, and file sync across workers. The CLI exposes this through osmedeus worker status, osmedeus worker queue new, and osmedeus worker queue run --concurrency 5, which lets an authorized team queue work for later processing instead of hammering targets in an uncontrolled burst. Queue polling feeds into deduplication and concurrent execution, so repeated targets or duplicate findings get collapsed before dispatch. For anyone running continuous attack surface management against their own estate, this queue-plus-dedup design is the difference between a scanner and a platform.


The function library is one of the README's headline claims: 80+ utility functions including nmap integration, tmux session management, SSH execution, TypeScript and Python scripting, SARIF parsing, and CDN/WAF classification. Notably, these functions are testable outside of a scan via osmedeus func eval 'log_info("hello")', and they can be evaluated in bulk across a target list with -T and -c for concurrency. Platform variables like PlatformOS and PlatformArch are exposed inside eval expressions, which suggests the library doubles as a scripting environment for glue logic — useful when triaging why a workflow step behaved unexpectedly.


The newest and most distinctive capability is agentic LLM steps. The README describes tool-calling agent loops with sub-agent orchestration, memory management, and structured output, plus ACP subprocess agents that can delegate to external coding agents such as Claude Code, Codex, OpenCode, and Gemini. The osmedeus agent command runs these interactively — osmedeus agent --agent codex "explain main.go" — and osmedeus agent --list enumerates what is available. In effect, the engine treats an LLM-backed reasoning step as just another executor in the pipeline, subject to the same workflow routing and hooks as a bash step, which is an architectural choice worth watching as agent-assisted security automation matures.


Scheduling is event-driven: cron, file-watch, and event triggers, each with filtering, deduplication, and delayed task queues. Combined with the webhook triggers on the API server, this enables patterns like kicking off a diff-oriented rescan whenever a target's certificate file changes, or scheduling nightly recon against in-scope assets. The roadmap shows diff reports comparing new, removed, and unchanged assets between runs as a planned but unfinished feature, which is precisely the delta-detection capability attack surface management programs depend on.


Cloud integration is another completed roadmap item. osmedeus cloud create --instances 3 provisions machines on DigitalOcean, AWS, GCP, Linode, or Azure, with cost controls and automatic cleanup, and osmedeus cloud run -f general -t example.com --instances 3 fans a workflow out across that freshly provisioned fleet. For authorized testers who need scan egress to come from clean, disposable infrastructure rather than a corporate IP range, this is a legitimate operational pattern — but it also means defenders should understand that tool traffic can originate from short-lived cloud addresses, since automatic teardown makes IP-based blocklists largely ineffective.


Results land in a local database with a surprisingly capable query surface. osmedeus assets -w example.com lists discovered assets for a workspace, osmedeus assets --stats summarizes unique technologies, sources, and types, and osmedeus query vulns --severity high --workspace example.com filters findings by severity. The db command drops to raw table access — osmedeus db list --table event_logs --search "nuclei" — which doubles as an audit trail of everything the engine did. An embedded Web UI provides workflow visualization and vulnerability views, and osmedeus serve exposes the same data through a REST API for integration into a broader reporting pipeline.


Installation is straightforward: npm install -g @j3ssie/osmedeus or a shell installer, with prebuilt binaries for linux and macOS on x64 and arm64. Workflow customization happens through preset repositories via osmedeus install workflow --preset, and module exclusion at run time is handled with -x portscan for exact matches or -X vuln for fuzzy substring exclusion. The SAST integration milestone — SARIF parsing for tools like Semgrep and Trivy — is marked complete, meaning the engine can ingest code-analysis results into the same workflow and reporting fabric as network recon, which is rare in this tool category.


For defenders, Osmedeus is worth studying even if you never run it offensively. Its workflow definitions encode a practitioner's mental model of how recon chains are assembled — subdomain enumeration feeding probing feeding vulnerability scanning — and the nmap, httpx, and nuclei references visible in the asset filters and log-search examples tell you which downstream tools are likely in play. Any large-scale automated enumeration against your perimeter will leave characteristic fingerprints: high-frequency DNS queries, uniform HTTP user agents, and rapid sequential port activity. Understanding the engine's queue-dedup-concurrency model helps blue teams reason about why authorized scanning looks the way it does, and why rate-limit-aware orchestration is as much a courtesy control as a performance feature.



Official project repository for j3ssie/osmedeus.

Download Tool

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.






Source: OffensiveSec
Source Link: https://www.offsecblog.com/2026/11/osmedeus-for-declarative-security.html


Comments
new comment
Nobody has commented yet. Will you be the first?
 
Forum
Red Team (CNA)



Copyright 2012 through 2026 - National Cyber Warfare Foundation - All rights reserved worldwide.