osmedeus/server/API-SPEC.md

Osmedeus API Specification

Generated by LLM

• Osmedeus API Specification
  • Overview
  • Base URL
  • Authentication
    • 1. JWT Token Authentication (Default)
    • 2. Basic Authentication (Optional)
    • 3. No Authentication (Development Mode)
  • API Endpoints
    • Authentication
      • Login
    • System Health
      • Health Check
      • Ping
    • Workspaces
      • List All Workspaces
      • Get Workspace Details
      • Delete Workspace
    • Scans
      • List All Scans
      • Start New Scan
    • Processes
      • List Running Processes
    • Workflows
      • List Available Workflows
    • File Operations
      • Upload Data
    • Static Content
      • Workspace Files
      • Storage Files
    • Utility
      • Raw Directory Information
      • Helper Message
  • Example Scanning request
    • Basic Scanning
    • Scanning with URL workflow

Overview

Osmedeus is a workflow engine for offensive security testing. This API provides endpoints to manage workspaces, execute scans, and monitor processes.

Base URL

• Local: http://localhost:8000
• With SSL: https://localhost:8443

Authentication

The API supports two authentication methods:

1. JWT Token Authentication (Default)

• Login Endpoint: POST /api/login
• Token Header: Authorization: Osmedeus <token>
• Token Expiry: 30 days

2. Basic Authentication (Optional)

• Username: osmedeus
• Password: Configured master password
• Header: Authorization: Basic <base64(username:password)>

3. No Authentication (Development Mode)

• Enabled with -A flag

API Endpoints

Authentication

Login

Authenticate user and obtain JWT token.

Endpoint: POST /api/login

Request Body:

{
  "username": "admin",
  "password": "your_password"
}

Response:

