Osmedeus

https://docs.osmedeus.org
Admin
Osmedeus is a security focused declarative orchestration engine that simplifies complex workflow...
Tokens:287,553
Snippets:3,035
Trust Score:6.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Quick Setup Checklist Commands

Source: https://docs.osmedeus.org/advanced/api-key-configuration

Commands for installing binaries, setting API keys, configuring authentication, and testing the setup.

```bash
osmedeus install binary --all
osmedeus config set global_vars.GITHUB_API_KEY ghp_xxx
osmedeus config set server.password secure123
osmedeus config list
osmedeus health
```

--------------------------------

### Create New Installer Mode Implementation

Source: https://docs.osmedeus.org/advanced/development

Example of creating a new installer function for a custom installation mode.

```go
func InstallBinaryViaMyMode(name, pkg, binariesFolder string) error {
    // Implementation
}
```

--------------------------------

### Direct-Fetch Installation Response

Source: https://docs.osmedeus.org/api-references/install

Example JSON response after attempting to install binaries in direct-fetch mode. It indicates which binaries were successfully installed and which failed, along with reasons.

```json
{
  "message": "Binary installation completed",
  "registry_mode": "direct-fetch",
  "installed": ["nuclei", "httpx"],
  "installed_count": 2,
  "binaries_folder": "/home/user/osmedeus-base/binaries",
  "failed": [
    {"name": "ffuf", "error": "download failed"}
  ],
  "failed_count": 1
}
```

--------------------------------

### Install All Binaries (Direct-Fetch)

Source: https://docs.osmedeus.org/api-references/install

Installs all available binaries from the registry using the direct-fetch mode. This is a convenient way to get all tools. Ensure the Authorization token is set.

```bash
curl -X POST http://localhost:8002/osm/api/registry-install \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "binary",
    "install_all": true
  }'
```

--------------------------------

### First Scan in 5 Minutes

Source: https://docs.osmedeus.org/cloud/usage-examples

This example demonstrates the initial setup for running your first scan. It covers enabling the cloud feature, configuring AWS credentials, setting up SSH keys, defining setup commands for workers, and finally running a scan with automatic instance destruction.

```bash
# Step 0: Enable cloud feature
osmedeus config set cloud.enabled true

# Step 1: Configure AWS credentials
osmedeus cloud config set providers.aws.access_key_id ${AWS_ACCESS_KEY_ID}
osmedeus cloud config set providers.aws.secret_access_key ${AWS_SECRET_ACCESS_KEY}
osmedeus cloud config set providers.aws.region ap-southeast-1
osmedeus cloud config set defaults.provider aws

# Step 2: SSH keys
osmedeus cloud config set ssh.private_key_path ~/.ssh/id_rsa
osmedeus cloud config set ssh.public_key_path ~/.ssh/id_rsa.pub

# Step 3: Clean the setup scripts first, then add setup commands for workers
osmedeus cloud config set setup.commands.clear ""
osmedeus cloud config set setup.commands.add "curl -fsSL https://www.osmedeus.org/install.sh | bash"
osmedeus cloud config set setup.commands.add "osmedeus install base --preset"

# Step 4: Run your first scan
osmedeus cloud run -f fast -t example.com --auto-destroy
```

--------------------------------

### Install Binary Request Body

Source: https://docs.osmedeus.org/reference/rest-api

Example request body for installing a binary, specifying its name and the desired installation method.

```json
{
  "name": "nuclei",
  "method": "nix"
}
```

--------------------------------

### Install Binary

Source: https://docs.osmedeus.org/reference/rest-api

Initiate the installation of a binary, specifying the name and installation method.

```bash
POST /osm/api/install/binary
```

--------------------------------

### Install Project

Source: https://docs.osmedeus.org/advanced/development

Install the project binaries to the $GOBIN directory.

```bash
make install
```

--------------------------------

### Nix Build Mode Response Example

Source: https://docs.osmedeus.org/api-references/install

Example JSON response when querying registry info in nix-build mode. It details installed and available tools categorized by function.

```json
{
  "registry_mode": "nix-build",
  "nix_installed": true,
  "categories": [
    {
      "name": "Subdomain",
      "tools": [
        {
          "name": "amass",
          "desc": "In-depth attack surface mapping and asset discovery",
          "tags": ["recon", "subdomain"],
          "version": "4.2.0",
          "repo_link": "https://github.com/owasp-amass/amass",
          "installed": true,
          "path": "/home/user/.nix-profile/bin/amass"
        },
        {
          "name": "subfinder",
          "desc": "Fast passive subdomain enumeration tool",
          "tags": ["recon", "subdomain"],
          "version": "2.6.0",
          "installed": false
        }
      ]
    },
    {
      "name": "Vuln",
      "tools": [
        {
          "name": "nuclei",
          "desc": "Fast, customizable vulnerability scanner",
          "tags": ["vuln", "scanner"],
          "version": "3.0.0",
          "installed": true,
          "path": "/home/user/.nix-profile/bin/nuclei"
        }
      ]
    }
  ]
}
```

--------------------------------

### Install All Available Binaries

Source: https://docs.osmedeus.org/reference/cli-references

Installs all supported security tool binaries.

```bash
# Install all binaries
osmedeus install binary --all
```

--------------------------------

### Start Production Infrastructure

Source: https://docs.osmedeus.org/getting-started/docker-setup

