C2 Introduction
Command and control, herein C2, consists of a C2 server and C2 agents. MiNIFi agents must adhere to the C2 protocols to have successful communications. C2 communications occur over a variety of protocols. Currently an HTTP/HTTPS RESTFul paradigm exists to support C2 capabilities to MiNiFi C2 agents. In the future additional protocols may become available for use. Note that when the phrasing "C2 designator" is used, this implies the C2 server, server, or agent that is designated as a responder to the C2 agent(s). All protocols must support the following operations:
| Operation Name | Description |
|---|
ACKNOWLEDGE | Operation used by MiNiFi C2 agents to acknowledge the receipt and execution of a C2 server requested operation |
CLEAR | Clears flow connection queues or repositories on the C2 agent |
DESCRIBE | Currently Unused |
HEARTBEAT | Heartbeat provides status and operational capabilities to C2 server(s) |
UPDATE | Updates components of the C2 agent or the flow configuration. |
RESTART | Restarts C2 agents |
START | Starts components within the C2 agents |
| STOP | Stops components within the C2 agent |
| TRANSFER | Transfers an object between the C2 agent and C2 designator. |
C2 Requirements
The requirements are an evolving list that have grown organically from an implementation
| C2 Requirement | Justification and Purpose |
|---|
| C2 agents shall report C2 status at regular intervals through a heartbeat message | Agents must employ heartbeat messages that follow an interval that is favorable to the agent ( power ) |
| C2 agents shall report the flow version within the heartbeat message at regular intervals | Agents must report flow version to the C2 server |
| C2 agents shall report queue status within the heartbeat message at regular intervals | Agents must report queue status to the C2 server at regular intervals |
| C2 agents shall execute acknowledge commands sent via a heartbeat response | Agents must execute and acknowledge commands from the C2 server |
| C2 agents shall apply requested changes and inform the C2 server of success or failure | Agents must apply and acknowledge updates from the C2 server, responding with a success or failure |
| C2 agents shall implement clear, update, restart, start, stop, and transfer commands | Agents must implement the prescribed commands. |
C2 Messages
Heartbeats
Primary communications are carried over a C2 heartbeat. The heartbeat contains operational information about the C2 agent and can occur a configurable frequency. The heartbeat provides status information to the C2 server. The response from the heartbeat contains requested operations from the C2 server. These operations are then acknowledged if/when they are completed. This means that the heartbeat is the only operation initiated by the C2 agent and the C2 server responds directly to these heartbeats.
Protocols
HTTP/S Protocol
The HTTP/S protocol supports a url for heartbeating and acknowledging operations. These endpoints support the JSON structures defined below. C2 agents must send a heartbeat, defined above, to update the C2 server of its status and to receive operations. The frequency of these calls are up to the C2 agent to define.
Heartbeat structure
Heartbeats consist of a POST of the following Schema to the C2 heartbeat url. Metrics is a configurable list of metrics that can be returned, so the entirety of that object is optional.
Update: current work uses a flow identifier to help identify the currently running flow within DeviceInfo.
| Key |
Value |
| Components |
| Key |
Value |
| FlowController |
enabled |
| ProcessorName |
enabled/disabled |
|
| DeviceInfo |
| Key |
Value |
| NetworkInfo |
| Key |
Value |
| Deviceid |
string |
| Flowid |
string |
| Hostname |
string |
| Ip |
string |
|
| SystemInformation |
| Key |
Value |
| Machinearch |
string |
| Physicalmem |
string |
| Vcores |
string |
|
|
| Metrics |
| Key |
Value |
| ProcessMetrics |
| Key |
Value |
| CpuMetrics |
|
| MemoryMetrics |
|
|
| QueueMetrics |
| Key |
Value |
| Connection |
| Key |
Value |
| Datasize |
string |
| Datasizemax |
string |
| Queued |
string |
| Queuedmax |
string |
|
|
| RepositoryMetrics |
| Key |
Value |
| Flowfile |
| Key |
Value |
| Full |
1/0 |
| Running |
1/0 |
| Size |
string |
|
| Provenance |
| Key |
Value |
| Full |
1/0 |
| Running |
1/0 |
| Size |
string |
|
|
|
| Operation |
heartbeat |
| State |
| Key |
Value |
| Running |
true/false |
| Uptime |
string |
|
| Key |
Value |
| Operation |
heartbeat |
| Requested_operations |
| Name |
Operationid |
Operation |
Content |
| string |
string |
string |
|
|
Operation schemas
The following are the schema definitions for each operation that is contained within the requested operations of a heartbeat response. It is expected that C2 agents adhere to this structure
Clear
The clear operation uses name of connection or repositories to clear either the connections or the repositories. In the case of a connection the content contains the operation arguments, in which the value defines the connection name to clear.
| Key |
Value |
| Operation |
heartbeat |
| Requested_operations |
| Name |
Operationid |
Operation |
Content |
| connection |
string |
clear |
| Unique_map_key |
| connection_name |
|
|
| Key |
Value |
| Operation |
heartbeat |
| Requested_operations |
| Name |
Operationid |
Operation |
| repositories |
string |
clear |
|
Update
Update allows the C2 server to update either the c2 agent or provide a URI from which we download the new flow configuration through a GET request.
| Key |
Value |
| Operation |
heartbeat |
| Requested_operations |
| Name |
Operationid |
Operation |
Content |
| configuration |
string |
update |
| Location |
| HTTP or HTTPS URL |
|
|
The following activity diagram depicts the flow of updating an agent from failure to success.
| Key |
Value |
| Operation |
heartbeat |
| Requested_operations |
| Name |
Operationid |
Operation |
Content |
| c2 |
string |
update |
|
|
Start
Start starts a previously stopped command. If a start is called on a component that is already started, nothing should occur other than an acknowledgement. Name defines the component to start.
| Key |
Value |
| Operation |
heartbeat |
| Requested_operations |
| Name |
Operationid |
Operation |
| component name |
string |
start |
|
Stop
Stop stops a component that is started. Components can be the FlowController, processors, or RPGs
| Key |
Value |
| Operation |
heartbeat |
| Requested_operations |
| Name |
Operationid |
Operation |
| component name |
string |
stop |
|
Transfer
Transfer will download an object from the C2 designator ( server or other location ). The location URI will be provided by the update JSON. This transfer will not be a JSON
response but will instead be the binary object. The hash of the object will be the acknowledgement ID for the transfer.
| Key |
Value |
| Operation |
acknowledge |
| Operationid |
hash of object |
Restart
Attempts to restart the component defined within name
| Key |
Value |
| Operation |
heartbeat |
| Requested_operations |
| Name |
Operationid |
Operation |
| component name |
string |
restart |
|
Acknowledgements.
Acknowledgements occur through a separate URL. This URL will receive a POST that contains the following payload, which acknowledges that the operation ID was received and executed.
| Key |
Value |
| Operation |
acknowledge |
| Operationid |
string |
MQTT Protocol
Discuss implementing the MQTT protocol
