osmedeus-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Osmedeus Expert

Osmedeus 专家指南

Expert knowledge for writing YAML workflows and operating the Osmedeus security automation engine.

编写YAML工作流及操作Osmedeus安全自动化引擎的专业知识。

Quick Orientation

快速概览

Osmedeus executes YAML-defined workflows with two kinds:

module - Single execution unit containing steps (the building block)
flow - Orchestrates multiple modules with dependency ordering

Template variables use

{{Variable}}

syntax. Foreach loop variables use

[[variable]]

to avoid conflicts.

Osmedeus执行基于YAML定义的工作流，分为两类：

module（模块） - 包含多个步骤的单个执行单元（基础构建块）
flow（流程） - 按依赖顺序编排多个模块

模板变量使用

{{Variable}}

语法。Foreach循环变量使用

[[variable]]

以避免冲突。

Running Osmedeus

运行Osmedeus

Essential Commands

核心命令

bash

undefined

bash

undefined

Run a flow against a target

osmedeus run -f <flow-name> -t <target>

Run a module

osmedeus run -m <module-name> -t <target>

Run multiple modules in sequence

osmedeus run -m mod1 -m mod2 -t <target>

Multiple targets from file with concurrency

osmedeus run -m <module> -T targets.txt -c 5

With parameters

osmedeus run -m <module> -t <target> -p threads=20 -p depth=2 osmedeus run -m <module> -t <target> -P params.yaml

With timeout and repeat

osmedeus run -m <module> -t <target> --timeout 2h osmedeus run -m <module> -t <target> --repeat --repeat-wait-time 30m

Dry run (show what would execute)

osmedeus run -m <module> -t <target> --dry-run

Chunked processing for large target lists

osmedeus run -m <module> -T targets.txt --chunk-size 100 --chunk-part 0

Distributed execution

osmedeus run -m <module> -t <target> --distributed-run

undefined

osmedeus run -m <module> -t <target> --distributed-run

undefined

Workflow Management

工作流管理

bash

osmedeus workflow list                # List available workflows
osmedeus workflow show <name>         # Show workflow details
osmedeus workflow lint <workflow-path> # Validate workflow YAML

bash

osmedeus workflow list                # List available workflows
osmedeus workflow show <name>         # Show workflow details
osmedeus workflow lint <workflow-path> # Validate workflow YAML

Installation & Setup

安装与配置

bash

osmedeus install base --preset              # Install base from preset repo
osmedeus install base --preset --keep-setting  # Install base, keep settings
osmedeus install workflow --preset          # Install workflows from preset
osmedeus install binary --all               # Install all tool binaries
osmedeus install binary --name <name>       # Install specific binary
osmedeus install binary --all --check       # Check binary status
osmedeus install env                        # Add binaries to PATH
osmedeus install validate --preset          # Validate installation

bash

osmedeus install base --preset              # Install base from preset repo
osmedeus install base --preset --keep-setting  # Install base, keep settings
osmedeus install workflow --preset          # Install workflows from preset
osmedeus install binary --all               # Install all tool binaries
osmedeus install binary --name <name>       # Install specific binary
osmedeus install binary --all --check       # Check binary status
osmedeus install env                        # Add binaries to PATH
osmedeus install validate --preset          # Validate installation

Server & Workers

服务器与工作节点

bash

osmedeus server                       # Start REST API server
osmedeus server --master              # Start as distributed master
osmedeus worker join                  # Join as distributed worker
osmedeus worker join --get-public-ip  # Join with public IP detection
osmedeus worker status                # Show registered workers
osmedeus worker eval -e '<expr>'     # Evaluate function with distributed hooks
osmedeus worker set <id> <field> <value>  # Update worker metadata
osmedeus worker queue list            # List queued tasks
osmedeus worker queue new -f <flow> -t <target>  # Queue task
osmedeus worker queue run --concurrency 5        # Process queued tasks

bash