Starts the PostgreSQL and Redis services for the production environment using docker-compose.production.yaml. This should be done before starting the main application.

```bash
docker compose -f build/docker/docker-compose.production.yaml up -d postgres redis
```

--------------------------------

### CLI: List Functions with Examples

Source: https://docs.osmedeus.org/functions/overview.md

Display usage examples for available functions by adding the `--example` flag to the `osmedeus func list` command.

```bash
# Show examples
osmedeus func list --example
```

--------------------------------

### GET /osm/api/install/registry

Source: https://docs.osmedeus.org/reference/rest-api

Lists available binaries in the registry, with optional filtering by installation method.

```APIDOC
## GET /osm/api/install/registry

### Description
List Binary Registry

### Method
GET

### Endpoint
/osm/api/install/registry

### Parameters
#### Query Parameters
- **method** (string) - Optional - Filter by installation method (e.g., 'nix', 'direct').
```

--------------------------------

### Display All Usage Examples

Source: https://docs.osmedeus.org/reference/cli-references

Show all available usage examples for the Osmedeus CLI.

```bash
osmedeus --usage-example
```

--------------------------------

### Install Osmedeus and Security Tools

Source: https://docs.osmedeus.org/others/faq

Build and install the Osmedeus binary from source, then install all security tools. Ensure your Go environment is set up correctly.

```bash
# Build from source
make build

# Install to $GOBIN
make install

# Install security tools
osmedeus install binary --all
```

--------------------------------

### Run Response Example

Source: https://docs.osmedeus.org/api-references/runs

This is an example of the JSON response received after successfully starting a run. It includes details like the job ID, status, and polling URL.

```json
{
  "message": "Run started",
  "workflow": "subdomain-enum",
  "kind": "flow",
  "target": "example.com",
  "target_count": 1,
  "priority": "normal",
  "job_id": "a1b2c3d4",
  "run_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "poll_url": "/osm/api/jobs/a1b2c3d4",
  "runner_type": "docker",
  "timeout": 60
}
```

--------------------------------

### Install Specific or All Tools

Source: https://docs.osmedeus.org/others/faq

Install specific tools by name or install all available tools. Use the `--name` flag for individual tools and `--all` for everything.

```bash
# Install specific tools
osmedeus install binary --name nuclei --name httpx

# Install all tools
osmedeus install binary --all
```

--------------------------------

### Add New Installer Mode Flag

Source: https://docs.osmedeus.org/advanced/development

Example of adding a boolean flag for a new installer mode in pkg/cli/install.go.

```go
installBinaryCmd.Flags().BoolVar(&myModeInstall, "my-mode-install", false, "use MyMode to install")
```

--------------------------------

### Install Osmedeus Library

Source: https://docs.osmedeus.org/advanced/library

Install the Osmedeus library using go get. This command fetches the latest version of the library.

```bash
go get github.com/j3ssie/osmedeus/v5
```

--------------------------------

### HTTP GET Request Example

Source: https://docs.osmedeus.org/workflows/step-types

Example of making a GET request to fetch data from an API. Supports templating for URLs and headers.

```yaml
- name: fetch-api
  type: http
  url: "https://api.example.com/data/{{target}}"
  method: GET
  headers:
    Authorization: "Bearer {{api_token}}"
  exports:
    api_response: "{{fetch_api_http_resp.response_body}}"
    status: "{{fetch_api_http_resp.status_code}}"
```

--------------------------------

### POST /osm/api/install/binary

Source: https://docs.osmedeus.org/reference/rest-api

Installs a specified binary using a given installation method.

```APIDOC
## POST /osm/api/install/binary

### Description
Install Binary

### Method
POST

### Endpoint
/osm/api/install/binary

### Parameters
#### Request Body
- **name** (string) - Required - The name of the binary to install.
- **method** (string) - Required - The installation method (e.g., 'nix').
```

--------------------------------

### Install Binaries or Workflows

Source: https://docs.osmedeus.org/api-references/install

Installs binaries from the registry or workflows from a Git/zip URL. Supports direct-fetch and Nix-build modes for binaries, and installation from various sources for workflows.

```APIDOC
## POST /osm/api/registry-install

### Description
Install binaries from registry or workflows from git/zip URL. Supports two installation modes for binaries.

### Method
POST

### Endpoint
/osm/api/registry-install

#### Request Body
- **type** (string) - Required. Either "binary" or "workflow"
- **names** ([]string) - Binary names to install (for `type=binary`)
- **install_all** (bool) - Install all binaries from registry (for `type=binary`)
- **source** (string) - Git URL, zip URL, or file path (for `type=workflow`)
- **registry_url** (string) - Custom registry URL (optional, for `type=binary`)
- **registry_mode** (string) - "direct-fetch" (default) or "nix-build"

### Request Example (Install Specific Binaries)
```bash
curl -X POST http://localhost:8002/osm/api/registry-install \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d 
    {
      "type": "binary",
      "names": ["nuclei", "httpx", "ffuf"]
    }
```

### Request Example (Install All Binaries)
```bash
curl -X POST http://localhost:8002/osm/api/registry-install \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d 
    {
      "type": "binary",
      "install_all": true
    }
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the installation process.
- **registry_mode** (string) - The mode used for installation (e.g., "direct-fetch").
- **installed** ([]string) - List of successfully installed binaries.
- **installed_count** (integer) - The total number of binaries successfully installed.
- **binaries_folder** (string) - The path to the directory where binaries are stored.
- **failed** ([]object) - List of binaries that failed to install, with error details.
  - **failed[].name** (string) - The name of the binary that failed.
  - **failed[].error** (string) - The error message associated with the failure.
