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.

Request:

1
2
3
4
5
6
7
8
9
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}
}

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 a list of all created listeners.

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

Update Listener Name

Change the name of an existing listener.

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

{
  "name": "NEW_NAME"
}

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}