osmedeus server                       # Start REST API server
osmedeus server --master              # Start as distributed master
osmedeus worker join                  # Join as distributed worker
osmedeus worker join --get-public-ip  # Join with public IP detection
osmedeus worker status                # Show registered workers
osmedeus worker eval -e '<expr>'     # Evaluate function with distributed hooks
osmedeus worker set <id> <field> <value>  # Update worker metadata
osmedeus worker queue list            # List queued tasks
osmedeus worker queue new -f <flow> -t <target>  # Queue task
osmedeus worker queue run --concurrency 5        # Process queued tasks

Cloud

云服务相关

bash

osmedeus cloud config set <key> <value>   # Configure cloud provider
osmedeus cloud config list                # List cloud config
osmedeus cloud create --instances N       # Provision infrastructure
osmedeus cloud list                       # List active infrastructure
osmedeus cloud run -f <flow> -t <target> --instances N  # Run distributed
osmedeus cloud destroy <id>               # Destroy infrastructure

bash

osmedeus cloud config set <key> <value>   # Configure cloud provider
osmedeus cloud config list                # List cloud config
osmedeus cloud create --instances N       # Provision infrastructure
osmedeus cloud list                       # List active infrastructure
osmedeus cloud run -f <flow> -t <target> --instances N  # Run distributed
osmedeus cloud destroy <id>               # Destroy infrastructure

Other Commands

其他命令

bash

osmedeus func list                    # List utility functions
osmedeus func e 'log_info("test")'   # Evaluate a function
osmedeus snapshot export <workspace>  # Export workspace as ZIP
osmedeus snapshot import <source>     # Import workspace
osmedeus snapshot list                # List snapshots
osmedeus update                       # Self-update
osmedeus update --check               # Check for updates
osmedeus assets                       # List discovered assets
osmedeus assets -w <workspace>        # Filter by workspace
osmedeus assets --source httpx --type web  # Filter by source/type
osmedeus assets --stats               # Show asset statistics
osmedeus assets --columns url,title,status_code  # Custom columns
osmedeus assets --json                # JSON output
osmedeus uninstall                    # Uninstall osmedeus
osmedeus uninstall --clean            # Also remove workspaces data

For complete CLI flags, see references/cli-flags.md.

bash

osmedeus func list                    # List utility functions
osmedeus func e 'log_info("test")'   # Evaluate a function
osmedeus snapshot export <workspace>  # Export workspace as ZIP
osmedeus snapshot import <source>     # Import workspace
osmedeus snapshot list                # List snapshots
osmedeus update                       # Self-update
osmedeus update --check               # Check for updates
osmedeus assets                       # List discovered assets
osmedeus assets -w <workspace>        # Filter by workspace
osmedeus assets --source httpx --type web  # Filter by source/type
osmedeus assets --stats               # Show asset statistics
osmedeus assets --columns url,title,status_code  # Custom columns
osmedeus assets --json                # JSON output
osmedeus uninstall                    # Uninstall osmedeus
osmedeus uninstall --clean            # Also remove workspaces data

完整的CLI参数说明，请查看references/cli-flags.md。

Writing Workflows

编写工作流

Module Structure (Minimal)

模块结构（最简版）

yaml

name: my-module
kind: module

params:
  - name: threads
    default: "10"

steps:
  - name: scan-target
    type: bash
    command: echo "Scanning {{Target}}"
    exports:
      result: "output.txt"

yaml

name: my-module
kind: module

params:
  - name: threads
    default: "10"

steps:
  - name: scan-target
    type: bash
    command: echo "Scanning {{Target}}"
    exports:
      result: "output.txt"

Flow Structure (Minimal)

流程结构（最简版）

yaml

name: my-flow
kind: flow