- **failed_count** (integer) - The total number of binaries that failed to install.

### Response Example
```json
{
  "message": "Binary installation completed",
  "registry_mode": "direct-fetch",
  "installed": ["nuclei", "httpx"],
  "installed_count": 2,
  "binaries_folder": "/home/user/osmedeus-base/binaries",
  "failed": [
    {"name": "ffuf", "error": "download failed"}
  ],
  "failed_count": 1
}
```
```

--------------------------------

### Distributed Mode: Manual Setup

Source: https://docs.osmedeus.org/advanced/deployment

Steps for manually setting up distributed mode without Docker Compose, involving starting Redis, the Master server, and worker nodes.

```bash
# 1. Start Redis
docker run -d --name redis -p 6379:6379 redis:7-alpine

# 2. Start Master
./build/bin/osmedeus serve --master --port 8001

# 3. Start Workers (on same or different machines)
./build/bin/osmedeus worker join --redis-url redis://localhost:6379
```

--------------------------------

### Install Binary from Local Filepath

Source: https://docs.osmedeus.org/functions/reference.md

Installs a binary by copying it from a local file path to a specified destination. Useful for pre-downloaded tools.

```javascript
filepath_installer("/tmp/downloads/nuclei", "nuclei", "{{Binaries}}")  // Returns: true or false
```

--------------------------------

### Install Workflows

Source: https://docs.osmedeus.org/getting-started/cli

Install workflows from a Git URL or a predefined preset. The preset installation uses the OSM_WORKFLOW_URL environment variable or a default source.

```bash
osmedeus workflow install https://github.com/user/osmedeus-workflows.git
```

```bash
osmedeus workflow install --preset
```

--------------------------------

### Start Osmedeus Web Server

Source: https://docs.osmedeus.org/getting-started/cli

Starts the Osmedeus web server. Examples show default settings, custom ports, disabling authentication, and running as a distributed master node.

```bash
osmedeus serve
```

```bash
osmedeus serve --port 8080
```

```bash
osmedeus serve -A
```

```bash
osmedeus serve --host 127.0.0.1 --port 8811 -A
```

```bash
osmedeus serve --master
```

```bash
osmedeus serve --no-queue-polling
```

--------------------------------

### Install Specific Binaries (Direct-Fetch)

Source: https://docs.osmedeus.org/api-references/install

Installs a specified list of binaries directly from the registry using the direct-fetch mode. Ensure the Authorization token is set.

```bash
curl -X POST http://localhost:8002/osm/api/registry-install \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "binary",
    "names": ["nuclei", "httpx", "ffuf"]
  }'
```

--------------------------------

### Install Binary via Nix Build

Source: https://docs.osmedeus.org/getting-started/cli

Install a specific binary using the Nix build system. This is an alternative installation method for binaries.

```bash
osmedeus install binary --name nuclei --nix-build-install
```

--------------------------------

### Install Specific Binary

Source: https://docs.osmedeus.org/reference/cli-references

Installs a specific security tool binary. Use `--name` to specify the binary.

```bash
# Install specific binary
osmedeus install binary --name nuclei
```

--------------------------------

### Configure SSH Keys and Setup Commands

Source: https://docs.osmedeus.org/cloud/quick-reference

Configure SSH private and public key paths for secure access to cloud instances. Clear existing setup commands and add new ones for worker setup.

```bash
osmedeus cloud config set ssh.private_key_path ~/.ssh/id_rsa
osmedeus cloud config set ssh.public_key_path ~/.ssh/id_rsa.pub
osmedeus cloud config set setup.commands.clear ""
osmedeus cloud config set setup.commands.add "curl -fsSL https://www.osmedeus.org/install.sh | bash"
osmedeus cloud config set setup.commands.add "osmedeus install base --preset"
```

--------------------------------

### Install All Nix Binaries

Source: https://docs.osmedeus.org/api-references/install

This command installs all available binaries managed by Nix. It's a convenient way to set up all tools at once.

```bash
curl -X POST http://localhost:8002/osm/api/registry-install \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "binary",
    "install_all": true,
    "registry_mode": "nix-build"
  }'
```

--------------------------------

### Install Nix Package Manager

Source: https://docs.osmedeus.org/getting-started/cli

Install the Nix package manager, which is a prerequisite for installing binaries using Nix.

```bash
osmedeus install binary --nix-installation
```

--------------------------------

### Nix Binary Installation Error Response (Nix Not Installed)

Source: https://docs.osmedeus.org/api-references/install

This error response is returned if Nix is not installed on the system. It suggests installing Nix or using an alternative installation mode.

```json
{
  "error": true,
  "message": "Nix is not installed. Install Nix first or use registry_mode=direct-fetch"
}
```

--------------------------------

### Install Binary via Nix

Source: https://docs.osmedeus.org/reference/cli-references

Installs a binary using the Nix package manager.

```bash
# Install via Nix
osmedeus install binary --nix-build-install
```

--------------------------------

### Copy Production Environment Example

Source: https://docs.osmedeus.org/getting-started/docker-setup

Copies the example environment file to be used for production configuration. This file should be edited with specific settings.

```bash
cp build/docker/.env.example build/docker/.env
```

--------------------------------

### Install Osmedeus Premium Edition

Source: https://docs.osmedeus.org/others/premium-edition

Run this command to install the Premium Edition. Replace `<your-premium-domain>` with your provided domain.

```bash
curl -fsSL https://<your-premium-domain>/premium-osmedeus-install.sh | bash
```

--------------------------------

### Start Redis with Docker

Source: https://docs.osmedeus.org/advanced/distributed

Start a Redis instance using Docker for task queueing and coordination. Includes options for persistence.

```bash
# Docker
docker run -d -p 6379:6379 redis:7-alpine

