Command ExecUnits
A command ExecUnit implements a task on the agent side and reports its output and outcome to the agent core. This page explains its responsibilities, including commands packaged with listener plugins.
Responsibilities
The command plugin on Command and Control (C2) prepares task-specific input and interprets the resulting data. The command ExecUnit performs the task in its supported environment. The agent core tracks the invocation, handles its local communication, and retains results for delivery through a listener.
The ExecUnit's binary format does not change this role. Managed and native implementations may provide the same command while differing in platform support, dependencies, and detailed behavior. A command built directly into the core is a native command; it is not a separately loaded ExecUnit. See Concepts and Lifecycle.
Listener-Owned Commands
Some listener plugins include command ExecUnits as well as listener ExecUnits. The relay listener families are examples: their packaged commands support listener-related work, but participate in the command lifecycle and use the command protocol.
Classify a component by its responsibility and protocol, rather than by the plugin directory that contains it. Listener-owned commands have their own platform and artifact support; the listener's available formats do not automatically apply to its commands.
Lifecycle
Three separate ideas matter when you describe a command's lifetime:
| Idea | Meaning |
|---|---|
| Task lifetime | The period during which the command performs its work. |
| Output availability | Whether output is retained until completion or can be made available while work continues. |
| Outcome | The command's final success or failure state. |
An ongoing-output command is not necessarily an indefinitely running command. For example, reading a file is finite work but can produce output incrementally. Conversely, a command that provides a continuing service may have no predetermined completion time.
Result data and error data do not replace the outcome. A task can produce useful partial results before failing, or finish successfully without substantial output. Treat peer disconnection or worker termination as separate observations; neither is evidence of successful completion.
Stop support also depends on the command implementation. Some commands support cooperative stopping, while others cannot finish immediately when asked to stop. The current host also has forced-stop paths, so do not assume that cancellation always runs application cleanup. See Limitations and Diagnostics.
Communication responsibilities
The pipe-based commands covered here communicate locally with the agent core. The core, together with a listener, handles the separate path to C2. Sharing the same local pipe facility does not require a command to use the listener's external transport format. The host also has a no-IPC strategy, which provides no such command back-channel.
Command-specific configuration and results belong to the command's contract. Some commands use structured data; others use text or opaque bytes. Their representation cannot be inferred from the ExecUnit's binary extension or programming language.
Output may be aggregated or retained in separate blocks according to the supported command behavior. Keep logical command results distinct from operating-system read and write boundaries: a read operation is not necessarily one application result. Local Communication explains that distinction.
The Agent and Command ExecUnits protocol owns the detailed definitions for command output, outcome, configuration changes, and control messages. Use the Type-Length-Value (TLV) reference for the shared encoding. This page does not redefine either contract.
Examples
These examples illustrate responsibility and lifetime, without depending on a particular artifact format.
| Example | What it illustrates |
|---|---|
| Creating an application-owned directory | A finite task can report its outcome without a large result body. Filesystem failure is a task failure, distinct from a local communication failure. |
| Reading an application-owned text file | Finite work can produce multiple result portions before completion. Incremental output does not make the task indefinite. |
| A listener-owned command | Packaging with a listener does not change command-result ownership or make the component a listener ExecUnit. |
Limitations
Support is specific to the command, operating system, architecture, artifact, and host. Shared names across platforms do not guarantee identical behavior, cancellation support, or result chunking. The compatibility tables describe the broad platform boundaries; individual command documentation describes task-specific behavior.
Working command communication also does not prove end-to-end result delivery. The core's result handling and the listener's external transport are additional responsibilities. Diagnose them separately, using Limitations and Diagnostics, and read Listener ExecUnits for the corresponding transport role.