mirror of
https://github.com/j3ssie/osmedeus.git
synced 2026-09-12 04:37:47 +02:00
457 lines
9.0 KiB
Markdown
457 lines
9.0 KiB
Markdown
# Osmedeus API Specification
|
|
|
|
> Generated by LLM
|
|
|
|
- [Osmedeus API Specification](#osmedeus-api-specification)
|
|
- [Overview](#overview)
|
|
- [Base URL](#base-url)
|
|
- [Authentication](#authentication)
|
|
- [1. JWT Token Authentication (Default)](#1-jwt-token-authentication-default)
|
|
- [2. Basic Authentication (Optional)](#2-basic-authentication-optional)
|
|
- [3. No Authentication (Development Mode)](#3-no-authentication-development-mode)
|
|
- [API Endpoints](#api-endpoints)
|
|
- [Authentication](#authentication-1)
|
|
- [Login](#login)
|
|
- [System Health](#system-health)
|
|
- [Health Check](#health-check)
|
|
- [Ping](#ping)
|
|
- [Workspaces](#workspaces)
|
|
- [List All Workspaces](#list-all-workspaces)
|
|
- [Get Workspace Details](#get-workspace-details)
|
|
- [Delete Workspace](#delete-workspace)
|
|
- [Scans](#scans)
|
|
- [List All Scans](#list-all-scans)
|
|
- [Start New Scan](#start-new-scan)
|
|
- [Processes](#processes)
|
|
- [List Running Processes](#list-running-processes)
|
|
- [Workflows](#workflows)
|
|
- [List Available Workflows](#list-available-workflows)
|
|
- [File Operations](#file-operations)
|
|
- [Upload Data](#upload-data)
|
|
- [Static Content](#static-content)
|
|
- [Workspace Files](#workspace-files)
|
|
- [Storage Files](#storage-files)
|
|
- [Utility](#utility)
|
|
- [Raw Directory Information](#raw-directory-information)
|
|
- [Helper Message](#helper-message)
|
|
- [Example Scanning request](#example-scanning-request)
|
|
- [Basic Scanning](#basic-scanning)
|
|
- [Scanning with URL workflow](#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**:
|
|
```json
|
|
{
|
|
"username": "admin",
|
|
"password": "your_password"
|
|
}
|
|
```
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"status": 200,
|
|
"data": {
|
|
"version": "v4.5.0"
|
|
},
|
|
"message": "server is up"
|
|
}
|
|
```
|
|
|
|
#### Ping
|
|
Simple connectivity check.
|
|
|
|
**Endpoint**: `GET /ping`
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"status": 200,
|
|
"message": "pong"
|
|
}
|
|
```
|
|
|
|
### Workspaces
|
|
|
|
#### List All Workspaces
|
|
Get all available workspaces.
|
|
|
|
**Endpoint**: `GET /api/osmp/workspaces`
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"target": "example.com",
|
|
"workflow": "general",
|
|
"workspace": "my-project",
|
|
"threads": 10,
|
|
"timeout": "1h",
|
|
"debug": false
|
|
}
|
|
```
|
|
|
|
**Advanced Request Examples**:
|
|
|
|
**Single Target**:
|
|
```json
|
|
{
|
|
"target": "example.com",
|
|
"workflow": "general"
|
|
}
|
|
```
|
|
|
|
**Multiple Targets**:
|
|
```json
|
|
{
|
|
"targets": ["1.2.3.4/24", "5.6.7.8/24"],
|
|
"as_file": true,
|
|
"workflow": "cidr"
|
|
}
|
|
```
|
|
|
|
**With Custom Parameters**:
|
|
```json
|
|
{
|
|
"target": "example.com",
|
|
"workflow": "general",
|
|
"params": ["-deep", "-aggressive"],
|
|
"distributed": true,
|
|
"concurrency": 5
|
|
}
|
|
```
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"data": "example.com\nsub.example.com",
|
|
"filename": "targets.txt"
|
|
}
|
|
```
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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"
|
|
}
|
|
``` |