# With persistence
docker run -d -p 6379:6379 \
  -v redis-data:/data \
  redis:7-alpine redis-server --appendonly yes

# then test connection at localhost:6379
```

--------------------------------

### Start Osmedeus Server Interactively

Source: https://docs.osmedeus.org/getting-started/docker-setup

Enter the toolbox container and start the Osmedeus REST API server interactively.

```bash
docker exec -it osmedeus-toolbox bash
osmedeus serve --port 8002 --host 0.0.0.0
```

--------------------------------

### Start Docker Toolbox Container

Source: https://docs.osmedeus.org/advanced/development

Starts the Docker toolbox container. Use this command after building the image to run the container.

```bash
make docker-toolbox-run
```

--------------------------------

### Flow Example: Full Reconnaissance

Source: https://docs.osmedeus.org/reference/workflow-schema

A complete workflow example demonstrating a full reconnaissance process, chaining multiple modules with dependencies and conditions.

```yaml
kind: flow
name: full-recon
description: "Complete reconnaissance workflow"
tags: "recon, full"

modules:
  - name: subdomain-enum
    path: modules/subdomain-enum.yaml
    params:
      threads: "20"

  - name: port-scan
    path: modules/port-scan.yaml
    depends_on:
      - subdomain-enum
    condition: "fileLength('{{Output}}/subdomains.txt') > 0"

  - name: vuln-scan
    path: modules/vuln-scan.yaml
    depends_on:
      - port-scan
```

--------------------------------

### Enable Ansible Setup

Source: https://docs.osmedeus.org/cloud/usage-examples

Enable Ansible integration for worker setup and specify the playbook path. Then, run a scan using Ansible.

```bash
osmedeus cloud config set setup.ansible.enabled true
```

```bash
osmedeus cloud config set setup.ansible.playbook_path /path/to/setup.yaml
```

```bash
osmedeus cloud run -f fast -t example.com --ansible
```

--------------------------------

### Install Workflow from Git URL

Source: https://docs.osmedeus.org/api-references/install

Installs a workflow by providing a direct URL to a git repository. Ensure the repository contains a valid workflow structure.

```bash
curl -X POST http://localhost:8002/osm/api/registry-install \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "workflow",
    "source": "https://github.com/osmedeus/osmedeus-workflow.git"
  }'
```

--------------------------------

### Install All Binaries via Nix Build

Source: https://docs.osmedeus.org/getting-started/cli

Install all available binaries using the Nix build system. This ensures all dependencies are managed by Nix.

```bash
osmedeus install binary --all --nix-build-install
```

--------------------------------

### Module Example: Subdomain Enumeration

Source: https://docs.osmedeus.org/reference/workflow-schema

A complete module example for enumerating subdomains, including parameters and steps for running tools and merging results.

```yaml
kind: module
name: subdomain-enum
description: "Enumerate subdomains for a target domain"
tags: "recon, subdomain"

params:
  - name: threads
    default: 10
  - name: wordlist
    default: "{{Data}}/wordlists/subdomains.txt"

steps:
  - name: subfinder
    type: bash
    command: "subfinder -d {{Target}} -all -o {{Output}}/subfinder.txt"
    timeout: 30m

  - name: merge-results
    type: function
    depends_on:
      - subfinder
    functions:
      - "sortUnix('{{Output}}/subfinder.txt', '{{Output}}/subdomains.txt')"
      - "db_total_subdomains('{{Output}}/subdomains.txt')"
```

--------------------------------

### Quick Start: Execute a Workflow

Source: https://docs.osmedeus.org/advanced/library

A basic Go program demonstrating how to load configuration, parse a workflow, set up an executor, and run a module with parameters.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/j3ssie/osmedeus/v5/internal/config"
    "github.com/j3ssie/osmedeus/v5/internal/executor"
    "github.com/j3ssie/osmedeus/v5/internal/parser"
)

func main() {
    ctx := context.Background()

    // 1. Load configuration
    cfg, err := config.NewConfig("")
    if err != nil {
        log.Fatal(err)
    }

    // 2. Load workflow
    loader := parser.NewLoader(cfg.WorkflowsPath)
    workflow, err := loader.LoadWorkflow("my-module")
    if err != nil {
        log.Fatal(err)
    }

    // 3. Create and configure executor
    exec := executor.NewExecutor()
    exec.SetVerbose(true)
    exec.SetLoader(loader)

    // 4. Execute workflow
    result, err := exec.ExecuteModule(ctx, workflow, map[string]string{
        "target": "example.com",
        "tactic": "default",
    }, cfg)

    if err != nil {
        log.Fatal(err)
    }

    // 5. Check results
    fmt.Printf("Status: %s\n", result.Status)
    for _, step := range result.Steps {
        fmt.Printf("  - %s: %s\n", step.StepName, step.Status)
    }
}
```

--------------------------------

### Install Workflow from Zip URL

