Skip to content

Execution Context (execConf)

This document explains the execution context for plugin commands. Every command requires a JSON object with at least a template and a configuration. Some commands also need an extra execConf object to specify how they are executed. The same object can optionally request a specific ExecUnit format with execUnitType. There are three execution modes:

The examples below use the ExecUnit-capable portscan plugin command and assume a Windows agent. Native commands, such as cmd and powershell, always run in the agent process and do not use execConf.

1. Same Process (Default)

Commands run in the agent's current process. Process-target settings are not used, but execUnitType may select a compatible in-process format.

Parameter:

  • execType: "SELF"
  • execUnitType: (Optional) Requested ExecUnit format

Example: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "template": "portscan",
  "configuration": {
    "ips": "10.0.0.1",
    "ports": "443"
  },
  "execConf": {
    "execType": "SELF",
    "execUnitType": "SHELLCODE_NATIVE"
  }
}

2. Spawn a New Process

Execute the command in a new process. The executable is optional; additional options let you control process suspension or run as a different user.

Parameters:

  • execType: "NEW"
  • executable: Executable to run (default: "svchost.exe")
  • suspended: Whether the new process starts with its main thread suspended (default: true)
  • username: (Optional) Username for the new process; must be supplied with password
  • password: (Optional) Password for the new process; must be supplied with username
  • ppid: (Optional) Spoofed parent process ID (default: 0)
  • execUnitType: (Optional) Requested ExecUnit format

Example (default spawn): 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "template": "portscan",
  "configuration": {
    "ips": "10.0.0.1",
    "ports": "443"
  },
  "execConf": {
    "execType": "NEW",
    "suspended": true,
    "execUnitType": "SHELLCODE_NATIVE"
  }
}

Example (spawn as a different user): 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "template": "portscan",
  "configuration": {
    "ips": "10.0.0.1",
    "ports": "443"
  },
  "execConf": {
    "execType": "NEW",
    "executable": "C:\\Windows\\System32\\notepad.exe",
    "suspended": false,
    "username": "bob",
    "password": "bob123"
  }
}

3. Inject into an Existing Process

Run the command by injecting the ExecUnit into an already running process. You only need to provide the process ID.

Parameters:

  • execType: "EXISTING"
  • pid: Process ID where the command will run
  • execUnitType: (Optional) Requested ExecUnit format

Example: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "template": "portscan",
  "configuration": {
    "ips": "10.0.0.1",
    "ports": "443"
  },
  "execConf": {
    "execType": "EXISTING",
    "pid": 1234,
    "execUnitType": "SHELLCODE_NATIVE"
  }
}

ExecUnit Format Selection

Accepted execUnitType values are SHELLCODE_NATIVE, DOTNET_EXE, DOTNET_DLL, and NATIVE_LIB. If omitted, the C2 selects the first compatible format from the command's supported formats and the agent's advertised preferences.