modules:
  - name: enumeration
    steps:
      - name: find-subdomains
        type: bash
        command: subfinder -d {{Target}} -o {{Output}}/subs.txt
        exports:
          subdomains: "{{Output}}/subs.txt"

  - name: scanning
    depends_on: [enumeration]
    condition: "file_length('{{subdomains}}') > 0"
    steps:
      - name: port-scan
        type: bash
        command: naabu -l {{subdomains}} -o {{Output}}/ports.txt

yaml

name: my-flow
kind: flow

modules:
  - name: enumeration
    steps:
      - name: find-subdomains
        type: bash
        command: subfinder -d {{Target}} -o {{Output}}/subs.txt
        exports:
          subdomains: "{{Output}}/subs.txt"

  - name: scanning
    depends_on: [enumeration]
    condition: "file_length('{{subdomains}}') > 0"
    steps:
      - name: port-scan
        type: bash
        command: naabu -l {{subdomains}} -o {{Output}}/ports.txt

Step Types

步骤类型

Type	Purpose	Key Fields
`bash`	Shell commands	`command` , `commands` , `parallel_commands`
`function`	JS utility functions	`function` , `functions` , `parallel_functions`
`parallel-steps`	Run steps concurrently	`parallel_steps: [Step list]`
`foreach`	Iterate over items	`input` , `variable` , `threads` , `step`
`remote-bash`	Execute on docker/ssh runner	Same as bash + `step_runner_config`
`http`	HTTP requests	`url` , `method` , `headers` , `request_body`
`llm`	LLM API calls	`messages` , `tools` , `llm_config`
`agent`	Agentic LLM with tool loop	`query` , `agent_tools` , `max_iterations`

For complete field reference per step type, see references/step-types.md.

类型	用途	核心字段
`bash`	Shell命令	`command` , `commands` , `parallel_commands`
`function`	JS工具函数	`function` , `functions` , `parallel_functions`
`parallel-steps`	并发执行步骤	`parallel_steps: [Step list]`
`foreach`	遍历项目	`input` , `variable` , `threads` , `step`
`remote-bash`	在Docker/SSH运行器执行	与bash类型相同 + `step_runner_config`
`http`	HTTP请求	`url` , `method` , `headers` , `request_body`
`llm`	LLM API调用	`messages` , `tools` , `llm_config`
`agent`	带工具循环的智能Agent	`query` , `agent_tools` , `max_iterations`

各步骤类型的完整字段说明，请查看references/step-types.md。

Common Step Fields (All Types)

通用步骤字段（所有类型）

yaml

- name: step-name            # Required, unique identifier
  type: bash                 # Required
  pre_condition: "expr"      # JS expression, skip if false
  log: "Custom message"      # Log message (supports templates)
  timeout: 60                # Max seconds (or "1h", "30m")
  exports:                   # Variables for subsequent steps
    var_name: "value"
  on_success: [{action: log, message: "done"}]
  on_error: [{action: continue}]
  decision:                  # Conditional routing
    switch: "{{var}}"
    cases:
      "val1": {goto: step-a}
    default: {goto: _end}    # _end terminates workflow
  depends_on: [other-step]   # DAG dependencies

yaml

- name: step-name            # Required, unique identifier
  type: bash                 # Required
  pre_condition: "expr"      # JS expression, skip if false
  log: "Custom message"      # Log message (supports templates)
  timeout: 60                # Max seconds (or "1h", "30m")
  exports:                   # Variables for subsequent steps
    var_name: "value"
  on_success: [{action: log, message: "done"}]
  on_error: [{action: continue}]
  decision:                  # Conditional routing
    switch: "{{var}}"
    cases:
      "val1": {goto: step-a}
    default: {goto: _end}    # _end terminates workflow
  depends_on: [other-step]   # DAG dependencies

Template Variables

模板变量

Built-in:

{{Target}}

{{Output}}

{{Workspaces}}

{{RunUUID}}

{{WorkflowName}}

Platform:

{{PlatformOS}}

{{PlatformArch}}

{{PlatformInDocker}}

{{PlatformInKubernetes}}

