# The TCP handler

The TCP handler performs manual serialisation and de-serialisation of request and response objects. The key differences between it and the HTTP(S) handlers are:

* TLS is enabled by default. To verify the server certificate, embed the certificate authority's PEM-encoded certificate into your agent's configuration for manual validation.
* TCP sessions don't timeout like HTTP sessions, because they don't use JWTs.
* Data is sent in a raw byte structure that needs to be parsed manually.

This is not a tutorial on serialisation. For a technical guide on how to develop your implant to interact with the TCP handler, you may want to read [this blog post](https://medium.com/@pygrum/malware-development-developing-a-custom-network-protocol-d6fa214fa10f) made by the developer themselves.

## Important

* Packets work using 'prepended size' - the size of the data sent over the connection ***must*** be prepended to the data itself.
* All <mark style="color:purple;">sizes</mark> and <mark style="color:purple;">numeric values</mark> use **big-endian notation** (i.e. network byte order) and are of type **`uint32`** - unsigned, 4-byte integer. This includes the [**opcode**](https://monarch.gitbook.io/monarch/c2-server/talking-to-implants#c2-request).
* Response [status](https://monarch.gitbook.io/monarch/c2-server/talking-to-implants#implant-response) and [dest](https://monarch.gitbook.io/monarch/c2-server/talking-to-implants#implant-response)(ination) are each 1 byte long, and either 1 or 0.
* All fields with non-fixed lengths ***must*** have their <mark style="color:purple;">sizes prepended</mark> to the field data itself as part of the packet. Fixed-length fields are as follows:\
  \
  &#x20;   1\. Agent ID (length as bytes: `8`, length as string: `16`)\
  &#x20;   2\. Request ID (length as string: `36`)\
  \
  The diagrams below provide neat visualisations for object structures.<br>
* TEST THOROUGHLY! Use the `install local` feature for quick and convenient integration testing.

[Empress](https://github.com/pygrum/empress), a POC agent for Monarch, includes several functions related to parsing and serialising valid request and response structures. It is recommended to draw from the examples contained in its source code.

## Object structures

The next sections provide diagrams for each structure that an implant using the TCP handler will have to work with. Pay attention to the offsets in the diagrams. The invalid hex numbers (e.g. `0xG` ) represent unknown offsets.

### Registration

* Usage: serialise

```json
{
	"agent_id": "string",
	"os": "string",
	"arch": "string",
	"username": "string",
	"hostname": "string",
	"uid": "string",
	"gid": "string",
	"pid": "string",
	"home_dir": "string",
}
```

Here is our registration object, for reference.\
To register an implant, we would send a packet with the same structure as the one shown below. Notice that **each field is dependent on its order above**.

<figure><img src="https://3353642664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdkbiggPMgoB7gNihfYbJ%2Fuploads%2FutGY8yTm9RJuj4qeu6nb%2FUntitled%20drawing.jpg?alt=media&#x26;token=405de858-f54d-43b2-a91a-c1342a9b30ca" alt="" width="563"><figcaption></figcaption></figure>

### Operator Requests

* Usage: parse / unserialise

The following diagram shows how requests from the C2 to the implant are structured.

<figure><img src="https://3353642664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdkbiggPMgoB7gNihfYbJ%2Fuploads%2FjytkjlEi9wkIKQbFFxPo%2Freq%20packet.jpg?alt=media&#x26;token=77a4f7e5-cce9-4149-845d-178a4b7ee709" alt="" width="563"><figcaption></figcaption></figure>

### Implant responses

* Usage: serialise

The following diagram shows how a response to an operator request should be structured.

<figure><img src="https://3353642664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdkbiggPMgoB7gNihfYbJ%2Fuploads%2Fz8WWtrc3hmxpJ1erzoPX%2Fresp%20packet.jpg?alt=media&#x26;token=450aee58-b988-4ba3-a50c-402107ff6078" alt="" width="563"><figcaption></figcaption></figure>

Despite the complexity, once a set of TCP-compliant routines have been implemented once, you won't need to implement them again!