Skip to content

Reverse HTTP Listener for Built Agents

The HTTP listener opens an HTTP/HTTPS server on a specified port and manages data traffic with agents.

Plugin ID: shelldot.listener.agent-reverse-http

HTTP Listener Configuration

The table below documents all available configuration parameters in a logical order:

Attribute Explanation
port Port number where the generated payload calls home. If bindToPort is set to null, it will also be the port that listener runs
bindToPort Port number where the listener actually runs. Default is "null", in that case the "port" variable is used
https Protocol flag (0 = HTTP, 1 = HTTPS).
startTime Optional UTC start time (e.g., "2023-04-10T11:02:09Z").
getUri URI used by the agent for GET requests when idle.
postUri URI for sending data via POST (also receives data).
stagedUri URI requested for generating agent executable/dll/service/shellcode.
stagedUriPayloadId What GET parameter should containg id of the payload to download via stagedUri
filename A template string visible in the HTTP response when payload is served via the stagedUri and stagedUriPayloadId parameters ( used primarily in the launchers ). See the examples on the bottom of the page.
fileStorageUri Base URI for retrieving files from file storage.
metadataCookieName Cookie name used to hold metadata.
metadataPrefix Prefix appended to metadata.
metadataSuffix Suffix appended to metadata.
instantResponses Boolean indicating if the agent sends data immediately or waits for the sleep timeout (for OPSEC).
sleep Global Base sleep time (seconds) between requests. Can be overridden by httpCallbacks[].sleep
sleepRandom Global Variation (seconds) in the sleep time. Can be overridden by httpCallbacks[].sleepRandom
headers[ ] Additional HTTP headers (array of objects with "name" and "value").
  â†³ name Name of the header.
  â†³ value Value of the header.
httpCallbacks[ ] Array of callback configuration objects.
↳ hosts[ ] Array of IP addresses or hostnames the agent can use to connect.
↳ hostsRotation: Rotation rules for host selection.
    â†³ type Rotation method (FAILOVER, ROTATE, RANDOM).
    â†³ counter Numeric value indicating when to rotate hosts.
    â†³ unit Unit for the counter (TRIES, SECONDS, MINUTES, HOURS).
↳ sleep Base sleep time (seconds) between requests.
↳ sleepRandom Variation (seconds) in the sleep time.
↳ hostHeaders[ ] Array of HTTP host header values used when connecting.
↳ hostHeaderRotation: Rotation rules for host headers.
    â†³ type Rotation method for host headers (FAILOVER, ROTATE, RANDOM).
    â†³ counter Numeric value for header change frequency.
    â†³ unit Unit for the header counter (TRIES, SECONDS, MINUTES, HOURS).

Hosts string array

If inner hosts string array contains more than 1 hostname/IP, then it's same as host object array to contain same number of objects, each with only one value in host string array bus rest configuration same. This is just so users would be able to keep configuration smaller.

These two configurations are equal: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
  "port": 8089,
  "httpCallbacks": [
    {
      "hosts": [
        "localhost",
        "192.168.1.100"
      ],
      "hostsRotation": {
        "type": "ROTATE",
        "counter": 7,
        "unit": "TRIES"
      },
      "sleep": 3000,
      "sleepRandom": 1000,
      "hostHeaders": [
        "alpha",
        "bravo",
        "charlie"
      ],
      "hostHeaderRotation": {
        "type": "FAILOVER",
        "counter": 2,
        "unit": "TRIES"
      }
    }
  ],
  "getUri": "/GIVEITTOME",
  "postUri": "/NOWIGIVETOYOU",
  "stagedUri": "/candy",
  "fileStorageUri": "/files/",
  "metadataCookieName": "PHPSESSID",
  "metadataPrefix": "ABC",
  "metadataSuffix": "XYZ",
  "https": 0,
  "startTime": "2023-04-10T11:02:09Z",
  "headers": [
      { 
        "name": "Extra-Header-Name",
        "value": "Extra-Header-Value"
      }
    ],
  "sleep": 1500
}
vs 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
  "port": 8089,
  "httpCallbacks": [
    {
      "hosts": [
        "localhost"
      ],
      "hostsRotation": {
        "type": "ROTATE",
        "counter": 7,
        "unit": "TRIES"
      },
      "sleep": 3000,
      "sleepRandom": 1000,
      "hostHeaders": [
        "alpha",
        "bravo",
        "charlie"
      ],
      "hostHeaderRotation": {
        "type": "FAILOVER",
        "counter": 2,
        "unit": "TRIES"
      }
    },
    {
      "hosts": [
        "192.168.1.100"
      ],
      "hostsRotation": {
        "type": "ROTATE",
        "counter": 7,
        "unit": "TRIES"
      },
      "sleep": 3000,
      "sleepRandom": 1000,
      "hostHeaders": [
        "alpha",
        "bravo",
        "charlie"
      ],
      "hostHeaderRotation": {
        "type": "FAILOVER",
        "counter": 2,
        "unit": "TRIES"
      }
    }
  ],
  "getUri": "/GIVEITTOME",
  "postUri": "/NOWIGIVETOYOU",
  "stagedUri": "/candy",
  "fileStorageUri": "/files/",
  "metadataCookieName": "PHPSESSID",
  "metadataPrefix": "ABC",
  "metadataSuffix": "XYZ",
  "https": 0,
  "startTime": "2023-04-10T11:02:09Z",
  "headers": [
      { 
        "name": "Extra-Header-Name",
        "value": "Extra-Header-Value"
      }
    ],
  "sleep": 1500
}