{{PlatformCloudProvider}}

Custom params defined in

params:

are accessed as

{{param_name}}

Foreach variables use double brackets:

[[variable]]

For parameter generators and all variables, see references/template-variables.md.

内置变量：

{{Target}}

{{Output}}

{{Workspaces}}

{{RunUUID}}

{{WorkflowName}}

平台变量：

{{PlatformOS}}

{{PlatformArch}}

{{PlatformInDocker}}

{{PlatformInKubernetes}}

{{PlatformCloudProvider}}

自定义参数在

params:

中定义，通过

{{param_name}}

访问。

Foreach变量使用双括号：

[[variable]]

。

参数生成器及所有变量说明，请查看references/template-variables.md。

Workflow Inheritance

工作流继承

yaml

extends: parent-workflow-name
override:
  params:
    threads: "5"
  steps:
    mode: append    # append | prepend | merge
    add: [{name: extra, type: bash, command: "..."}]
    remove: [step-to-remove]

For the complete inheritance system, see references/workflow-advanced.md.

yaml

extends: parent-workflow-name
override:
  params:
    threads: "5"
  steps:
    mode: append    # append | prepend | merge
    add: [{name: extra, type: bash, command: "..."}]
    remove: [step-to-remove]

完整的继承系统说明，请查看references/workflow-advanced.md。

Workflow Patterns

工作流模式

Pattern: Parallel Tool Execution

模式：并行工具执行

yaml

- name: parallel-enum
  type: parallel-steps
  parallel_steps:
    - name: subfinder
      type: bash
      command: subfinder -d {{Target}} -o {{Output}}/subfinder.txt
      timeout: 600
    - name: amass
      type: bash
      command: amass enum -passive -d {{Target}} -o {{Output}}/amass.txt
      timeout: 900

yaml

- name: parallel-enum
  type: parallel-steps
  parallel_steps:
    - name: subfinder
      type: bash
      command: subfinder -d {{Target}} -o {{Output}}/subfinder.txt
      timeout: 600
    - name: amass
      type: bash
      command: amass enum -passive -d {{Target}} -o {{Output}}/amass.txt
      timeout: 900

Pattern: Foreach with Concurrency

模式：带并发的Foreach遍历

yaml

- name: scan-each-host
  type: foreach
  input: "{{hosts_file}}"
  variable: host
  threads: "{{threads}}"
  step:
    name: scan-host
    type: bash
    command: nmap -sV [[host]] -oX {{Output}}/nmap/[[host]].xml
    timeout: 120
    on_error: continue

yaml

- name: scan-each-host
  type: foreach
  input: "{{hosts_file}}"
  variable: host
  threads: "{{threads}}"
  step:
    name: scan-host
    type: bash
    command: nmap -sV [[host]] -oX {{Output}}/nmap/[[host]].xml
    timeout: 120
    on_error: continue

Pattern: Conditional Branching (Switch/Case)

模式：条件分支（Switch/Case）

yaml

- name: check-depth
  type: bash
  command: echo "{{scan_depth}}"
  decision:
    switch: "{{scan_depth}}"
    cases:
      "quick": {goto: fast-scan}
      "deep": {goto: full-scan}
    default: {goto: standard-scan}

yaml

- name: check-depth
  type: bash
  command: echo "{{scan_depth}}"
  decision:
    switch: "{{scan_depth}}"
    cases:
      "quick": {goto: fast-scan}
      "deep": {goto: full-scan}
    default: {goto: standard-scan}

Pattern: Conditional Branching (Conditions)

模式：条件分支（多条件判断）

yaml

- name: route-by-conditions
  type: bash
  command: echo "Evaluating conditions"
  decision:
    conditions:
      - if: "file_length('{{inputFile}}') > 100"
        goto: deep-analysis
      - if: "file_length('{{inputFile}}') > 0"
        function: "log_info('file has content')"
      - if: "{{enableNmap}}"
        commands:
          - "nmap -sV {{Target}}"

