企业官网建设流程全解析

Osmedeus 安全编排引擎完全指南：声明式 YAML 工作流、分布式执行与 Agentic LLM 实战

【免费下载链接】osmedeusA Modern Orchestration Engine for Security项目地址: https://gitcode.com/GitHub_Trending/os/osmedeus

Osmedeus 是一款面向安全领域的声明式编排引擎（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 子进程 Agent（Claude 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），自动完成以下步骤：

1. 创建 base folder（默认$HOME/osmedeus-base）；
2. 从预设仓库（默认osmedeus/osmedeus-base）安装 base 目录骨架；
3. 安装预置 workflows（默认osmedeus/osmedeus-workflow）；
4. 重新加载osm-settings.yaml配置；
5. 从二进制注册表批量安装 nmap、ffuf、httpx 等安全工具到external-binaries（支持OSM_REGISTRY_URL覆盖注册表地址、OSM_IGNORE_REGISTRY=true跳过自动安装）；
6. 在$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，主要区块如下：

配置文件通过 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 list

run子命令的完整参数在 pkg/cli/run.go 中注册，下面列出核心参数及其语义：

几个值得注意的运行时细节：

• 若同时省略-f与-m，引擎会回退到默认 flowgeneral并给出提示；
• --dry-run模式会输出工作流名称、目标、步骤数、tactic、内置变量（BaseFolder、Binaries、Data、Workspaces、Output、threads、baseThreads、Today）以及各模块的参数表，方便执行前评审；
• 多目标执行时通过信号量（semaphore）控制并发，支持 Ctrl+C 优雅取消与超时终止（实现见 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.go（nmap 结果解析）、tmux_functions.go（tmux 会话管理）、ssh_functions.go（SSH 执行）、url_functions.go、string_functions.go、file_functions.go、db_functions.go（数据库读写）、event_functions.go（事件发射）、sarif_functions.go（SARIF 解析）、cdn_functions.go（CDN/WAF 分类）、markdown_functions.go、telegram_functions.go、webhook_functions.go、jq.go（jq 表达式）等，合计 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.go：worker 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.go：WorkflowKind分为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.go：

每个 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 cp，SSH 走rsync）；
• SetPIDCallbacks(onStart, onEnd)：进程生命周期回调，用于取消支持。

同时 runner 层实现了输出上限保护（stdout 10MB、stderr 1MB，超出部分静默丢弃并标记截断），防止工具输出 GB 级数据撑爆内存（internal/runner/runner.go）。

事件驱动与调度

Scheduler（internal/scheduler/scheduler.go）管理三类触发器，Trigger 结构定义在 internal/core/trigger.go：

• Cron 触发器：on: cron+schedule字段，使用标准 cron 表达式（如0 2 * * *）；
• 文件监听触发器：on: watch+path，支持debounce去抖（如500ms、1s），基于 fsnotify 实现；
• 事件触发器：on: event+event配置块，订阅特定 topic 的事件。

事件 Topic 采用<component>.<event_type>格式（如webhook.received、assets.new），支持 glob 通配匹配：*匹配一切、test*前缀匹配、*.new后缀匹配、assets.*.created多段匹配（见 internal/core/trigger.go）。

事件触发器的event配置块还支持：

触发器输入支持两种语法（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 分布式锁保证同一时刻只有一个 Master（TTL 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 执行，或按 scope（all/ 指定 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/linter）；
• EXECUTOR：按 Step 类型分发执行，支持 bash、function、parallel、foreach、remote-bash、http、llm、agent、agent-acp、SARIF/SAST 等执行器（见 internal/executor）；
• STEP DISPATCHER：负责 hooks 编排与决策路由；
• RUNNER：抽象 host / docker / ssh 三种运行环境；
• Queue：通过 DB + Redis 轮询实现任务去重与并发控制。

该架构保证了同一份 YAML 工作流可以无差别地在本机、容器或远程主机上执行，也为分布式扩展留出了清晰的边界。

路线图与当前状态

README 记录了项目的演进路线（部分长期目标仍在推进中）：

其中差异报告（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.go，CLI 子命令注册见 pkg/cli/root.go；
• REST 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。

License

Osmedeus 由 @j3ssie）。

【免费下载链接】osmedeusA Modern Orchestration Engine for Security项目地址: https://gitcode.com/GitHub_Trending/os/osmedeus