Skip to content

05_Modules Configurations

Jump to bottom
q-roland edited this page Aug 20, 2025 · 1 revision

When injecting configurations into a GPO with the gpo > inject command, GroupPolicyBackdoor expects one or several INI file(s) describing the module(s) to inject.

You can find examples of module configuration files in the modules_templates directory. Such files are divided into three sections: MODULESCONFIG, MODULEOPTIONS and MODULEFILTERS.

MODULECONFIG section

The MODULECONFIG section describes which configuration you want to inject, and if this configuration should be applied by user objects or computer objects. Here are the available options.

  • [REQUIRED] name: The name of the configuration to inject. At the moment, the following configurations are supported: Scheduled Tasks, Groups, Registry, Files, Folders.
  • [REQUIRED] type: The type of configuration, that can be either "computer" or "user".

MODULEOPTIONS section

The MODULEOPTIONS section is used to customize the configuration you want to inject with various options, that are specific to said configuration. This page describes, for each configuration, the supported options.

Options requiring to specify the date are all in the ISO 8601 format:

# Target domain local time
2025-02-19T23:21:05
# UTC time
2025-02-19T23:21:05Z
# UTC+1 time
2025-02-19T22:21:05+01:00

Scheduled Tasks

This configuration handles the creation and deletion of Scheduled Tasks (included Immediate Tasks). Use it to run arbitrary commands, possibly with the identity of other domain users.

Sample files:

  • modules_templates/ScheduledTask_create.ini
  • modules_templates/ScheduledTask_delete.ini
  • modules_templates/ImmediateTask_create.ini

Available options:

  • [OPTIONAL] action: Can be either "create" or "delete". Whether the configuration should create or delete the Scheduled Task. Ignored for Immediate Tasks. When the action is "delete", only the task_name option is considered.
    Default value: "create".

  • [OPTIONAL] task_type: Can be either "scheduled" or "immediate". Whether the created task should be a standard scheduled task, or an immediate task.
    Default value: "scheduled".

  • [REQUIRED] program: The program to launch (for instance, "cmd.exe" or "powershell.exe").

  • [REQUIRED] arguments: The arguments to pass to the program.

  • [OPTIONAL] impersonate: If this option is not specified, the task will run with the local NT AUTHORITY\SYSTEM account (the one of the computer applying the GPO for computer GPOs, or the one of the computer on which the user applying the GPO is logged on for user GPOs).
    If this option is used, you should provide a domain user in the DOMAIN\username format (e.g CORP\john). The task will then run with the identity of the target user (and will only execute when the user has an interactive session on the machine).
    For user GPOs only, you can use the %LogonDomain%\%LogonUser% value. In that case, the scheduled task will execute with the identity of the user applying the GPO.
    This option works best with tasks of type 'scheduled'. For 'immediate' tasks, impersonating a user will only work if the impersonated user has an active session on the machine when the GPO is applied for the first time since task injection.
    Default value: None (use NT AUTHORITY\SYSTEM)

  • [OPTIONAL] repeat_every: The interval at which the task will be executed, in minutes. Should be comprised between 1 (every minute) and 43200 (every 30 days).
    Default value: 60 (the task executes every hour)

  • [OPTIONAL] start_from: The date from which the Scheduled Task will begin to be executed. Use the ISO 8601 format.
    Default value: 30 days before current UTC date.

  • [OPTIONAL] expiration_date: The date after which the Scheduled Task will be removed by the task scheduler on targets. Use the ISO 8601 format.
    Default value: None (no expiration)

  • [OPTIONAL] task_name: The name of the Scheduled Task, displayed in GPMC and Task Scheduler
    Default value: "OneDrive Telementry".

  • [OPTIONAL] author: The displayed author for the task.
    Default value: "Microsoft Corporation".

  • [OPTIONAL] description: The displayed description for the task.
    Default value: No description.

Groups

This configuration handles the addition or removal of domain users to local groups on target machines.