yaml

- name: route-by-conditions
  type: bash
  command: echo "Evaluating conditions"
  decision:
    conditions:
      - if: "file_length('{{inputFile}}') > 100"
        goto: deep-analysis
      - if: "file_length('{{inputFile}}') > 0"
        function: "log_info('file has content')"
      - if: "{{enableNmap}}"
        commands:
          - "nmap -sV {{Target}}"

Pattern: Agent-Powered Analysis

模式：Agent驱动的分析

yaml

- name: analyze-findings
  type: agent
  query: "Analyze vulnerabilities in {{Output}}/vulns.json and prioritize by severity"
  system_prompt: "You are a security analyst."
  max_iterations: 10
  agent_tools:
    - preset: bash
    - preset: read_file
    - preset: grep_regex
    - preset: save_content
  memory:
    max_messages: 30
    persist_path: "{{Output}}/agent/conversation.json"
  exports:
    analysis: "{{agent_content}}"

yaml

- name: analyze-findings
  type: agent
  query: "Analyze vulnerabilities in {{Output}}/vulns.json and prioritize by severity"
  system_prompt: "You are a security analyst."
  max_iterations: 10
  agent_tools:
    - preset: bash
    - preset: read_file
    - preset: grep_regex
    - preset: save_content
  memory:
    max_messages: 30
    persist_path: "{{Output}}/agent/conversation.json"
  exports:
    analysis: "{{agent_content}}"

Pattern: Flow with Module Dependencies

模式：带模块依赖的流程

yaml

modules:
  - name: recon
    steps: [...]

  - name: scanning
    depends_on: [recon]
    condition: "file_length('{{subdomains}}') > 0"
    steps: [...]

  - name: reporting
    depends_on: [scanning]
    steps: [...]

yaml

modules:
  - name: recon
    steps: [...]

  - name: scanning
    depends_on: [recon]
    condition: "file_length('{{subdomains}}') > 0"
    steps: [...]

  - name: reporting
    depends_on: [scanning]
    steps: [...]

Reference Files

参考文档

references/cli-flags.md - All CLI flags for every command
references/step-types.md - Complete field reference for each step type
references/template-variables.md - All template variables, generators, and utility functions
references/workflow-advanced.md - Triggers, inheritance, runners, action handlers, reports
references/examples.md - Full annotated workflow examples (module, flow, agent, triggers)

references/cli-flags.md - 所有命令的CLI参数说明
references/step-types.md - 各步骤类型的完整字段参考
references/template-variables.md - 所有模板变量、生成器及工具函数
references/workflow-advanced.md - 触发器、继承、运行器、动作处理器、报告
references/examples.md - 完整的带注释工作流示例（模块、流程、Agent、触发器）

Debugging Tips

调试技巧

Validate YAML before running:
```
osmedeus workflow lint <workflow-path>
```

Dry run to see execution plan:

osmedeus run -m <module> -t test --dry-run

Verbose output:
```
osmedeus run -m <module> -t <target> -v
```
Check exports: each step's exports propagate to subsequent steps only
Foreach uses
[[var]]
not
```
{{var}}
```
- this is the most common mistake

pre_condition uses JS expressions:

file_length('path') > 0

is_empty('{{var}}')

on_error: continue prevents a failing step from stopping the workflow

运行前验证YAML：
```
osmedeus workflow lint <workflow-path>
```

空运行查看执行计划：

osmedeus run -m <module> -t test --dry-run

详细输出：
```
osmedeus run -m <module> -t <target> -v
```
检查导出变量：每个步骤的导出变量仅会传递给后续步骤
Foreach使用
[[var]]
而非
{{var}}
：这是最常见的错误

pre_condition使用JS表达式：例如

file_length('path') > 0

、

is_empty('{{var}}')

on_error: continue：可防止单个步骤失败导致整个工作流终止