Osmedeus — Modern Security Orchestration Engine
Automate and orchestrate complex security scanning and reconnaissance with auditable YAML workflows, distributed execution, and agentic LLM steps.
Evidence shows: SECURITY.md clearly distinguishes trusted and untrusted inputs and provides hardening recommendations (e.g., random key generation, limiting exposure). However, there is no explicit implementation of least privilege (e.g., default non-root, sandboxing), user confirmation is only prompted during installation, data flow transparency is limited (no detailed data flow description), sensitive data handling mentions encryption and credential management but lacks implementation details. Dependency security: go.mod lists many dependencies but no vulnerability scanning or version pinning strategy. External effects: clearly warns scans may trigger IDS/WAF, but no rollback mechanism. Source attribution: clear author and license, but publisher unverified. Thus, most criteria score low.
Evidence shows: README and SECURITY.md are consistent in product positioning and trust model, but detailed error handling documentation is missing. Dependency availability: multiple installation methods (curl, npm, Docker) but no availability guarantees. Failure messages: no specific error message examples or troubleshooting guide. Thus, self-consistency scores higher, other two lower.
Evidence shows: README explicitly targets beginners and experts, provides multiple usage scenarios (CLI, API, cloud, distributed). Capability boundaries clearly stated in SECURITY.md (e.g., arbitrary code execution is by design). Trigger precision: multiple trigger types (cron, webhook, events) but no detailed filtering/dedup mechanisms. Environment fit: supports multiple OS and cloud providers but no detailed configuration guide. Thus, moderate scores.
Evidence shows: README provides clear information architecture (features, install, quickstart, architecture, docs links). Install notes detailed (curl, npm, Docker). Naming stability: version v5 and release process, but no naming convention doc. Examples and FAQ: rich examples but no FAQ section. Known limitations listed in SECURITY.md (e.g., CSRF risk). License MIT clear. Versioning/changelog not provided. Maintenance responsibility: author and community but not explicit. Thus, moderate scores.
Evidence shows: Output usability: multiple query and output formats (JSON, table) but no output examples. Marginal value: rich features (80+ functions, cloud integration, LLM steps) but no comparison with alternatives. Cost-benefit: cloud cost controls but no performance benchmarks. Thus, output usability and marginal value moderate, cost-benefit low.
Evidence shows: README feature claims lack specific code references, but SECURITY.md provides detailed security model description. Cross-source corroboration: docs and code exist but no independent verification. Fact-inference separation: README claims are descriptive, not clearly separating facts and inferences. Thus, low scores.
- This tool is designed to execute arbitrary code; review workflow YAML before running, and avoid untrusted sources.
- API and Web UI have known security risks (e.g., CSRF, cookie readable by JS); avoid public exposure and enable authentication.
- Publisher identity unverified; many dependencies; check for vulnerabilities and supply chain risks.
What does this agent do, and when should you use it?
Osmedeus is a security-focused declarative orchestration engine that simplifies complex workflow automation into auditable YAML definitions, complete with encrypted data handling, secure credential management, and sandboxed execution. Built for both beginners and experts, it delivers powerful, composable automation without sacrificing the integrity and safety of your infrastructure. Key features include declarative YAML workflows with hooks, decision routing, module exclusion, and conditional branching across multiple runners (host, Docker, SSH); Redis-based master-worker distributed execution with queue system, webhook triggers, and file sync; a rich function library of 80+ utilities such as nmap integration, tmux sessions, SSH execution, TypeScript/Python scripting, SARIF parsing, and CDN/WAF classification; event-driven scheduling with cron, file-watch, and event triggers; agentic LLM steps with tool-calling agent loops and ACP subprocess agents (Claude Code, Codex, OpenCode, Gemini); cloud infrastructure provisioning on DigitalOcean, AWS, GCP, Linode, and Azure with cost controls; a comprehensive CLI; and a REST API with web UI. The execution boundary spans local or remote hosts, Docker containers, and cloud VMs.
Osmedeus reads target inputs from the user via CLI, API, or YAML workflow definitions, and executes a series of steps according to the workflow. It supports multiple step executors including bash, function, parallel, foreach, remote-bash, http, llm, agent, agent-acp, and SARIF/SAST. These steps are orchestrated and run on HostRunner, DockerRunner, or SSHRunner. The engine uses Redis for a master-worker pattern, enabling queue management, webhook triggers, and file synchronization. Users can launch scans with commands like osmedeus run -m recon -t example.com for a module workflow, osmedeus run -f general -t example.com for a flow workflow, or osmedeus cloud run for cloud-based execution. Output includes discovered assets, vulnerabilities, run logs, and event logs, queryable via CLI (e.g., osmedeus assets, osmedeus query vulns) or the REST API. The engine also integrates ACP subprocess agents such as Claude Code, Codex, OpenCode, and Gemini for interactive agent operations.
- A security researcher uses
osmedeus run -m recon -t target.comto automate reconnaissance on a target domain, collecting subdomains, technologies, and vulnerabilities. - A penetration tester runs
osmedeus run -f general -T targets.txt -c 5to concurrently scan multiple targets with a full workflow, improving efficiency. - A DevOps engineer uses
osmedeus worker queue newandosmedeus worker queue runto distribute scan tasks to worker queues for batch execution in a distributed environment. - A red team operator uses
osmedeus cloud create --instances 3to spawn temporary cloud VMs for large-scale scans, with automatic cleanup. - A developer uses
osmedeus agent "analyze this codebase"to invoke an ACP sub-agent (e.g., Claude Code) for code analysis or vulnerability auditing. - An automation platform starts the REST API server via
osmedeus serveto integrate Osmedeus into existing security pipelines, triggering scans via webhooks.
What are this agent's strengths and limitations?
- Declarative YAML workflows simplify complex automation with hooks, decision routing, module exclusion, and conditional branching, offering high auditability.
- Redis-based distributed execution with master-worker architecture enables queueing, webhook triggers, and file sync, supporting horizontal scaling.
- A rich function library of 80+ utilities includes nmap integration, tmux sessions, SSH execution, scripting (TypeScript/Python), and CDN/WAF classification.
- Agentic LLM steps with tool-calling agent loops and ACP sub-agent integrations (Claude Code, Codex, OpenCode, Gemini) extend analysis capabilities.
- Cloud infrastructure integration allows dynamic provisioning of scanning instances on multiple providers (DigitalOcean, AWS, GCP, Linode, Azure) with cost controls and auto-cleanup.
- Requires external dependencies like Redis and Docker, adding deployment and operational complexity.
- Documentation is extensive but scattered; new users may face a learning curve, especially for writing custom workflows.
- Cloud integrations depend on specific provider APIs, and migration costs may be high, plus cloud resource fees apply.
- Some advanced features (e.g., diff reports, serverless steps) are not yet complete, so be aware of functional boundaries.
- The project is primarily maintained by a single lead, and the community ecosystem may be smaller than large open-source projects, though a Discord community exists.
How do you install or deploy this agent?
The simplest installation is via the install script:
curl -sSL http://www.osmedeus.org/install.sh | bashAlternatively, install via npm (prebuilt binaries for linux and macOS on x64/arm64):
npm install -g @j3ssie/osmedeusAfter installation, refer to the Quickstart guide at https://docs.osmedeus.org/quickstart/ for initial setup, and https://docs.osmedeus.org/installation/ for advanced configurations such as Docker.
How do you use this agent?
Run a module workflow:
osmedeus run -m recon -t example.comRun a flow workflow:
osmedeus run -f general -t example.comPreview the execution plan in dry-run mode:
osmedeus run -f general -t example.com --dry-runStart the API server:
osmedeus serveQuery discovered assets:
osmedeus assets -w example.comInstall preset workflows:
osmedeus install base --presetUsing Docker:
docker run --rm -v $(pwd)/output:/root/workspaces-osmedeus j3ssie/osmedeus:latest run -f general -t example.comRemember to review workflow YAML files before execution and ensure you have permission to scan targets.
FAQ
How does Osmedeus differ from other security scanners like Nuclei or Amass?
Does Osmedeus cost money?
osmedeus cloud create), you will incur cloud provider costs. Dependencies like Docker and Redis may also involve infrastructure costs.Can I run Osmedeus on Windows?
How can I ensure the workflows I run are safe?
Can I use only part of the functionality without installing the whole engine?
osmedeus run -m recon runs only the reconnaissance module. All features are accessible through the same CLI.