Source: https://docs.osmedeus.org/api-references/install

Installs a workflow from a zip archive by providing a URL to the archive. The archive should contain the workflow files.

```bash
curl -X POST http://localhost:8002/osm/api/registry-install \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "workflow",
    "source": "https://example.com/custom-workflow.zip"
  }'
```

--------------------------------

### GET /osm/api/install/status/:binary_name

Source: https://docs.osmedeus.org/reference/rest-api

Checks the installation status of a specific binary.

```APIDOC
## GET /osm/api/install/status/:binary_name

### Description
Check Binary Status

### Method
GET

### Endpoint
/osm/api/install/status/:binary_name
```

--------------------------------

### Basic CLI Run Examples

Source: https://docs.osmedeus.org/getting-started/cli

Demonstrates running workflows or modules against single or multiple targets, using stdin, and custom parameters.

```bash
osmedeus run -f recon-workflow -t example.com
```

```bash
osmedeus run -m simple-module -t target1.com -t target2.com
```

```bash
cat list-of-urls.txt | osmedeus run -m simple-module --concurrency 10
```

```bash
echo "extra.com" | osmedeus run -m simple-module -t main.com -T more-targets.txt
```

```bash
osmedeus run -m simple-module -t example.com --params 'threads=20'
```

```bash
osmedeus run --base-folder /opt/osmedeus-base -f recon-workflow -t example.com
```

```bash
osmedeus run -m recon -t example.com --timeout 2h
```

```bash
osmedeus run -m recon -t example.com --repeat --repeat-wait-time 1h
```

```bash
osmedeus run -m subdomain -m portscan -m vulnscan -t example.com
```

```bash
osmedeus run -m recon -t example.com --timeout 3h --repeat --repeat-wait-time 30m
```

```bash
osmedeus run -m recon -t example.com --dry-run
```

```bash
cat module.yaml | osmedeus run --std-module -t example.com
```

```bash
osmedeus run -m recon -t example.com --params-file params.yaml
```

```bash
osmedeus run -m recon -t example.com --workspace /custom/workspace
```

```bash
osmedeus run -m recon -t example.com --heuristics-check none
```

```bash
osmedeus run -m recon -T targets.txt --concurrency 5
```

--------------------------------

### Setup Existing Machines

Source: https://docs.osmedeus.org/cloud/quick-reference

Set up existing machines by providing their IP addresses. This command allows for the configuration of previously provisioned infrastructure.

```bash
osmedeus cloud setup --reuse-with "1.2.3.4,5.6.7.8"
```

--------------------------------

### Run E2E API Tests

Source: https://docs.osmedeus.org/advanced/development

Command to run end-to-end tests for all API endpoints. This setup involves starting Redis, seeding the database, and starting the server.

```bash
make test-e2e-api
```

--------------------------------

### Install All Required Binaries

Source: https://docs.osmedeus.org/getting-started/cli

Install all essential binaries required for Osmedeus to function correctly. Use '--install-optional' to include optional dependencies.

```bash
osmedeus install binary --all
```

```bash
osmedeus install binary --all --install-optional
```

--------------------------------

### Full Configuration Example

Source: https://docs.osmedeus.org/getting-started/basic-setup

This snippet shows a comprehensive example of an Osmedeus configuration file. It covers settings for database connections, environment paths, LLM providers, notification services, server details, and storage options. Use this as a reference for setting up your own configuration.

```bash
base_folder = $HOME/osmedeus-base
database.connection_timeout = 60
database.db_engine = sqlite
database.db_name = osmedeus
database.db_path = {{base_folder}}/database-osm.sqlite
database.host = localhost
database.password = [REDACTED]
database.port = 5432
database.ssl_mode = disable
database.username = osmedeus
environments.external_agent_configs = {{base_folder}}/external-agent-configs
environments.external_binaries_path = {{base_folder}}/external-binaries
environments.external_configs = {{base_folder}}/external-configs
environments.external_data = {{base_folder}}/external-data
environments.markdown_report_templates = {{base_folder}}/markdown-report-templates
environments.snapshot = {{base_folder}}/snapshot
environments.workflows = {{base_folder}}/workflows
environments.workspaces = $HOME/workspaces-osmedeus
global_vars.CENSYS_API_KEY.as_env = [REDACTED]
global_vars.CENSYS_API_KEY.value = [REDACTED]
global_vars.GITHUB_API_KEY.as_env = [REDACTED]
global_vars.GITHUB_API_KEY.value = [REDACTED]
global_vars.PASSIVETOTAL_API_KEY.as_env = [REDACTED]
global_vars.PASSIVETOTAL_API_KEY.value = [REDACTED]
global_vars.SHODAN_API_KEY.as_env = [REDACTED]
global_vars.SHODAN_API_KEY.value = [REDACTED]
llm_config.custom_headers = 
llm_config.enabled_tool_call = false
llm_config.llm_providers.0.auth_token = [REDACTED]
llm_config.llm_providers.0.base_url = http://localhost:11434/v1/chat/completions
llm_config.llm_providers.0.model = gpt-oss:120b-cloud
llm_config.llm_providers.0.provider = ollama
llm_config.max_retries = 3
llm_config.max_tokens = [REDACTED]
llm_config.n = 1
llm_config.stream = false
llm_config.structured_json_format = false
llm_config.system_prompt = 
llm_config.temperature = 0.7
llm_config.timeout = 120s
llm_config.top_k = 50
llm_config.top_p = 0.9
notification.enabled = false
notification.provider = telegram
notification.telegram.bot_token = [REDACTED]
notification.telegram.chat_id = 0
notification.telegram.enabled = false
redis.connection_timeout = 60
redis.db = 0
redis.host = 
redis.password = [REDACTED]
redis.port = 6379
redis.username = 
scan_tactic.aggressive = 40
scan_tactic.default = 10
scan_tactic.gently = 5
server.host = 0.0.0.0
server.jwt.expiration_minutes = 180
server.jwt.secret_signing_key = [REDACTED]
server.license = open-source
server.password = [REDACTED]
server.port = 8002
server.simple_user_map_key.osmedeus = [REDACTED]
server.ui_path = {{base_folder}}/ui/
server.username = osmedeus
server.workspace_prefix_key = [REDACTED]
storage.access_key_id = [REDACTED]
storage.bucket = 
storage.enabled = false
storage.endpoint = 
storage.provider = s3
storage.region = us-east-1
storage.secret_access_key = [REDACTED]
storage.use_ssl = true
```

