mirror of
https://github.com/j3ssie/osmedeus.git
synced 2026-09-09 19:27:48 +02:00
Complete rewrite and re-architecture Osmedeus Engine in v5
This commit is contained in:
j3ssie
@@ -0,0 +1,374 @@
|
||||
# API Reference
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints return errors in a consistent format:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": true,
|
||||
"message": "Error description"
|
||||
}
|
||||
```
|
||||
|
||||
**Common HTTP Status Codes:**
|
||||
- `200` - Success
|
||||
- `201` - Created
|
||||
- `202` - Accepted (async operation started)
|
||||
- `400` - Bad Request (invalid input)
|
||||
- `401` - Unauthorized (missing or invalid token)
|
||||
- `404` - Not Found
|
||||
- `500` - Internal Server Error
|
||||
|
||||
---
|
||||
|
||||
## Pagination
|
||||
|
||||
Endpoints that return lists support pagination via query parameters:
|
||||
|
||||
| Parameter | Default | Max | Description |
|
||||
|-----------|---------|-----|-------------|
|
||||
| `offset` | 0 | - | Number of records to skip |
|
||||
| `limit` | 20 | 10000 | Maximum records to return |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl "http://localhost:8002/osm/api/assets?offset=100&limit=50" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cron Expression Reference
|
||||
|
||||
Schedules use standard cron expressions:
|
||||
|
||||
```
|
||||
┌───────────── minute (0-59)
|
||||
│ ┌───────────── hour (0-23)
|
||||
│ │ ┌───────────── day of month (1-31)
|
||||
│ │ │ ┌───────────── month (1-12)
|
||||
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
|
||||
│ │ │ │ │
|
||||
* * * * *
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
- `0 2 * * *` - Every day at 2:00 AM
|
||||
- `0 0 * * 0` - Every Sunday at midnight
|
||||
- `*/30 * * * *` - Every 30 minutes
|
||||
- `0 9-17 * * 1-5` - Every hour from 9 AM to 5 PM, Monday to Friday
|
||||
|
||||
---
|
||||
|
||||
## Workflow Step Types
|
||||
|
||||
Reference documentation for workflow step types used in YAML workflow definitions.
|
||||
|
||||
### bash
|
||||
|
||||
Execute shell commands on the local system or configured runner.
|
||||
|
||||
```yaml
|
||||
- name: run-nuclei
|
||||
type: bash
|
||||
log: "Running nuclei scan"
|
||||
command: nuclei -u {{Target}} -o {{Output}}/nuclei.txt
|
||||
timeout: 3600
|
||||
exports:
|
||||
nuclei_results: "{{Output}}/nuclei.txt"
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | string | Yes | Unique step name |
|
||||
| `type` | string | Yes | Must be `bash` |
|
||||
| `command` | string | No* | Single command to execute |
|
||||
| `commands` | array | No* | Sequential commands |
|
||||
| `parallel_commands` | array | No* | Commands to run in parallel |
|
||||
| `timeout` | int | No | Timeout in seconds |
|
||||
| `log` | string | No | Log message displayed during execution |
|
||||
| `pre_condition` | string | No | Condition that must be true to run |
|
||||
| `exports` | map | No | Variables to export after execution |
|
||||
|
||||
*One of `command`, `commands`, or `parallel_commands` is required.
|
||||
|
||||
---
|
||||
|
||||
### function
|
||||
|
||||
Execute utility functions written in JavaScript via Otto VM.
|
||||
|
||||
```yaml
|
||||
- name: check-file
|
||||
type: function
|
||||
log: "Checking if results exist"
|
||||
function: fileExists("{{Output}}/results.txt")
|
||||
exports:
|
||||
has_results: "{{check_file_output}}"
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | string | Yes | Unique step name |
|
||||
| `type` | string | Yes | Must be `function` |
|
||||
| `function` | string | No* | Single function to execute |
|
||||
| `functions` | array | No* | Sequential functions |
|
||||
| `parallel_functions` | array | No* | Functions to run in parallel |
|
||||
|
||||
*One of `function`, `functions`, or `parallel_functions` is required.
|
||||
|
||||
---
|
||||
|
||||
### parallel-steps
|
||||
|
||||
Run multiple steps concurrently.
|
||||
|
||||
```yaml
|
||||
- name: parallel-scans
|
||||
type: parallel-steps
|
||||
log: "Running scans in parallel"
|
||||
parallel_steps:
|
||||
- name: nuclei-scan
|
||||
type: bash
|
||||
command: nuclei -u {{Target}}
|
||||
- name: httpx-scan
|
||||
type: bash
|
||||
command: httpx -u {{Target}}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | string | Yes | Unique step name |
|
||||
| `type` | string | Yes | Must be `parallel-steps` |
|
||||
| `parallel_steps` | array | Yes | Array of steps to run concurrently |
|
||||
|
||||
---
|
||||
|
||||
### foreach
|
||||
|
||||
Iterate over items from a file or array.
|
||||
|
||||
```yaml
|
||||
- name: scan-subdomains
|
||||
type: foreach
|
||||
log: "Scanning each subdomain"
|
||||
input: "{{Output}}/subdomains.txt"
|
||||
variable: subdomain
|
||||
step:
|
||||
name: scan-subdomain
|
||||
type: bash
|
||||
command: httpx -u [[subdomain]]
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | string | Yes | Unique step name |
|
||||
| `type` | string | Yes | Must be `foreach` |
|
||||
| `input` | string | Yes | File path or array to iterate over |
|
||||
| `variable` | string | Yes | Loop variable name (use `[[variable]]`) |
|
||||
| `step` | object | Yes | Step to execute for each item |
|
||||
| `parallel` | int | No | Number of parallel iterations |
|
||||
|
||||
---
|
||||
|
||||
### remote-bash
|
||||
|
||||
Execute commands in Docker containers or via SSH.
|
||||
|
||||
```yaml
|
||||
- name: docker-scan
|
||||
type: remote-bash
|
||||
log: "Running scan in Docker"
|
||||
step_runner: docker
|
||||
step_runner_config:
|
||||
image: "projectdiscovery/nuclei:latest"
|
||||
volumes:
|
||||
- "{{Output}}:/output"
|
||||
command: nuclei -u {{Target}} -o /output/nuclei.txt
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | string | Yes | Unique step name |
|
||||
| `type` | string | Yes | Must be `remote-bash` |
|
||||
| `step_runner` | string | Yes | `docker` or `ssh` |
|
||||
| `step_runner_config` | object | No | Runner-specific configuration |
|
||||
| `command` | string | No* | Command to execute |
|
||||
| `commands` | array | No* | Sequential commands |
|
||||
|
||||
**Docker Configuration:**
|
||||
```yaml
|
||||
step_runner_config:
|
||||
image: "image:tag"
|
||||
volumes: ["host:container"]
|
||||
env:
|
||||
KEY: value
|
||||
network: "host"
|
||||
workdir: "/app"
|
||||
```
|
||||
|
||||
**SSH Configuration:**
|
||||
```yaml
|
||||
step_runner_config:
|
||||
host: "worker.example.com"
|
||||
user: "ubuntu"
|
||||
key_file: "~/.ssh/id_rsa"
|
||||
port: 22
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### http
|
||||
|
||||
Make HTTP requests and capture responses.
|
||||
|
||||
```yaml
|
||||
- name: api-request
|
||||
type: http
|
||||
log: "Calling API"
|
||||
url: "https://api.example.com/endpoint"
|
||||
method: POST
|
||||
headers:
|
||||
Content-Type: "application/json"
|
||||
Authorization: "Bearer {{api_token}}"
|
||||
request_body: '{"domain": "{{Target}}"}'
|
||||
timeout: 30
|
||||
exports:
|
||||
api_response: "{{api_request_body}}"
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | string | Yes | Unique step name |
|
||||
| `type` | string | Yes | Must be `http` |
|
||||
| `url` | string | Yes | Request URL |
|
||||
| `method` | string | No | HTTP method (default: GET) |
|
||||
| `headers` | map | No | Request headers |
|
||||
| `request_body` | string | No | Request body for POST/PUT |
|
||||
| `timeout` | int | No | Timeout in seconds |
|
||||
|
||||
**Auto-Exports:**
|
||||
- `<step_name>_status_code` - HTTP status code
|
||||
- `<step_name>_body` - Response body
|
||||
- `<step_name>_headers` - Response headers
|
||||
|
||||
---
|
||||
|
||||
### llm
|
||||
|
||||
Execute LLM (Large Language Model) API calls for AI-powered analysis.
|
||||
|
||||
```yaml
|
||||
- name: analyze-target
|
||||
type: llm
|
||||
log: "Analyzing target with LLM"
|
||||
messages:
|
||||
- role: system
|
||||
content: "You are a security analyst."
|
||||
- role: user
|
||||
content: "Analyze the security of {{Target}}"
|
||||
llm_config:
|
||||
max_tokens: 1000
|
||||
temperature: 0.7
|
||||
timeout: 60
|
||||
exports:
|
||||
analysis: "{{analyze_target_content}}"
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | string | Yes | Unique step name |
|
||||
| `type` | string | Yes | Must be `llm` |
|
||||
| `messages` | array | No* | Chat messages (role + content) |
|
||||
| `is_embedding` | bool | No | Set to true for embeddings |
|
||||
| `embedding_input` | array | No* | Strings to embed |
|
||||
| `llm_config` | object | No | Step-level LLM configuration |
|
||||
| `tools` | array | No | Tool definitions for function calling |
|
||||
| `tool_choice` | string | No | Tool selection (`auto`, `none`, etc.) |
|
||||
| `extra_llm_parameters` | map | No | Additional provider-specific params |
|
||||
| `timeout` | int | No | Timeout in seconds |
|
||||
|
||||
*Either `messages` or `embedding_input` (with `is_embedding: true`) is required.
|
||||
|
||||
**Message Format:**
|
||||
```yaml
|
||||
messages:
|
||||
- role: system
|
||||
content: "System prompt"
|
||||
- role: user
|
||||
content: "User message with {{variables}}"
|
||||
```
|
||||
|
||||
**Multimodal Messages (with images):**
|
||||
```yaml
|
||||
messages:
|
||||
- role: user
|
||||
content:
|
||||
- type: text
|
||||
text: "What do you see in this screenshot?"
|
||||
- type: image_url
|
||||
image_url:
|
||||
url: "data:image/png;base64,{{screenshot_base64}}"
|
||||
```
|
||||
|
||||
**LLM Configuration Override:**
|
||||
```yaml
|
||||
llm_config:
|
||||
model: "gpt-4"
|
||||
max_tokens: 2000
|
||||
temperature: 0.3
|
||||
response_format:
|
||||
type: json_object
|
||||
```
|
||||
|
||||
**Embeddings:**
|
||||
```yaml
|
||||
- name: generate-embeddings
|
||||
type: llm
|
||||
is_embedding: true
|
||||
embedding_input:
|
||||
- "{{Target}} security analysis"
|
||||
- "vulnerability assessment"
|
||||
exports:
|
||||
embeddings: "{{generate_embeddings_llm_resp}}"
|
||||
```
|
||||
|
||||
**Tool Calling:**
|
||||
```yaml
|
||||
- name: with-tools
|
||||
type: llm
|
||||
messages:
|
||||
- role: user
|
||||
content: "What DNS records exist for {{Target}}?"
|
||||
tools:
|
||||
- type: function
|
||||
function:
|
||||
name: dns_lookup
|
||||
description: "Look up DNS records"
|
||||
parameters:
|
||||
type: object
|
||||
properties:
|
||||
domain:
|
||||
type: string
|
||||
required: [domain]
|
||||
tool_choice: auto
|
||||
```
|
||||
|
||||
**Auto-Exports:**
|
||||
- `<step_name>_llm_resp` - Full response object (id, model, usage, content, tool_calls)
|
||||
- `<step_name>_content` - Just the content string for easy access
|
||||
Reference in New Issue
Block a user