Sample files:

  • modules_templates/Groups_add.ini
  • modules_templates/Groups_remove.ini

Available options:

  • [REQUIRED] action: Can be either "add" or "remove". Whether the configuration should add the target user to the specified group, or remove the user from it.

  • [REQUIRED] group_sid: The SID of the local group to add/remove the user to/from (for instance, "S-1-5-32-544" for the Administrators built-in group).

  • [REQUIRED] user_sid: The SID of the domain user to add to the group.

  • [OPTIONAL] group_name: The name of the local group the user will be added to/removed from. This is purely optional and is only used for display in the GPMC. Only the group SID is taken into account.
    Default value: None

  • [OPTIONAL] user_name: The name of the domain user to add to/remove from the group. This is purely optional and is only used for display in the GPMC. Only the user SID is taken into account.
    Default value: None

Registry

This configuration handles the modification of registry keys on target machines.

Sample files:

  • modules_templates/Registry_set.ini

Available options:

  • [REQUIRED] hive: The target registry hive. Can be one of the following: "HKEY_CLASSES_ROOT", "HKEY_CURRENT_USER", "HKEY_LOCAL_MACHINE", "HKEY_USERS", "HKEY_CURRENT_CONFIG".

  • [REQUIRED] path: The path to the target key (for instance, "SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters").

  • [REQUIRED] key: The registry key to edit (for instance, "SMB1").

  • [REQUIRED] key_type: The type of key that will be edited. Can be one of the following: "REG_SZ", "REG_DWORD", "REG_BINARY", "REG_MULTI_SZ", "REG_EXPAND_SZ", "REG_QWORD".

  • [REQUIRED] value: The value to affect to the key. The format depends on the key type:

    • REG_SZ: an arbitrary string.
    • REG_DWORD: a 32bits hexadecimal number (e.g. "1", "1C" etc.).
    • REG_BINARY: binary data (e.g. "00101").
    • REG_MULTI_SZ: a list of strings separated by the '||' sequence (e.g. "somevalue||someothervalue||etc").
    • REG_EXPAND_SZ: an arbitrary string.
    • REG_QWORD: a 64bits hexadecimal number.

Files

This configuration handles the transfer and removal of files between systems. You can upload files to remote machines, or exfiltrate files to other machines. As file transfers are performed via SMB, you may want to first enable anonymous guest access via a Registry configuration if you want the target to download a file from a non-domain joined machine.

Sample files:

  • modules_templates/File_create.ini
  • modules_templates/File_delete.ini

Available options:

  • [REQUIRED] action: Can be either "create" or "delete". Whether a file should be transfered or deleted from the target machine.

  • [REQUIRED] source_file: The file that should be transferred to the destination. Can be a local or UNC path. Ignored for the "delete" action.

  • [REQUIRED] destination_file: The path to which the source file should be transferred, or the path of the file to be deleted. Can be a local or UNC path.

  • [OPTIONAL] hidden: Can be either "true" or "false". Whether the transferred file should be hidden.
    Default value: false.

Folders

This configuration handles the creation and deletion of folders on the target machines.

Sample files:

  • modules_templates/Folder_create.ini
  • modules_templates/Folder_delete.ini

Available options:

  • [REQUIRED] action: Can be either "create" or "delete". Whether the folder should be created or deleted.

  • [REQUIRED] path: The path to the folder to be created or deleted.

  • [OPTIONAL] recursive_delete: Can be either "true" or "false". Whether, when deleting the folder, all the folder's content should be recursively deleted
    Default value: false.

  • [OPTIONAL] hidden: Can be either "true" or "false". Whether the created folder should be hidden.
    Default value: false.

MODULEFILTERS section

One of the concerns regularily raised when exploiting GPOs resides in the fact that a GPO can potentially be applied by a high number of domain objects. From an offensive standpoint (either for stealth or exploit safety considerations), one may not be willing to deploy a configuration to hundreds or thousands of objects.