--------------------------------

### Get Registry Info

Source: https://docs.osmedeus.org/api-references/install

Fetch binary registry metadata with installation status. Supports two modes: `direct-fetch` (default) and `nix-build`.

```APIDOC
## GET /osm/api/registry-info

### Description
Fetch binary registry metadata with installation status. Supports two modes: `direct-fetch` (default) and `nix-build`.

### Method
GET

### Endpoint
/osm/api/registry-info

### Parameters
#### Query Parameters
- **registry_mode** (string) - Optional - Registry mode: `direct-fetch` or `nix-build`

### Request Example
```bash
curl http://localhost:8002/osm/api/registry-info \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **registry_mode** (string) - Always "direct-fetch"
- **registry_url** (string) - URL of the binary registry source
- **binaries** (object) - Map of binary names to their metadata
  - **binaries[name].desc** (string) - Description of the binary tool
  - **binaries[name].tags** ([]string) - Tags/categories for the binary
  - **binaries[name].version** (string) - Version of the binary
  - **binaries[name].linux** (object) - Linux download URLs by architecture (amd64, arm64)
  - **binaries[name].darwin** (object) - macOS download URLs by architecture
  - **binaries[name].windows** (object) - Windows download URLs by architecture
  - **binaries[name].command-linux** (object) - Linux install commands by architecture
  - **binaries[name].command-darwin** (object) - macOS install commands by architecture
  - **binaries[name].installed** (boolean) - Whether the binary is currently installed
  - **binaries[name].path** (string) - Full path to the installed binary

#### Response Example
```json
{
  "registry_mode": "direct-fetch",
  "registry_url": "https://raw.githubusercontent.com/osmedeus/osmedeus-base/main/registry-metadata.json",
  "binaries": {
    "nuclei": {
      "desc": "Vulnerability scanner",
      "tags": ["vuln", "scanner"],
      "version": "3.0.0",
      "linux": {
        "amd64": "https://github.com/projectdiscovery/nuclei/releases/download/v3.0.0/nuclei_3.0.0_linux_amd64.zip",
        "arm64": "https://github.com/projectdiscovery/nuclei/releases/download/v3.0.0/nuclei_3.0.0_linux_arm64.zip"
      },
      "darwin": {
        "amd64": "https://github.com/projectdiscovery/nuclei/releases/download/v3.0.0/nuclei_3.0.0_darwin_amd64.zip",
        "arm64": "https://github.com/projectdiscovery/nuclei/releases/download/v3.0.0/nuclei_3.0.0_darwin_arm64.zip"
      },
      "installed": true,
      "path": "/usr/local/bin/nuclei"
    },
    "amass": {
      "desc": "In-depth attack surface mapping",
      "tags": ["recon", "subdomain"],
      "version": "4.0.0",
      "linux": {
        "amd64": "https://github.com/owasp-amass/amass/releases/download/v4.0.0/amass_linux_amd64.zip"
      },
      "darwin": {
        "amd64": "https://github.com/owasp-amass/amass/releases/download/v4.0.0/amass_darwin_amd64.zip"
      },
      "installed": false,
      "path": ""
    }
  }
}
```
```

--------------------------------

### Export Function Result

Source: https://docs.osmedeus.org/functions/reference.md

Execute a function and export its result to a variable for later use. This example gets the file length and exports it as 'result_count'.

```yaml
- name: count
  type: function
  function: file_length("{{Output}}/results.txt")
  exports:
    result_count: "{{result}}"

- name: report
  type: function
  function: log_info("Found " + result_count + " results")
```

--------------------------------

### GET /osm/api/vulnerabilities/diff

Source: https://docs.osmedeus.org/reference/rest-api

Compare vulnerabilities between two time points within a specified workspace. It allows filtering by a start time and optionally an end time.

```APIDOC
## GET /osm/api/vulnerabilities/diff

### Description
Compare vulnerabilities between two time points.

### Method
GET

### Endpoint
/osm/api/vulnerabilities/diff

### Parameters
#### Query Parameters
- **workspace** (string) - Required - Workspace name
- **from** (string) - Required - Start time (RFC3339 or Unix timestamp)
- **to** (string) - Optional - End time (default: now)

