Listener API

Overview

The Listener API in Meduza provides functionality to create, manage, and interact with C2 (Command and Control) infrastructure. This API supports multiple listener types (HTTP, TCP, SMB, and external) and handles their lifecycle.

UI endpoints (Client facing)

These requests are handled by the frontend. They remain approximately the same for different kinds but the documentation will be using the http listener for demonstration. To perform the requests, the user must be authenticated to the teamserver using a JWT token. If the requests are performed using Postman or some other tool (like curl), the user will need to provide an authentication token in the request header as a Bearer token.

Create a Listener

Creates a new listener configuration.

Endpoint: POST /api/v1/listeners

Request Body:

{
  "kind": "http",
  "name": "primary-listener",
  "description": "Main HTTP listener",
  "heartbeat": 60
}

Successful Response:

{
  "status": "success",
  "message": "Listener created",
  "data": null
}

Get All Listeners

Retrieves a list of all configured listeners.

Endpoint: GET /api/v1/listeners

Request Body:

No body is required to perform the request.

Successful Response:

{
  "status": "success",
  "message": "Listeners retrieved successfully",
  "data": [
    {
      "id": "f8d7e9a1-c4b6-4a8c-9e2d-3f5c7b9e8a1d",
      "kind": "http",
      "status": "running",
      "name": "primary-listener",
      "description": "Main HTTP listener",
      "external": false,
      "host": "localhost",
      "port": 8010,
      "heartbeat": 60,
      "config": {... kind specific config ... },
      "created_at": "2024-09-12T15:30:45Z",
      "updated_at": "2024-09-12T15:30:45Z",
      "started_at": "2024-09-12T15:31:05Z",
      "stopped_at": null
    },
...
  ]
}

Get Listener by ID

Retrieves a specific listener by ID.

Endpoint: GET /api/v1/listeners/{listener_id}

Request Body:

No body is required to perform the request.

Successful Response:

{
  "status": "success",
  "message": "Listener retrieved successfully",
  "data": {
    "id": "f8d7e9a1-c4b6-4a8c-9e2d-3f5c7b9e8a1d",
    "kind": "http",
    "status": "running",
    "name": "primary-listener",
    "description": "Main HTTP listener",
    "external": false,
    "host": "localhost",
    "port": 8010,
    "heartbeat": 60,
    "config": {},
    "created_at": "2024-09-12T15:30:45Z",
    "updated_at": "2024-09-12T15:30:45Z",
    "started_at": "2024-09-12T15:31:05Z",
    "stopped_at": null
  }
}

Get Listener by Name

Retrieves a specific listener by name.

Endpoint: GET /api/v1/listeners/{listener_name}

Request Body:

No body is required to perform the request.

Successful Response:

{
  "status": "success",
  "message": "Listener retrieved successfully",
  "data": {
    "id": "f8d7e9a1-c4b6-4a8c-9e2d-3f5c7b9e8a1d",
    "kind": "http",
    "status": "running",
    "name": "primary-listener",
    "description": "Main HTTP listener",
    "external": false,
    "host": "localhost",
    "port": 8010,
    "heartbeat": 60,
    "config": {},
    "created_at": "2024-09-12T15:30:45Z",
    "updated_at": "2024-09-12T15:30:45Z",
    "started_at": "2024-09-12T15:31:05Z",
    "stopped_at": null
  }
}

Get Listener Statuses

Retrieves the status of all listeners.

Endpoint: GET /api/v1/listeners/statuses

Request Body:

No body is required to perform the request.

Successful Response:

{
  "status": "success",
  "message": "Listeners retrieved successfully",
  "data": {
    "f8d7e9a1-c4b6-4a8c-9e2d-3f5c7b9e8a1d": "running",
    "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6": "ready"
  }
}

Start Listener

Start a specific listener.

Endpoint: POST /api/v1/listeners/{listener_id}/start

Request Body:

No body is required to perform the request.

Successful Response:

{
  "status": "success",
  "message": "Successfully started listener with ID: f8d7e9a1-c4b6-4a8c-9e2d-3f5c7b9e8a1d",
  "data": null
}

Stop Listener

Stop a specific listener.

Endpoint: POST /api/v1/listeners/{listener_id}/stop

Request Body:

No body is required to perform the request.

Successful Response:

{
  "status": "success",
  "message": "Successfully stopped listener with ID: f8d7e9a1-c4b6-4a8c-9e2d-3f5c7b9e8a1d",
  "data": null
}

Terminate Listener

Terminate and remove a specific listener.

Endpoint: DELETE /api/v1/listeners/{listener_id}

Request Body:

No body is required to perform the request.

Successful Response:

{
  "status": "success",
  "message": "Listener deleted successfully",
  "data": null
}

Update Listener

Update a listener's configuration.

Endpoint: PUT /api/v1/listeners/

Request Body:

{
  "id": "f8d7e9a1-c4b6-4a8c-9e2d-3f5c7b9e8a1d",
  "name": "primary-listener",
  "description": "Updated HTTP listener description",
  "config": {
    "read_timeout": 30,
    "write_timeout": 30
  }
}

Successful Response:

{
  "status": "success",
  "message": "Successfully updated listener f8d7e9a1-c4b6-4a8c-9e2d-3f5c7b9e8a1d",
  "data": null
}

External Listener Endpoints

External listener endpoints are meant for externally deployed listeners to register and integrate themselves with the teamserver

Register External Listener

Registers an external listener with the teamserver.

Endpoint: POST /external/register

Request Body:

Successful Response:

W.I.P.