{
  "status": "success",
  "message": "Successfully login",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Status Codes:

• 200: Success
• 401: Unauthorized
• 500: Internal Server Error

System Health

Health Check

Check server health status and version.

Endpoint: GET /api/osmp/health

Response:

{
  "status": 200,
  "data": {
    "version": "v4.5.0"
  },
  "message": "server is up"
}

Ping

Simple connectivity check.

Endpoint: GET /ping

Response:

{
  "status": 200,
  "message": "pong"
}

Workspaces

List All Workspaces

Get all available workspaces.

Endpoint: GET /api/osmp/workspaces

Response:

{
  "status": 200,
  "data": [...],
  "type": "workspaces",
  "total": 42,
  "message": "List all of Workspaces"
}

Get Workspace Details

Get detailed information about a specific workspace including reports.

Endpoint: GET /api/osmp/workspace/{wsname}

Path Parameters:

• wsname (string): Workspace name

Response:

{
  "status": 200,
  "data": {
    "workspace": {...},
    "reports": {
      "subdomain": ["/static/workspaces/target/subdomain.txt"],
      "portscan": ["/static/workspaces/target/portscan.html"]
    }
  },
  "type": "workspace",
  "message": "Workspace Detail"
}

Delete Workspace

Delete a workspace and all its associated files.

Endpoint: DELETE /api/osmp/delete/{wsname}

Path Parameters:

• wsname (string): Workspace name

Response:

{
  "status": 200,
  "type": "delete",
  "message": "Workspace Deleted"
}

Status Codes:

• 200: Success
• 400: Workspace doesn't exist

Scans

List All Scans

Get all running and completed scan processes.

Endpoint: GET /api/osmp/scans

Response:

{
  "status": 200,
  "data": [...],
  "type": "scans",
  "total": 15,
  "message": "List all the scan process"
}

Start New Scan

Execute a new scan with specified configuration.

Endpoint: POST /api/osmp/execute

Request Body:

{
  "target": "example.com",
  "workflow": "general",
  "workspace": "my-project",
  "threads": 10,
  "timeout": "1h",
  "debug": false
}

Advanced Request Examples:

Single Target:

{
  "target": "example.com",
  "workflow": "general"
}

Multiple Targets:

{
  "targets": ["1.2.3.4/24", "5.6.7.8/24"],
  "as_file": true,
  "workflow": "cidr"
}

With Custom Parameters:

{
  "target": "example.com",
  "workflow": "general",
  "params": ["-deep", "-aggressive"],
  "distributed": true,
  "concurrency": 5
}

Response:

{
  "status": 200,
  "data": {
    "command": "osmedeus scan -f general -t example.com -w my-project",
    "input": "example.com",
    "workspace": "my-project"
  },
  "type": "new-scan",
  "message": "New Scan Imported"
}

Request Schema:

• target (string): Target to scan
• targets (array): List of targets to scan (optional)
• workflow (string): Workflow name to execute (default: "general")
• workspace (string): Workspace name (optional)
• module (string): Plugin name to run (optional)
• threads (integer): Number of concurrent threads (optional)
• timeout (string): Scan timeout (e.g., "1h", "30m") (optional)
• concurrency (integer): Concurrency level (optional)
• distributed (boolean): Enable distributed scanning (optional)
• params (array): Additional parameters (optional)
• debug (boolean): Enable debug mode (optional)
• test (boolean): Test mode without actual execution (optional)

Processes

List Running Processes

Get all currently running Osmedeus processes.

Endpoint: GET /api/osmp/ps

Response:

{
  "status": 200,
  "data": [...],
  "type": "processes",
  "total": 5,
  "message": "List all osm process"
}

Workflows

List Available Workflows

Get all available workflow configurations and their modules.

Endpoint: GET /api/osmp/flows

Response:

{
  "status": 200,
  "data": [
    {
      "name": "general",
      "desc": "General reconnaissance workflow",
      "modules": "subdomain,portscan,vulnscan"
    }
  ],
  "total": 12,
  "type": "flows",
  "message": "Workflows Listing"
}

File Operations

Upload Data

Upload target data or configuration files.

Endpoint: POST /api/osmp/upload

Request Body:

{
  "data": "example.com\nsub.example.com",
  "filename": "targets.txt"
}

Response:

{
  "status": 200,
  "data": {
    "filepath": "/tmp/osmedeus-input/targets.txt"
  },
  "type": "upload",
  "message": "New Data Uploaded"
}

Static Content

Workspace Files

Access workspace files and reports.

Endpoint: GET /{static_prefix}/workspaces/{path...}

Example: GET /static/workspaces/target/subdomain.txt

Storage Files

Access storage files and configurations.

Endpoint: GET /{static_prefix}/storages/{path...}

Example: GET /static/storages/cloud-configs/aws.json

Utility

Raw Directory Information

Get raw directory structure for workspaces, storages, and logs.

Endpoint: GET /api/osmp/raw

Response:

{
  "status": 200,
  "data": {
    "storages": "/static/storages/",
    "workspaces": "/static/workspaces/",
    "logs": "/static/logs/"
  },
  "type": "raw",
  "message": "Raw directory"
}

Helper Message

Get help information and documentation links.

Endpoint: GET /api/osmp/help

Response:

{
  "status": 200,
  "data": {
    "version": "v4.5.0",
    "doc": "https://docs.osmedeus.org",
    "message": "[*] Visit this page for complete Usage: https://docs.osmedeus.org"
  },
  "type": "helper",
  "message": "Helper message"
}

Example Scanning request

Basic Scanning

POST /api/osmp/execute HTTP/1.1
Host: 127.0.0.1:8000
User-Agent: curl/8.7.1
Accept: */*
Connection: keep-alive
Authorization: <your-auth>
Content-Type: application/json
Content-Length: 334

{
	"target":"sample.io",
	"flow":"general"
}

Scanning with URL workflow

POST /api/osmp/execute HTTP/1.1
Host: 127.0.0.1:8000
User-Agent: curl/8.7.1
Accept: */*
Connection: keep-alive
Authorization: <your-auth>
Content-Type: application/json
Content-Length: 334

{
  "targets": [
    "origin-lite-www.example.com",
    "partner.example.com",
    "partners.example.com",
    "polri.example.com",
    "retailenabler.example.com",
    "seller-id.example.com",
    "shop-id.example.com",
    "sobat.example.com"
  ],
  "as_file": true,
  "debug": true,
  "workspace": "custom-workspace",
  "workflow": "url"
}