### Response
#### Success Response (200)
- **data** (object) - Contains the vulnerability diff details.
  - **workspace_name** (string)
  - **from_time** (string)
  - **to_time** (string)
  - **added** (array) - List of added vulnerabilities.
  - **removed** (array) - List of removed vulnerabilities.
  - **changed** (array) - List of changed vulnerabilities.
  - **summary** (object) - Summary of changes.
    - **total_added** (integer)
    - **total_removed** (integer)
    - **total_changed** (integer)

### Response Example
```json
{
  "data": {
    "workspace_name": "example_com",
    "from_time": "2025-01-01T00:00:00Z",
    "to_time": "2025-01-15T00:00:00Z",
    "added": [
      {
        "id": 789,
        "vuln_info": "CVE-2025-1234",
        "asset_value": "api.example.com",
        "severity": "critical",
        "template_id": "CVE-2025-1234",
        "created_at": "2025-01-12T08:00:00Z"
      }
    ],
    "removed": [],
    "changed": [],
    "summary": {
      "total_added": 1,
      "total_removed": 0,
      "total_changed": 0
    }
  }
}
```
```

--------------------------------

### Single Host Deployment: Docker Container

Source: https://docs.osmedeus.org/advanced/deployment

Docker commands to run Osmedeus as a container, including basic setup and an example with custom workflow and workspace volumes.

```bash
# Basic server
docker run -d \
  --name osmedeus \
  -p 8001:8001 \
  -v osmedeus-data:/root/osmedeus-base \
  -v workspaces:/root/workspaces-osmedeus \
  osmedeus:latest

# With custom workflows
docker run -d \
  --name osmedeus \
  -p 8001:8001 \
  -v /path/to/workflows:/root/osmedeus-base/workflows \
  -v /path/to/workspaces:/root/workspaces-osmedeus \
  osmedeus:latest
```

--------------------------------

### Workflow Step Dependencies Example

Source: https://docs.osmedeus.org/api-references/workflows

This JSON snippet demonstrates how to define dependencies between workflow steps using the `depends_on` field. Steps listed in `depends_on` must complete successfully before the current step can start.

```json
{
  "steps": [
    {
      "index": 0,
      "name": "step-a",
      "type": "bash",
      "command": "echo A"
    },
    {
      "index": 1,
      "name": "step-b",
      "type": "bash",
      "command": "echo B",
      "depends_on": ["step-a"]
    },
    {
      "index": 2,
      "name": "step-c",
      "type": "bash",
      "command": "echo C",
      "depends_on": ["step-a", "step-b"]
    }
  ]
}
```

--------------------------------

### Configure Spot Instances and Cost Limits

Source: https://docs.osmedeus.org/cloud/quick-reference

Enable the use of spot instances for significant cost savings and set limits on hourly and total spend, as well as the maximum number of instances.

```bash
osmedeus cloud config set providers.aws.use_spot true
osmedeus cloud config set limits.max_hourly_spend 1.00
osmedeus cloud config set limits.max_total_spend 10.00
osmedeus cloud config set limits.max_instances 10
```

--------------------------------

### Get Registry Info (Nix-Build Mode)

Source: https://docs.osmedeus.org/api-references/install

Retrieves information about Nix flake binaries available in the registry, grouped by category. This is useful for understanding what tools are available and their installation status when using Nix-build mode.

```APIDOC
## GET /osm/api/registry-info?registry_mode=nix-build

### Description
Returns Nix flake binaries grouped by category with registry metadata.

### Method
GET

### Endpoint
/osm/api/registry-info

#### Query Parameters
- **registry_mode** (string) - Required - Must be "nix-build"

### Response
#### Success Response (200)
- **registry_mode** (string) - Always "nix-build"
- **nix_installed** (boolean) - Whether Nix package manager is installed
- **categories** (array) - List of tool categories from flake.nix
  - **categories[].name** (string) - Category name (e.g., "Subdomain", "Vuln")
  - **categories[].tools** (array) - List of tools in this category
    - **categories[].tools[].name** (string) - Binary name
    - **categories[].tools[].desc** (string) - Description from registry
    - **categories[].tools[].tags** ([]string) - Tags from registry
    - **categories[].tools[].version** (string) - Version from registry
    - **categories[].tools[].repo_link** (string) - Repository URL
    - **categories[].tools[].installed** (boolean) - Whether the binary is installed
    - **categories[].tools[].path** (string) - Full path to installed binary

### Request Example
```bash
curl "http://localhost:8002/osm/api/registry-info?registry_mode=nix-build" \
  -H "Authorization: Bearer $TOKEN"
```

### Response Example
```json
{
  "registry_mode": "nix-build",
  "nix_installed": true,
  "categories": [
    {
      "name": "Subdomain",
      "tools": [
        {
          "name": "amass",
          "desc": "In-depth attack surface mapping and asset discovery",
          "tags": ["recon", "subdomain"],
          "version": "4.2.0",
          "repo_link": "https://github.com/owasp-amass/amass",
          "installed": true,
          "path": "/home/user/.nix-profile/bin/amass"
        },
        {
          "name": "subfinder",
          "desc": "Fast passive subdomain enumeration tool",
          "tags": ["recon", "subdomain"],
          "version": "2.6.0",
          "installed": false
        }
      ]
    },
    {
      "name": "Vuln",
      "tools": [
        {
          "name": "nuclei",
          "desc": "Fast, customizable vulnerability scanner",
          "tags": ["vuln", "scanner"],
          "version": "3.0.0",
          "installed": true,
          "path": "/home/user/.nix-profile/bin/nuclei"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Run Spot Instance Pipeline

Source: https://docs.osmedeus.org/cloud/provider-aws

Execute a multi-stage scanning pipeline using inexpensive spot instances. This example configures spot instances, runs subfinder, httpx, and nuclei sequentially, and cleans up automatically.

```bash
# Configure spot
osmedeus cloud config set providers.aws.use_spot true
osmedeus cloud config set providers.aws.instance_type t3.large