GroupPolicyBackdoor implements configurations that support Item-level targeting, a feature allowing to only deploy a configuration to specific objects that meet one or more criteria. A lot of criteria exist, and GroupPolicyBackdoor implements the following filters:

  • Computer Name: only apply the configuration if the target computer has a specific name.
  • Security Group: only apply the configuration if the target object is part of a security group.
  • WMI Query: only apply the configuration if the defined WMI query returns true.

You can apply multiple targeting items to a preference item and select the logical operation (AND or OR) by which to combine each targeting item with the preceding one. If the combined value of all targeting items for a preference item is false, then the settings in the preference item are not applied to the user or computer.
Filters are specified under the filters option that should specify a valid JSON list of filters. The first filter should always have the "AND" operator.

⚠️ Note that to produce a valid JSON string, backslashes must be escaped

Here is an example of a valid filters option for a configuration. With such filters, the configuration will only be applied if the computer has the DNS name ad01-bastion.corp.com, and the object that applies it (here, a user) is a member of the Domain Admins group:

filters =
    [{
        "operator": "AND",
        "type": "Computer Name",
        "value": "ad01-bastion.corp.com"
    },
    {
        "operator": "AND",
        "type": "Security Group",
        "group_name": "CORP\\IT_SUPPORT",
        "group_sid": "S-1-5-21-2015307081-2275635861-2347354195-512",
        "user_context": true
    }]

The following sections provide some information regarding the options available for each filter.

Computer Name

When defining a filter of type "Computer Name", only one value is expected:

  • [REQUIRED] value: the DNS name of the computer (full FQDN).

Security Group

When defining a filter of type "Security Group", the following values can be specified:

  • [REQUIRED] group_sid: The SID of the security group that the object should be part of.

  • [OPTIONAL] group_name: The name of the security group that the object should be part of. Note that this is only for display purposes in the GPMC. Only the group_sid is actually considered by the filter.
    Default value: Empty

  • [OPTIONAL] primary_group: Can be either "true" or "false". Whether the specified group should be the primary group of the object.
    Default value: False

  • [REQUIRED] user_context: Can be either "true" or "false". This configuration only makes sense for configurations of type user. If "true", the user applying the configuration should be part of the group. If "false", the computer on which the user applying the configuration is connected should be part of the group. For a computer configuration, this should always be "false".

WMI query

When defining a filter of type "WMI Query", the following values can be specified:

  • [REQUIRED] query: the WMI query to execute. Configuration will only be applied if the query returns True.

  • [OPTIONAL] namespace: the namespace in which the WMI query should be executed.
    Default value: "Root\\cimv2"

Some "WMI query" filter examples:

; Only applies to Windows 10 computers and only applies to Windows Servers that are not Domain Controllers
filters = 
    [{
        "operator": "AND",
        "type": "WMI Query",
        "query": "SELECT * FROM Win32_OperatingSystem WHERE Version LIKE '10.%' AND ProductType='3'",
    }]
; Only applies to computers with names starting with 'PC-'
filters = 
    [{
        "operator": "AND",
        "type": "WMI Query",
        "query": "SELECT * FROM Win32_ComputerSystem WHERE Name LIKE 'PC-%'",
    }]

Note: Filters gotchas

There is a weird gotcha with item-level targeting filters that you might encounter when you combine filters.

When defining filters, if you provide a "Computer Name" filter with a DNS name that does not exist in the domain, the filters chain will always evaluate to false (and not apply the GPO), even if you have other valid filters specified in an "OR" condition. For instance, if you specified two filters:

  • Computer Name = idonotexist.corp.com
  • OR Computer Name = srv1.corp.com

And your GPO applies to srv1.corp.com, the filters will still evaluate as False because idonotexist.corp.com is not a FQDN corresponding to an existing domain machine. Thus, the configuration will not apply.

This is also the case if you provide a WMI Query with an invalid synthax.

More generally, if a filter somehow "crashes" or is somehow considered as invalid by Windows, the whole chain will evaluate to "False" and your condifuration will not apply.

Clone this wiki locally