Developer Guide

Agent Development

Quick Code Reference

• cmd/agent - Configures and runs an agent
• pkg/agent - Provides agent functionality, could be used to implement a custom agent with minimal effort
• pkg/agent/transport Package - Defines message format and includes protocol buffer definitions for Agent & Server communication
  • Paragon's built-in transports are located in subdirectories of this package
• pkg/agent/c2 - Defines a C2 that interfaces with the Paragon Teamserver to claim tasks and report execution results

Execution Flow

The above diagram illustrates the control flow for the Agent's execution. It begins by collecting metadata about the system it's running on, which will later be included in AgentMessages reported to the server. Then, a loop is started that will send an empty AgentMessage to the server on an interval (based on the configured MaxIdleTime). Each agent is configured with a transport that implements transport.AgentMessageWriter, which is used to send messages to the server. Most implementations will use a transport.AgentMessageMultiWriter to enable failover between multiple transports. AgentMessages are dropped if all transport attempts fail. In cases where a transport receives Tasks from the server (i.e. the http agent transport), it should write the received ServerMessage to the provided transport.ServerMessageWriter. The Agent type itself implements this interface, utilizing the configured transport.TaskExecutor to execute tasks. TaskResults are written to the agent's transport.AgentMessageWriter, which reports these results to the server.

Creating a Transport

Paragon's built-in transport mechanisms are included as subdirectories of the transport package.

1. Define an AgentTransport type (http example)

• Required to implement transport.AgentMessageWriter to send AgentMessages to the server.
• Embed a transport.Transport in your AgentTransport struct to use for encoding & decoding messages.
• Any response from the server should be written to the provided transport.ServerMessageWriter.
• All required configuration & dependencies should be included as fields on your defined AgentTransport struct.

2. Define a ServerTransport type (http example)

• Embed a transport.Transport in your ServerTransport struct to use for encoding & decoding messages.
• Embed a transport.AgentMessageWriter (implemented by the server to handle incoming AgentMessages) Any received messages should be written to this dependency.

Language Development

Overview

Renegade is a python-like DSL based on Google Starlark. For language reference, please refer to the starlark docs. Renegade scripts are not executed in any special environment, instead these scripts are simply parsed and execute golang code. This enables us to expose functionality written in golang to Renegade scripts, providing a simple DSL for operators to control program execution. Renegade scripts are however limited to only be able to execute specially defined golang methods that are provided to it. We provide an abstraction in the pkg/script package to simplify method definition and enable developers to quickly add functionality.

running the teamserver

PG_DISABLE_CORS=1 go run -tags=dev ./cmd/teamserver

running the frontend

run the teamserver and

cd www && npm i && npm start