# Run a heavy scan for cheap
osmedeus cloud run \
  --custom-cmd "subfinder -d {{Target}} -all -o /tmp/osm-custom/subs.txt" \
  --custom-cmd "cat /tmp/osm-custom/subs.txt | httpx -td -o /tmp/osm-custom/live.txt" \
  --custom-cmd "cat /tmp/osm-custom/live.txt | nuclei -o /tmp/osm-custom/nuclei.txt" \
  --sync-path "/tmp/osm-custom/" \
  -t example.com --auto-destroy
```

--------------------------------

### Registry Info Response (Direct-Fetch Mode)

Source: https://docs.osmedeus.org/api-references/install

Example JSON response when fetching registry information in direct-fetch mode. It includes details about available binaries like nuclei and amass, their versions, download URLs, and installation status.

```json
{
  "registry_mode": "direct-fetch",
  "registry_url": "https://raw.githubusercontent.com/osmedeus/osmedeus-base/main/registry-metadata.json",
  "binaries": {
    "nuclei": {
      "desc": "Vulnerability scanner",
      "tags": ["vuln", "scanner"],
      "version": "3.0.0",
      "linux": {
        "amd64": "https://github.com/projectdiscovery/nuclei/releases/download/v3.0.0/nuclei_3.0.0_linux_amd64.zip",
        "arm64": "https://github.com/projectdiscovery/nuclei/releases/download/v3.0.0/nuclei_3.0.0_linux_arm64.zip"
      },
      "darwin": {
        "amd64": "https://github.com/projectdiscovery/nuclei/releases/download/v3.0.0/nuclei_3.0.0_darwin_amd64.zip",
        "arm64": "https://github.com/projectdiscovery/nuclei/releases/download/v3.0.0/nuclei_3.0.0_darwin_arm64.zip"
      },
      "installed": true,
      "path": "/usr/local/bin/nuclei"
    },
    "amass": {
      "desc": "In-depth attack surface mapping",
      "tags": ["recon", "subdomain"],
      "version": "4.0.0",
      "linux": {
        "amd64": "https://github.com/owasp-amass/amass/releases/download/v4.0.0/amass_linux_amd64.zip"
      },
      "darwin": {
        "amd64": "https://github.com/owasp-amass/amass/releases/download/v4.0.0/amass_darwin_amd64.zip"
      },
      "installed": false,
      "path": ""
    }
  }
}
```

--------------------------------

### Precompiled Template Usage Example

Source: https://docs.osmedeus.org/architecture/templates

Demonstrates how to precompile templates for a workflow at load time and retrieve them during execution.

```go
// At workflow load time
registry := NewPrecompiledRegistry()
templates := map[string]string{
    "scan:command": "nuclei -l {{Output}}/urls.txt",
    "scan:exports:result": "{{Output}}/nuclei.json",
}
registry.PrecompileWorkflow("my-workflow", templates)

// At execution time
if tpl := registry.GetPrecompiled("my-workflow", "scan:command"); tpl != nil {
    // Use pre-compiled template
}
```

--------------------------------

### View Logs in Basic Setup

Source: https://docs.osmedeus.org/getting-started/docker-setup

Follows the logs of all services defined in the basic docker-compose.yml file. Press Ctrl+C to stop following.

```bash
docker compose -f build/docker/docker-compose.yml logs -f
```

--------------------------------

### Check Installed Tools

Source: https://docs.osmedeus.org/others/faq

Verify if all required tools are installed on the system. This command checks the binary installations.

```bash
osmedeus install binary --all --check
```

--------------------------------

### API Pagination Example

Source: https://docs.osmedeus.org/api-references/reference

Demonstrates how to paginate through list endpoints using offset and limit query parameters. Ensure your Authorization token is set.

```bash
curl "http://localhost:8002/osm/api/assets?offset=100&limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Build Project

Source: https://docs.osmedeus.org/advanced/development

Compile the project from source code.

```bash
make build
```

--------------------------------

### Install Specific Binaries

Source: https://docs.osmedeus.org/getting-started/cli

Install one or more specific binaries by name. This command allows granular control over which tools are installed.

```bash
osmedeus install binary --name nuclei --name httpx
```

--------------------------------

### Install Osmedeus via Homebrew

Source: https://docs.osmedeus.org/quickstart

Install Osmedeus using the Homebrew package manager. Ensure you have Homebrew installed on your system.

```bash
brew install osmedeus/tap/osmedeus
```

--------------------------------

### List Available Binaries for Direct Fetch

Source: https://docs.osmedeus.org/getting-started/cli

List binaries available in the registry for direct fetching. This is useful for understanding what can be installed directly.

```bash
osmedeus install binary --list-registry-direct-fetch
```

--------------------------------

### List Nix-Available Binaries

Source: https://docs.osmedeus.org/reference/cli-references

Lists all binaries that can be installed via Nix.

```bash
# List available binaries
osmedeus install binary --list-registry-nix-build
```
Tokens:
Raw