Skip to content

API: Listeners

This section covers listener management via the API.

Get Listener Plugins

Retrieve a list of available listener plugins.

1
2
GET /api/v1/plugins/listeners HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Create a New Listener

Use this endpoint to create a listener. You must provide the plugin ID (from the plugins list), a name, and configuration settings. By default, the listener starts immediately after creation.

JSON request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
POST /api/v1/listeners HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "plugin": "ID_OF_THE_LISTENER",
  "name": "YOUR_LISTENER_NAME",
  "configuration": {LISTENER_CONFIGURATION},
  "configurationFiles": [],
  "startAfterCreation": true
}

Multipart request (when the listener configuration uses files):

1
2
3
4
5
6
POST /api/v1/listeners HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: multipart/form-data

requestBody: {"plugin": "ID_OF_THE_LISTENER", "name": "YOUR_LISTENER_NAME", "configuration": {LISTENER_CONFIGURATION}, "configurationFiles": [], "startAfterCreation": true}
{FILE_FIELD_NAME}: <binary file content>

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
POST /api/v1/listeners HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "plugin": "shelldot.listener.agent-reverse-tcp",
  "name": "my-tcp-reverse-listener",
  "configuration": {
    "hosts": [
      "localhost",
      "192.168.32.135"
    ],
    "port": 5555,
    "handshakeBytes": "QUFBQQ==",
    "startTime": "2025-02-14T13:00:00Z"
  }
}

List All Listeners

Get all created listeners.

1
2
GET /api/v1/listeners HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Response is a JSON object keyed by listener ID:

1
2
3
4
{
  "1": { "id": 1, "name": "...", "plugin": "...", "status": "RUNNING", "configuration": { ... } },
  "2": { "id": 2, "name": "...", "plugin": "...", "status": "STOPPED", "configuration": { ... } }
}

Get Listener Details

Fetch full information for a specific listener.

1
2
GET /api/v1/listeners/{LISTENER_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Update a Listener

Change the name or configuration of an existing listener. Updating the configuration triggers immediate listener reconfiguration.

1
2
3
4
5
6
7
8
9
PATCH /api/v1/listeners/{LISTENER_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "name": "NEW_NAME",
  "configuration": {LISTENER_CONFIGURATION},
  "configurationFiles": []
}

Use the multipart variant when the new configuration requires uploaded files:

1
2
3
4
5
6
PATCH /api/v1/listeners/{LISTENER_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: multipart/form-data

requestBody: {"name": "NEW_NAME", "configuration": {LISTENER_CONFIGURATION}, "configurationFiles": []}
{FILE_FIELD_NAME}: <binary file content>

Start a Listener

Activate a listener.

1
2
PUT /api/v1/listeners/{LISTENER_ID}/start HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Stop a Listener

Deactivate a listener.

1
2
PUT /api/v1/listeners/{LISTENER_ID}/stop HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Delete a Listener

Remove a listener.

1
2
DELETE /api/v1/listeners/{LISTENER_ID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}