Skip to content

Agent and Listener ExecUnits

This page describes the existing Type-Length-Value (TLV) message reference for communication between the agent core and listener ExecUnits. The reference retains the historical term "shellcode" in its message descriptions.

See Listener ExecUnits for the listener's role, and TLV for the shared encoding. C2 below means Command and Control.

Packet framing

In both directions data is sent in packets with format ("actual data" is one of the TLV's): 

1
< 4 byte little endian length >< actual data >

2. Agent to shellcode command & result

Requests that are sent from agent to the shellcode and their responses

2.1 Send shellcode new configuration

Listener configuration changing request & response

2.1.1 Request

  • ID: 0x20
    TYPE = PARENT
    VALUE: Outer ID 0x20 shows that the structure contains listener reconfiguration information or response
    • ID: 0x1
      TYPE: BYTE
      required: YES
      VALUE: isRequest (1 == request, 0 == response), so should be 0x1
    • ID: 0x2
      TYPE: INT32
      required: YES
      VALUE: Unique ID generated by the agent to distinguish responses to different requests
    • ID: 0x4
      TYPE: BLOB
      required: YES
      VALUE: Configuration to be relayed to the shellcode

2.1.2 Response

  • ID: 0x20
    TYPE: PARENT
    VALUE: Outer ID 0x20 shows that the structure contains listener reconfiguration information or response
    • ID: 0x1
      TYPE: BYTE
      required: YES
      VALUE: #isRequest (1 == request, 0 == response), so should be 0x0
    • ID: 0x2
      TYPE: INT32
      required: YES
      VALUE: Unique ID generated by the agent to distinguish responses to different requests
    • ID: 0x3
      TYPE: BYTE
      required: YES
      VALUE: isSuccess (1 == yes, 0 == no)
    • ID: 0x4
      TYPE: BLOB
      VALUE: Error msg

3. Shellcode to agent command & result

Requests that are sent from shellcode to agent

3.1 Get metadata

Shellcode asks for metadata blob

The shellcode requests metadata bytes from the agent, which are received in encrypted form and subsequently decrypted by the server.

3.1.1 Request

  • ID: 0x21
    TYPE: PARENT
    VALUE: Outer ID 0x21 shows that the structure contains metadata request or response
    • ID: 0x1
      TYPE: BYTE
      required: YES
      VALUE: isRequest (1 == request, 0 == response), so should be 0x1
    • ID: 0x2
      TYPE: INT32
      required: YES
      VALUE: Unique ID generated by the shellcode to distinguish responses to different requests

3.1.2 Response

  • ID: 0x21
    TYPE: PARENT
    VALUE: Outer ID 0x21 shows that the structure contains metadata request or response
    • ID: 0x1
      TYPE: BYTE
      required: YES
      VALUE: isRequest (1 == request, 0 == response), so should be 0x0
    • ID: 0x2
      TYPE: INT32
      required: YES
      VALUE: Unique ID generated by the shellcode to distinguish responses to different requests
    • ID: 0x4
      TYPE: BLOB
      VALUE: Metadata binary

3.2 Get next message to send to C2

Shellcode asks for command blob

The shellcode requests upstream data bytes from the agent. These bytes are received in encrypted form and are decrypted by the server for further processing.

3.2.1 Request

  • ID: 0x22
    TYPE: PARENT
    VALUE: Outer ID 0x22 shows that the structure contains command asking request or response
    • ID: 0x1
      TYPE: BYTE
      required: YES
      VALUE: isRequest (1 == request, 0 == response), so should be 1
    • ID: 0x2
      TYPE: INT32
      required: YES
      VALUE: Unique ID generated by the shellcode to distinguish responses to different requests

3.2.2 Response

  • ID: 0x22
    TYPE: PARENT
    VALUE: Outer ID 0x22 shows that the structure contains command asking request or response
    • ID: 0x1
      TYPE: BYTE
      required: YES
      VALUE: isRequest (1 == request, 0 == response), so should be 0
    • ID: 0x2
      TYPE: INT32
      required: YES
      VALUE: Unique ID generated by the shellcode to distinguish responses to different requests
    • ID: 0x4
      TYPE: BLOB
      VALUE: Command binary

3.3 Give agent core a new message received from C2

Shellcode sends received message to agent core

3.3.1 Request

  • ID: 0x23
    TYPE: BLOB
    VALUE: Outer ID 0x23 shows that the structure contains command binary

3.3.2 Response

NO RESPONSE