Agent Message Format

This page describes how an agent message is formatted

All messages go to the /api/v1.4/agent_message endpoint. These messages can be:

• POST request

  • message content in body

  • message content in FIRST header value

  • message content in FIRST cookie value

• GET request

  • message content in FIRST header value

  • message content in FIRST cookie value

  • message content in FIRST query parameter

All agent messages have the same general structure, but it's the message inside the structure that varies.

Each message has the following general format:

base64(
		UUID + EncBlob( //the following is all encrypted
			JSON({
				"action": "", //indicating what the message is - required
				"...": ... // JSON data relating to the action - required
				
				//this piece is optional and just for p2p mesh forwarding
				"delegates": [
				{"UUID1": agentMessage},
				{"UUID2": agentMessage}
				]
			})
		)
	)

There are a couple of components to note here in what's called an agentMessage:

• UUID - This UUID varies based on the phase of the agent (initial checkin, staging, fully staged). This is always a 36 character long of the format b50a5fe8-099d-4611-a2ac-96d93e6ec77b .

• EncKey - This section is encrypted, typically by an AES256 key, but when agents are staging, this could be encrypted with RSA keys or as part of a Diffie-Hellman key exchange.

• JSON - This is the actual message that's being sent by the agent to Apfell or from Apfell to an agent.

  • action - This specifies what the rest of the message means. This can be one of the following:

    • staging_rsa

    • staging_dh

    • checkin

    • get_tasking

    • post_response

    • upload

    • delegate

  • ... - This section varies based on the action that's being performed. The different variations here can be found in Hooking Features , Initial Checkin, and Agent Responses

  • delegates - This section contains messages from other agents that are being passed along. This is how messages from nested peer-to-peer agents can be forwarded out through and egress callback. If your agent isn't forwarding messages on from others (such as in a p2p mesh or as an egress point), then you don't need this section

• + - when you see something like UUID + EncBlob, that's referring to byte concatenation of the two values. You don't need to do any specific processing or whatnot, just right after the first elements bytes put the second elements bytes