Examples

Example 1: Basic Configuration with Host Rotation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
  "port": 8089,
  "https": false,
  "httpCallbacks": [
    {
      "hosts": [
        "localhost",
        "192.168.1.100"
      ],
      "hostsRotation": {
        "type": "ROTATE",
        "counter": 7,
        "unit": "TRIES"
      },
      "sleep": 3000,
      "sleepRandom": 1000,
      "hostHeaders": [
        "alpha",
        "bravo",
        "charlie"
      ],
      "hostHeaderRotation": {
        "type": "FAILOVER",
        "counter": 2,
        "unit": "TRIES"
      }
    }
  ],
  "getUri": "/GIVEITTOME",
  "postUri": "/NOWIGIVETOYOU",
  "stagedUri": "/candy",
  "fileStorageUri": "/files/",
  "metadataCookieName": "PHPSESSID",
  "metadataPrefix": "ABC",
  "metadataSuffix": "XYZ",
  "startTime": "2023-04-10T11:02:09Z",
  "headers": [
    {
      "name": "Extra-Header-Name",
      "value": "Extra-Header-Value"
    }
  ],
  "instantResponses": false,
  "sleep": 1500
}

Example 2: Complex Rotation Rules

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
{
  "port": 8089,
  "https": false,
  "httpCallbacks": [
    {
      "hosts": ["localhost"],
      "hostsRotation": {
        "type": "FAILOVER",
        "counter": 5,
        "unit": "MINUTES"
      },
      "sleep": 10000,
      "sleepRandom": 4000,
      "hostHeaders": [
        "alpha",
        "bravo",
        "charlie"
      ],
      "hostHeaderRotation": {
        "type": "ROTATE",
        "counter": 30,
        "unit": "SECONDS"
      }
    },
    {
      "hosts": ["192.168.1.100"],
      "hostsRotation": {
        "type": "FAILOVER",
        "counter": 3,
        "unit": "TRIES"
      },
      "sleep": 8000,
      "sleepRandom": 6000,
      "hostHeaders": [
        "delta",
        "echo"
      ],
      "hostHeaderRotation": {
        "type": "RANDOM",
        "counter": 2,
        "unit": "TRIES"
      }
    }
  ],
  "getUri": "/GIVEITTOME",
  "postUri": "/NOWIGIVETOYOU",
  "stagedUri": "/candy",
  "fileStorageUri": "/files/",
  "metadataCookieName": "PHPSESSID",
  "metadataPrefix": "ABC",
  "metadataSuffix": "XYZ",
  "startTime": "2023-04-10T11:02:09Z",
  "headers": [
    {
      "name": "Extra-Header-Name",
      "value": "Extra-Header-Value"
    }
  ],
  "instantResponses": false,
  "sleep": 1500
}

How the rotation works:

  1. Agent starts with connection to IP localhost using host header "alpha"
  2. For the localhost connection:
  3. Host rotation occurs after 5 minutes of failed connections
  4. Host headers rotate every 30 seconds between "alpha", "bravo", and "charlie"
  5. For the 192.168.1.100 connection:
  6. Host rotation occurs after 3 failed connection attempts
  7. Host headers randomly switch between "delta" and "echo" with 50% probability before each request

Note: Host rotation and header rotation operate independently. A successful connection resets the host rotation counter, while header rotation continues according to its own rules.

Available filename template string functions

Template Description
{rand_str_X} Where X is number of characters. Will generate a random case insensitive string with the length of "X" (integer)
{rand_str_X_Y} Where X is the minimum length and Y is the maximum length. Will generate a random case insensitive string with a length between X and Y
{rand_int_X_Y} Where X is the minimum and Y is the maximum. Will generate a random integer between X and Y
{ext} Will return the file extension of the requested payload. eg. .exe or .dll ( note that dot is included in the extension)
{payload_id} Will return the payload id of the requested payload

Example Usage: 

1
2
3
...,
"filename": "{rand_str_10}-Little-{rand_str_9_20}-Agent-{rand_int_9_2000000000}-With-{payload_id}-{ext}",
...
Will change the filename attribute of the stagedUri to return: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
> GET /payload?payloadId=4 HTTP/1.1
> Host: skippy.and.joe
> User-Agent: curl/1337.81.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Content-Type: application/octet-stream
< Content-Disposition: attachment; filename="A9JfMQRwq8-Little-guhRgWYRqV-Agent-391964415-With-4-.exe"
< Content-Length: 770560