Osmedeus 安全编排引擎完全指南声明式 YAML 工作流、分布式执行与 Agentic LLM 实战【免费下载链接】osmedeusA Modern Orchestration Engine for Security项目地址: https://gitcode.com/GitHub_Trending/os/osmedeusOsmedeus 是一款面向安全领域的声明式编排引擎Declarative Orchestration Engine for Security它将复杂的安全自动化流程抽象为可审计、可版本化的 YAML 定义同时内置加密数据处理、安全凭证管理与沙箱化执行能力。本指南以 README.md 为骨架结合当前仓库源码系统讲解其安装配置、CLI 实战、工作流编写、事件驱动调度、分布式 Master-Worker 架构与库模式集成读完即可上手编排自己的侦察与漏洞评估流水线。Osmedeus 是什么Osmedeus 的核心设计理念是把流程交给声明式定义把执行交给引擎。它通过可组合的 YAML 工作流把 recon侦察、扫描、漏洞评估等复杂流程组织成标准化的流水线并且面向初学者与专家同样友好——初学者可以直接使用预置工作流专家则可以深度定制每一个 Step。从仓库的版本常量可以看到当前引擎代号为 v5.0.3见 internal/core/constants.go项目描述为A Modern Orchestration Engine for Security。它的能力覆盖声明式 YAML 工作流hooks、决策路由、模块排除、条件分支可跨 host / Docker / SSH 三种执行器运行分布式执行基于 Redis 的 Master-Worker 模式含任务队列、Webhook 触发与跨 Worker 文件同步80 工具函数库涵盖 nmap 集成、tmux 会话、SSH 执行、TypeScript/Python 脚本、SARIF 解析、CDN/WAF 分类等事件驱动调度Cron、文件监听、事件三类触发器支持过滤、去重与延迟任务队列Agentic LLM Steps工具调用型 Agent 循环、子 Agent 编排、记忆管理、结构化输出以及 ACP 子进程 AgentClaude Code、Codex、OpenCode、Gemini云基础设施可在 DigitalOcean、AWS、GCP、Linode、Azure 上批量开通机器执行扫描内置成本控制与自动清理丰富的 CLI 与 REST API / Web UI交互式数据库查询、批量函数求值、工作流 lint、进度条、嵌入式可视化仪表盘。安装与首次配置一键安装安装脚本位于仓库的 public/mics/install.sh官方推荐的一键安装方式为curl -sSL http://www.osmedeus.org/install.sh | bash首次运行自动初始化安装完成后第一次执行任意常规命令时CLI 会触发 first-time setup实现见 pkg/cli/root.go自动完成以下步骤创建 base folder默认$HOME/osmedeus-base从预设仓库默认osmedeus/osmedeus-base安装 base 目录骨架安装预置 workflows默认osmedeus/osmedeus-workflow重新加载osm-settings.yaml配置从二进制注册表批量安装 nmap、ffuf、httpx 等安全工具到external-binaries支持OSM_REGISTRY_URL覆盖注册表地址、OSM_IGNORE_REGISTRYtrue跳过自动安装在$HOME/.osmedeus/initialized写入初始化标记避免下次重复初始化。首次配置完成后会提示后续步骤例如运行osmedeus run -f basic-recon -t example.com或osmedeus health检查环境。核心配置文件 osm-settings.yaml引擎的所有路径、数据库、服务器、策略等都由osm-settings.yaml控制。仓库内置的完整示例见 public/examples/osmedeus-base.example/osm-settings.yaml主要区块如下配置区块关键项说明base_folder$HOME/osmedeus-base所有数据根目录支持$HOME与环境变量展开environmentsexternal_binaries_path/external_data/external_configs/workspaces/workflows/snapshot/markdown_report_templates/external_agent_configs/external_scripts各组件目录可使用{{base_folder}}引用根目录databasedb_engine: sqlite或postgresql、db_path、PostgreSQL 的 host/port/username/password/ssl_mode扫描结果持久化SQLite 为默认serverhost: 0.0.0.0、port: 8002、ui_path、simple_user_map_key用户名密码映射、jwt.secret_signing_key、jwt.expiration_minutes: 180REST API 与 Web UI 服务scan_tacticaggressive: 40/default: 10/gently: 5不同强度的线程并发数分别对应--tactic aggressive/default/gentlyredishost留空即禁用分布式模式、port、username/password、db、connection_timeout分布式扫描必需global_varsGITHUB_API_KEY、SHODAN_API_KEY、CENSYS_API_KEY、PASSIVETOTAL_API_KEY等支持valueas_env工作流中通过{{VARIABLE_NAME}}或环境变量引用_API_KEY后缀用于标记敏感值notificationprovider: telegram、enabled、telegram.bot_token、telegram.chat_id扫描完成或发现关键结果时推送通知storageprovider: s3兼容 MinIO/GCS/DO Spaces、endpoint、access_key_id、bucket、region、use_sslS3 兼容对象存储备份扫描结果llm_configllm_providers多个 Provider 自动轮换、enabled_tool_call、max_tokens、temperature、top_k、top_p、max_retries、timeout、structured_json_format、system_promptLLM 能力Ollama / OpenAI / Anthropic 等配置文件通过 pkg/cli/root.go 在每次命令执行时加载也可以使用--settings-file指定自定义配置文件、--base-folder/-b指定 base 目录、--workflow-folder/-F指定工作流目录。配置加载后还会把global_vars导出到环境变量供后续步骤使用。Quick Start 快速上手运行第一个扫描# 运行一个 module 工作流如 recon 侦察模块 osmedeus run -m recon -t example.com # 运行一个 flow 工作流如 general 综合流程 osmedeus run -f general -t example.com # 多目标并发执行从文件读取目标并发 5 osmedeus run -m recon -T targets.txt -c 5 # 干跑模式只预览不执行 osmedeus run -f general -t example.com --dry-run # 启动 API 服务器 osmedeus serve # 列出可用工作流 osmedeus workflow listrun子命令的完整参数在 pkg/cli/run.go 中注册下面列出核心参数及其语义参数说明-f, --flow要执行的 flow 工作流名称-m, --module要执行的 module 工作流可多次指定按序执行-t, --target目标可多次指定也支持 stdin 管道输入-T, --target-file目标列表文件每行一个-p, --params附加参数keyvalue格式-P, --params-file参数文件JSON 或 YAMLkey:value-w, --workspace自定义 workspace 路径覆盖{{TargetSpace}}-c, --concurrency目标并发数默认 1-B, --tactic运行强度aggressive/default/gently-x, --exclude精确排除模块可多次指定-X, --fuzzy-exclude按子串模糊排除模块如-X vuln排除所有名称含 vuln 的模块-S, --space覆盖{{TargetSpace}}变量-W, --workspaces-folder覆盖{{Workspaces}}变量--heuristics-check目标类型启发式检查级别none/basic/advanced-D, --distributed-run提交到分布式 Worker 队列需要 Redis--repeat/--repeat-wait-time完成后循环重跑默认间隔1m--timeout运行超时如2h、1d--std-module从 stdin 读取 module YAML--module-url从 URL 拉取 module YAML支持 GitHub 私有仓库--empty-target无目标运行生成占位目标-G, --progress-bar进度条模式自动进入 silent--chunk-size/--chunk-count/--chunk-part/--chunk-threads目标分块执行--skip-validation跳过dependencies.variables的目标类型校验--sudo-aware一次性认证 sudo 并在执行期间保活--queue将任务入队稍后处理--queue-run立即处理排队任务osmedeus worker queue run的别名--as-webhook/--webhook-auth-key注册 Webhook 触发器代替立即执行--as-cron创建 Cron 调度如0 2 * * *几个值得注意的运行时细节若同时省略-f与-m引擎会回退到默认 flowgeneral并给出提示--dry-run模式会输出工作流名称、目标、步骤数、tactic、内置变量BaseFolder、Binaries、Data、Workspaces、Output、threads、baseThreads、Today以及各模块的参数表方便执行前评审多目标执行时通过信号量semaphore控制并发支持 CtrlC 优雅取消与超时终止实现见 pkg/cli/run.go。资产、漏洞与运行查询# 查询工作区资产 osmedeus assets -w example.com # 列出 workspace 资产 osmedeus assets --stats # 展示去重后的技术栈、来源、类型 osmedeus assets --source httpx --type web --json # 按来源与类型过滤并以 JSON 输出 # 查询漏洞、运行记录与步骤 osmedeus query vulns --severity high --workspace example.com osmedeus query runs --status running osmedeus query steps --run run-uuid # 查询数据库表 osmedeus db list --table runs osmedeus db list --table event_logs --search nuclei这些命令的底层依赖引擎的持久化数据库默认 SQLite扫描过程中的 assets、vulnerabilities、runs、steps、event_logs 都会被记录形成可审计的完整时间线。函数求值Function Eval引擎内置了基于 JS 运行时Goja/Otto见 internal/functions/registry.go的工具函数库可以直接在命令行求值非常适合调试或做临时数据处理# 求值单个表达式 osmedeus func eval log_info(hello) # 批量求值 并发 osmedeus func eval -e http_get(https://example.com) -T targets.txt -c 10 # eval 中可用的平台变量 osmedeus func eval log_info(OS: PlatformOS , Arch: PlatformArch)从 internal/functions 目录的源码划分可以看出函数库的组织方式nmap_functions.gonmap 结果解析、tmux_functions.gotmux 会话管理、ssh_functions.goSSH 执行、url_functions.go、string_functions.go、file_functions.go、db_functions.go数据库读写、event_functions.go事件发射、sarif_functions.goSARIF 解析、cdn_functions.goCDN/WAF 分类、markdown_functions.go、telegram_functions.go、webhook_functions.go、jq.gojq 表达式等合计 80 个工具函数。安装预设与模块排除# 从预设仓库安装 base 骨架 osmedeus install base --preset osmedeus install base --preset --keep-setting # 保留现有 osm-settings.yaml # 安装预设工作流 osmedeus install workflow --preset # 从 flow 执行中排除模块 osmedeus run -f general -t example.com -x portscan osmedeus run -f general -t example.com -X vuln # 按子串模糊排除Worker 队列系统osmedeus worker queue new -f general -t example.com # 入队稍后处理 osmedeus worker queue run --concurrency 5 # 以并发 5 处理队列分布式 Worker 管理osmedeus worker status # 展示在线 Worker 池状态 osmedeus worker eval -e ssh_exec(host, whoami) # 注册分布式钩子后求值worker子命令join / status / eval / set的实现见 pkg/cli/worker.goworker status会以表格展示 Worker 的 ID、主机名、公网 IP、SSH 使能状态、状态idle/busy/offline、完成任务数与最近心跳并支持--columns、--exclude-columns、--search过滤以及--json输出worker eval则在注册分布式钩子后执行函数表达式使ssh_exec等函数可以走 Redis 数据队列分发。ACP Agent 交互# 交互式运行 ACP Agent osmedeus agent analyze this codebase osmedeus agent --agent codex explain main.go osmedeus agent --list默认 ACP Agent 为claude-code见 internal/core/types.go可选 agent 包括 Codex、OpenCode、Gemini 等子进程型 Agent。云基础设施管理osmedeus cloud create --instances 3 # 批量开通云机器 osmedeus cloud setup 1.2.3.4 5.6.7.8 # 配置已有机器 osmedeus cloud list # 查看活跃云资产 osmedeus cloud run -f general -t example.com --instances 3云能力在 internal/cloud 中按 Provider 拆分实现aws.go、azure.go、digitalocean.go、gcp.go、linode.go等支持成本控制与生命周期自动清理。全部用法示例osmedeus --usage-example # 打印所有命令的综合用法示例该命令由根命令的-H/--usage-example与--full-usage-example标志触发见 pkg/cli/root.go可作为离线速查手册。Docker 部署引擎提供了官方镜像j3ssie/osmedeus:latest# 查看帮助 docker run --rm j3ssie/osmedeus:latest --help # 运行一次扫描挂载输出目录 docker run --rm -v $(pwd)/output:/root/workspaces-osmedeus \ j3ssie/osmedeus:latest run -f general -t example.com将宿主机的output目录挂载到容器内的workspaces-osmedeus扫描产物即可持久化到宿主机。工作流系统深度解析两种工作流Module 与 Flow核心类型定义在 internal/core/types.goWorkflowKind分为module单一模块与flow组合流程。Flow 内部通过modules字段引用若干模块形成可复用的组合模块则通过dependencies、params、pre_scan_steps/post_scan_steps等声明自己的输入输出契约。仓库中预置了大量可参考的 workflow 示例如 test/testdata/workflows 与 public/examples/osmedeus-base.example/workflows后者按flows/与modules/分目录组织。Step 类型引擎支持的 Step 类型同样定义在 internal/core/types.goStepType说明bash本地 shell 命令functionJS 工具函数求值parallel-steps并行执行一组子步骤foreach遍历列表循环执行remote-bash远程 shell 命令httpHTTP 请求步骤llm大模型调用步骤agent工具调用型 Agent 循环agent-acpACP 子进程 AgentClaude Code、Codex、OpenCode、Geminiagent-sdkSDK 型 Agent每个 Step 执行结果记录状态pending / running / success / failed / skipped并可通过决策路由decision routing控制下一步走向hooks 以pre_scan_steps → [main steps] → post_scan_steps的次序组织见 README 架构图中的 Hooks 行。Runner执行环境抽象工作流可以通过runner字段选择执行环境host/docker/ssh默认 host。Runner 抽象为一个接口见 internal/runner/runner.go其核心方法包括Execute(ctx, command)执行命令并返回 stdout/stderr 合并结果与退出码Setup(ctx)/Cleanup(ctx)准备与回收执行环境启动容器、建立 SSH、复制二进制IsRemote()判断是否远程执行CopyFromRemote(ctx, remotePath, localPath)将远程产物回传本地Docker 走docker cpSSH 走rsyncSetPIDCallbacks(onStart, onEnd)进程生命周期回调用于取消支持。同时 runner 层实现了输出上限保护stdout 10MB、stderr 1MB超出部分静默丢弃并标记截断防止工具输出 GB 级数据撑爆内存internal/runner/runner.go。事件驱动与调度Schedulerinternal/scheduler/scheduler.go管理三类触发器Trigger 结构定义在 internal/core/trigger.goCron 触发器on: cronschedule字段使用标准 cron 表达式如0 2 * * *文件监听触发器on: watchpath支持debounce去抖如500ms、1s基于 fsnotify 实现事件触发器on: eventevent配置块订阅特定 topic 的事件。事件 Topic 采用component.event_type格式如webhook.received、assets.new支持 glob 通配匹配*匹配一切、test*前缀匹配、*.new后缀匹配、assets.*.created多段匹配见 internal/core/trigger.go。事件触发器的event配置块还支持字段说明topic订阅的事件主题支持通配符filtersJS 布尔过滤表达式如event.name discoveredfilter_functions带工具函数的 JS 过滤如contains(event.data.url, /api/)dedupe_key去重键模板如{{event.source}}-{{event.data.url}}dedupe_window去重窗口如5s、1m窗口内重复事件被忽略触发器输入支持两种语法internal/core/trigger.go# 传统单变量语法 input: type: event_data field: url name: target # 新的 exports 风格多变量语法 input: target: event_data.url description: trim(event_data.desc) source: event.source分布式执行架构分布式能力基于 Redis 实现 Master-Worker 模式核心代码在 internal/distributed。Master 节点internal/distributed/master.go承担以下职责Master 锁通过 Redis 分布式锁保证同一时刻只有一个 MasterTTL 60s、每 30s 续约见 internal/distributed/master.go任务队列SubmitTask把任务推入 pending 队列Worker 轮询取走执行DB Redis polling → dedup → 并发执行Worker 健康监控每 30s 检查一次心跳超时HeartbeatTimeout即判定 Worker 失联将其运行中的任务重置回 pending 并重新分配随后移除失联 Worker事件订阅通过 Redis pub/sub 订阅事件并持久化到数据库数据汇聚Worker 通过runs/steps/events/artifacts/execute五类数据队列把结果回传 Master 落库执行请求路由支持 Worker 通过run_on_master(func|bash|run, ...)请求 Master 执行或按 scopeall/ 指定 Worker路由到其他 Worker文件同步sync_to_worker通过 rsync 把 Master 上的文件同步到已启用 SSH 的 Worker。在 CLI 侧通过-D/--distributed-run即可把本地 run 提交到分布式队列Worker 侧通过osmedeus worker join加入集群见 pkg/cli/worker.go加入时可选--get-public-ip获取公网 IP并自动连接数据库以支持db_import_*类函数。库模式集成Programmatic API除了 CLI引擎还提供了 Go 库模式入口在 lib/osmedeus.go可把工作流执行嵌入自己的程序result, err : lib.Run(example.com, workflowYAML, nil) fmt.Printf(Status: %s\n, result.Status) // 带上下文超时/取消 ctx, cancel : context.WithTimeout(context.Background(), 5*time.Minute) defer cancel() result, err : lib.RunWithContext(ctx, example.com, workflowYAML, nil) // 便捷封装 result, err : lib.RunModuleWithParams(example.com, workflowYAML, map[string]string{ threads: 20, timeout: 30, }) // 函数求值与条件判断 exists, err : lib.Eval(fileExists(/etc/passwd), nil) ok, err : lib.EvalCondition(len(items) 0, lib.EvalOptions{ Context: map[string]interface{}{items: []string{a, b}}, }) // 解析与校验无需执行 workflow, err : lib.ParseWorkflow(workflowYAML) err lib.ValidateWorkflow(workflowYAML)lib.Run的内部流程lib/osmedeus.go为校验输入 →parser.ParseContent解析 YAML →parser.Validate校验 → 校验为 module库模式不支持 flow→ 构建配置与参数 → 创建 Executor →ExecuteModule执行。注意库模式仅支持 module 类型工作流。高层架构总览README 给出了引擎的整体分层架构整理如下┌───────────────────────────────────────────────────────────────────────────┐ │ Osmedeus Orchestration Engine │ ├───────────────────────────────────────────────────────────────────────────┤ │ ENTRY POINTS │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │ │ │ CLI │ │ REST API │ │Scheduler │ │ Distributed │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬───────┘ │ │ └─────────────┴─────────────┴──────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ CONFIG ──▶ PARSER ──▶ EXECUTOR ──▶ STEP DISPATCHER ──▶ RUNNER │ │ │ │ │ │ │ │ │ Step Executors: bash | function | parallel | foreach | remote-bash │ │ │ │ http | llm | agent | agent-acp | SARIF/SAST │ │ │ │ Hooks: pre_scan_steps → [main steps] → post_scan_steps │ │ │ │ │ │ │ │ │ Runners: HostRunner | DockerRunner | SSHRunner │ │ │ │ Queue: DB Redis polling → dedup → concurrent execution │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ └───────────────────────────────────────────────────────────────────────────┘四个入口CLI、REST API、Scheduler、Distributed统一汇入核心执行管线CONFIG → PARSER → EXECUTOR → STEP DISPATCHER → RUNNER。其中CONFIG负责加载osm-settings.yaml、环境变量、全局变量PARSER解析并校验 YAML 工作流含继承、extends、lint 等见 internal/parser 与 internal/linterEXECUTOR按 Step 类型分发执行支持 bash、function、parallel、foreach、remote-bash、http、llm、agent、agent-acp、SARIF/SAST 等执行器见 internal/executorSTEP DISPATCHER负责 hooks 编排与决策路由RUNNER抽象 host / docker / ssh 三种运行环境Queue通过 DB Redis 轮询实现任务去重与并发控制。该架构保证了同一份 YAML 工作流可以无差别地在本机、容器或远程主机上执行也为分布式扩展留出了清晰的边界。路线图与当前状态README 记录了项目的演进路线部分长期目标仍在推进中#里程碑状态1下一代架构重构的 Osmedeus 引擎✅2灵活的工作流与 Step 类型✅3事件驱动架构模型与各类触发器✅4可视化结果与工作流图的 Web UI✅5适配新架构与语法的工作流重写✅6更多工具函数如通知测试✅7基于 SARIF 解析的 SAST 集成Semgrep、Trivy 等✅8云集成支持在云 Provider 上运行扫描✅9生成展示运行间新增/移除/未变资产的差异报告❌10面向 Serverless 的云 Provider Step 类型❌N其他高级特性待讨论❌其中差异报告diff reports在仓库中已有基础支撑internal/database/diff.go 及 pkg/server/handlers/asset_diff.go 提供了资产对比的 API 能力相关差异逻辑在 internal/database/diff_test.go 中有测试覆盖。安全与免责声明Osmedeus 被设计为可以执行来自用户输入CLI、API、工作流定义的任意代码与命令这种灵活性是引擎的核心特性但也意味着使用者必须承担相应责任。README 明确提示不要运行来源不受信任的工作流不要对不拥有或未获授权的目标执行命令或扫描使用未经审查的工作流前务必谨慎。执行任何第三方提供的 workflow YAML 之前请务必先通读其内容。你对自己运行的内容负责。生产环境部署时还应按 public/examples/osmedeus-base.example/osm-settings.yaml 中的提示修改服务器 JWT 密钥secret_signing_key并妥善保管 API 凭证。相关资源引擎主体osmedeus命令入口在 cmd/osmedeus/main.goCLI 子命令注册见 pkg/cli/root.goREST API 文档仓库内 docs/api/README.mdx 及各接口的 docs/api 分篇说明服务端实现路由与处理函数在 pkg/server认证中间件在 pkg/server/middleware/auth.go开发指南HACKING.md预置工作流示例public/examples/osmedeus-base.example/workflows 与 test/testdata/workflows端到端测试覆盖 agent、cloud、distributed、event trigger、extends、foreach、hooks、sudo、ssh、worker 等场景见 test/e2e。LicenseOsmedeus 由 j3ssie。【免费下载链接】osmedeusA Modern Orchestration Engine for Security项目地址: https://gitcode.com/GitHub_Trending/os/osmedeus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考