BOF and Extensions

Official extensions: https://github.com/Adaptix-Framework/Extension-Kit

Beacon Object Files

BOF is just a block of position-independent code that receives pointers to some Beacon internal APIs. BOFs are single-file C programs that call Win32 APIs and limited Beacon APIs.

AdaptixC2 expects that your BOFs are single-threaded programs that run for a short period of time. BOFs will block other agent tasks and functionality from executing. BOFs execute inside of your agent. If a BOF crashes, you will lose access. Write your BOFs carefully.

Description of BOF for agents

Beacon BOFs

Extensions

The AdaptixСlient allows you to extend the default functionality by adding new commands to the agent console.

Extensions are managed through the context menu of the extensions table.

The extension file must be in JSON format and have the following structure.

{
  "name": "Test",
  "description": "Test extensions",
  "extensions": [
    {
      "type":"<EXTENTION_TYPE>",
      ...
    },
    {
      "type":"<EXTENTION_TYPE>",
      ...
    }
  ]
}

At the moment there is only one extension type available: "command"

1. command

This type defines a new command. In addition to the required type, agents and exec parameters, this type must contain a description of the command (see here for details). The Adaptix command structure has the following JSON parameters:

• command - сonsole command name;

• message - the message displayed in the console after entering the command;

• description - description of the command;

• example - example of command input;

• args - command arguments.

The args parameter is a json-array of strings. Each string contains information about the parameter according to the following mask:

"Type [or<Argument_name>or] (Default_value) {Argument_description}"

Example:
"STRING <str> (default value) {String value}"

• Type - is a required parameter that must have one of the following values: BOOL, INT, STRING, FILE. If the type is "FILE", then the path to the file will need to be specified in the console. In the received JSON data, the file contents will be encoded in base64.

• Argument_name - is a required parameter that defines the name of the parameter. If Argument_name is specified in brackets <>, then the parameter is mandatory, and if in brackets [], then it is optional. The argument name can be specified as a simple string, or as a flag (starting with - or /) and a simple string. For the BOOL type, the Argument_name is specified by a flag in square brackets [].

• Default_value - is an optional parameter that specifies the default value. To do this, Argument_name must be specified in brackets <>.

• Argument_description - is an optional parameter that describes the parameter for the 'help' menu.

The agents parameter defines the list of agents to whose console the new command will be added.

The exec parameter defines the template for forming the command that will be executed in the console.

The following file defines two new commands: shell and dir.

    {
      "type": "command",
      "agents": ["beacon"],

      "command": "dir",
      "description": "List files in a directory. Supports wildcards (e.g. \"C:\\Windows\\S*\")",
      "message": "BOF implementation: dir",
      "example": "dir C:\\Windows",
      "args" : [
        "STRING </d directory> (.\\)",
        "BOOL </s> (false) {Recursive list}"
      ],
      "exec": "execute bof $EXT_DIR()/dir.$ARCH().o $PACK_BOF(CSTR {directory}, SHORT {/s})"
    },
    {
      "type" : "command",
      "agents": ["beacon"],

      "command": "shell",
      "message": "",
      "description": "Execute command via cmd.exe",
      "example": "shell whoami /all",
      "args": [
        "STRING <cmd>"
      ],
      "exec": "ps run -o C:\\Windows\\System32\\cmd.exe /c {cmd}"
    }

The shell command is a shortcut for the ps run command. The shell command has only one required parameter: cmd. The value of the cmd parameter will simply be substituted into the exec template.

So when you run the command shell whoami, another command will be executed:

# "exec": "ps run -o C:\\Windows\\System32\\cmd.exe /c {cmd}"

ps run -o C:\\Windows\\System32\\cmd.exe /c whoami

CmdChecker

Agent's console

In addition to parameter substitution, the extension has certain macros that will also be replaced in the resulting command. Currently, three macros are defined:

• $EXT_DIR() - returns the directory where the extension file is located.

• $ARCH() - return agent's architecture.

• $RAND(count, chars) - generate count characters from character set chars (alphanumeric, alphabetic, numeric, hex).

• $HASH(hash, count, data) - Calculate hash (md5, sha1) and take first count characters.

• $PACK_BOF(CSTR {directory}, SHORT {/s}) - returns packed data for BOF. Supports the following data types: BYTES, CSTR, WSTR, INT, SHORT.

So when you run the command dir C:\Windows /s, another command will be executed:

# execute bof $EXT_DIR()/dir.$ARCH().o $PACK_BOF(CSTR {directory}, SHORT {/s})

execute bof ~/tmp/dir.x64.o CQAAAAMAAAAuXAAAAA==

CmdChecker

Agent's console