Empire is a pure PowerShell post-exploitation agent built on cytologically-secure communications and a flexible architecture. Empire implements the ability to run PowerShell agents without needing powershell.exe
, rapidly deployable post-exploitation modules ranging from key loggers to Mimikatz, and adaptable communications to evade network detection, all wrapped up in a usability-focused framework.
This document provides information about the Empire connector, which facilitates automated interactions, with an Empire database using FortiSOAR™ playbooks. Add the Empire connector as a step in FortiSOAR™ playbooks and perform automated operations such as creating or terminating listeners, retrieving a list of current listeners, and removing agents.
Connector Version: 1.0.0
FortiSOAR™ Version Tested on: 4.11.0-1161
Empire Version Tested on: 2.5
Authored By: Fortinet.
Certified: Yes
All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum
command to install connectors:
yum install cyops-connector-empire
For the detailed procedure to install a connector, click here.
For the procedure to configure a connector, click here.
In FortiSOAR™ , on the Connectors page, select the Empire connector row, and in the Configuration tab enter the required configuration details.
Parameter | Description |
---|---|
Server URL | Hostname URL or IP address of the Empire server to which you will connect and perform the automated operations. If you not specify the HTTP or HTTPS protocol in this field, then by default the HTTPS protocol is used. |
Server Port | Port number that is used to connect to the Empire server. |
Username | Username to access the Empire endpoint server to which you will connect and perform the automated operations. |
Password | Password to access the Empire endpoint server to which you will connect and perform the automated operations. |
Token | Access token used to access the Empire REST API to which you will connect and perform the automated operations. Note: You must specify either the Username-Password pair or the Token value. |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True . |
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:
Function | Description | Annotation and Category |
---|---|---|
Create Listener | Creates a listener on the Empire server based on the input parameters, such as the listener type and the listener name that you have specified. | create_listener Investigation |
Get Listeners | Retrieves a list and details of all listeners that are available on the Empire server or retrieves the details of a particular listener based on the listener name that you have specified. | get_listeners Investigation |
Get Listener Options | Retrieves a list and details of listener options that are available on the Empire server based on the listener type that you have specified. | get_listener Investigation |
Terminate Listener | Kills all listeners that are available on the Empire server or kills a particular listener based on the listener name that you have specified. | terminate_listener Investigation |
Create Stager | Creates a stager on the Empire server based on the input parameters, such as the stager name and the listener name that you have specified. | create_stager Investigation |
Get Stagers | Retrieves a list and details of all stagers that are available on the Empire server or retrieves the details of a particular stager based on the stager name that you have specified. | get_stager Investigation |
Get Agents | Retrieves a list and details of all agents that are available on the Empire server or retrieves the details of a particular agent based on the agent name that you have specified. | get_agent Investigation |
Get Stale Agents | Retrieves a list and details of all stage agents (past checkin window) from the Empire server. | get_agent Investigation |
Get Agent Results | Retrieves details of a particular agent from the Empire server based on the agent name that you have specified. | get_results Investigation |
Execute Shell Command | Executes a shell command on the Empire server that tasks all agents or a particular agent based on the agent name that you have specified. | run_command Investigation |
Remove Agent | Removes an agent from the Empire server based on the agent name that you have specified or removes all stale agents from the Empire server. | remove_agent Remediation |
Terminate Agent | Kills all agents that are available on the Empire server or kills a particular agent based on the agent name that you have specified. | terminate_agent Remediation |
Remove Agent Results | Removes all stale agent results that are available on the Empire server or removes the result of a particular agent based on the agent name that you have specified. | terminate_agent Investigation |
Get/Search Modules | Retrieves a list and details of all modules that are available on the Empire server or retrieves the details of a particular module based on the module name or search term that you have specified. | search_module Investigation |
Execute Modules | Executes the module that you have specified on a particular agent based on the agent name that you have specified. | run_module Investigation |
Get Credentials | Retrieves a list and details of all credentials currently stored in the Empire server. | get_credentials Investigation |
Parameter | Description |
---|---|
Listener Type | Type of the listener that you want to create on the Empire server. |
Listener Name | Name of the listener that you want to create on the Empire server. |
Additional Listener Values | (Optional) Additional options that you want to add to the listener that you want to create on the Empire server. For more information of additional listener values that you can add, you can use the Get Listener and Get Listener Options operations. |
The JSON output contains a Success
message if the listener based on the input parameters that you have specified is created and started successfully on the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Get Listener By | Options based on which you want to retrieve details of listeners from the Empire server. You can choose from the following options: Get All: Retrieves a list and details of all listeners that are available on the Empire server. Listener Name: Retrieves the details of a particular listener from the Empire server based on the listener name that you have specified. |
Value | Value of the Get Listener By filter option you have selected. If you have selected Get All, then you do not add any input to this field. If you have selected Listener Name, then enter the valid Empire listener name for which you want to retrieve details. |
The JSON output contains a list and details of all listeners that are available on the Empire server or retrieves the details of a particular listener based on the listener name that you have specified. Listener details include listener category, module, name, ID, options, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Listener Type | Type of the listener for which you want to retrieve details from the Empire server. |
The JSON output contains the details of the listener options based on the listener type that you have specified.
Following image displays a sample output:
Parameter | Description |
---|---|
Listener Name | Name of the listener that you want to kill on the Empire server. |
All Listeners | Select this option if you want to kill all listeners from the Empire server. By default, this is set to False . |
The JSON output contains a Success
message if the all the listeners or the listener based on the listener name that you have specified is terminated successfully on the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Stager Name | Name of the stager that you want to create on the Empire server. |
Listener | Name of the listener for which you want to generate the stager on the Empire server. |
Additional Stager Values | (Optional) Additional options that you want to add to the stager that you want to create on the Empire server. For more information of additional stager values that you can add, you can use the Get Stager operation. |
The JSON output contains the details of the stager that is created on the Empire server. Stager details include stager retries, proxy creds, listener, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Get Stager By | Options based on which you want to retrieve details of stagers from the Empire server. You can choose from the following options: Get All: Retrieves a list and details of all stagers that are available on the Empire server. Stager Name: Retrieves the details of a particular stager from the Empire server based on the stager name that you have specified. |
Value | Value of the Get Stager By filter option you have selected. If you have selected Get All, then you do not add any input to this field. If you have selected Stager Name, then enter the valid Empire stager name for which you want to retrieve details. |
The JSON output contains a list and details of all stagers that are available on the Empire server or retrieves the details of a particular stager based on the stager name that you have specified. Stager details include description, name, options, comments, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Get Agent By | Options based on which you want to retrieve details of agents from the Empire server. You can choose from the following options: Get All: Retrieves a list and details of all agents that are available on the Empire server. Agent Name: Retrieves the details of a particular agent from the Empire server based on the agent name that you have specified. |
Value | Value of the Get Agent By filter option you have selected. If you have selected Get All, then you do not add any input to this field. If you have selected Agent Name, then enter the valid Empire agent name for which you want to retrieve details. |
The JSON output contains a list and details of all agents that are available on the Empire server or retrieves the details of a particular agent based on the agent name that you have specified. Agent details include language, hostname, process ID, process name, session key, username, etc.
Following image displays a sample output:
None.
The JSON output contains a list and details of all stale agents that are available on the Empire server. Stale agent details include language, results, high integrity, listener, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Agent Name | Name of the agent whose results you want to retrieve from the Empire server. |
The JSON output contains a list and details of tasks that are run on the particular agent based on the agent name that you have specified. Details include command, result, task ID, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Agent Name | Name of the agent on which you want to execute the shell command on the Empire server. |
Shell Command | Shell command to be run on the Empire server. |
All Agents | Select this option if you want to execute the shell command on all agents on the Empire server. By default, this is set to False . |
The JSON output contains a Success
message and the taskID
if the shell command is run successfully on the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Remove Agent | Select one the following options based on which you want to remove agents from the Empire server:
|
The JSON output contains a Success
message if the specified agent or all stale agents are removed successfully from the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Agent Name | Name of the agent that you want to terminate from the Empire server. |
All Agents | Select this option if you want to terminate all agents from the Empire server. By default, this is set to False . |
The JSON output contains a Success
message if the specified agent or all agents are terminated successfully from the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Agent Name | Name of the agent whose results you want to remove from the Empire server. |
All Results | Select this option if you want to remove results of all agents from the Empire server. By default, this is set to False . |
The JSON output contains a Success
message if the result of the specified agent or results of all the agents are removed successfully from the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Get Module By | Options based on which you want to retrieve details of modules from the Empire server. You can choose from the following options: Get All: Retrieves a list and details of all modules that are available on the Empire server. Module Name: Retrieves the details of a particular module from the Empire server based on the module name that you have specified. Search Term: Retrieves the details of a particular module from the Empire server based on the search term that you have specified. |
Value | Value of the Get Agent By filter option you have selected. If you have selected Get All, then you do not add any input to this field. If you have selected Module Name, then enter the valid Empire module name for which you want to retrieve details. If you have selected Search Term, then enter a term based on which you want to search for module details on the Empire server. |
The JSON output contains a list and details of all modules that are available on the Empire server or retrieves the details of a particular module based on the module name or search term that you have specified. Module details include description, comments, name, author, options, language, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Module Name | Name of the module that you want to execute on the Empire server. |
Agent Name | Name of the agent on which you want to executed the specified module on the Empire server. |
Additional Module Values | (Optional) Additional options, in the JSON format, which you want to add to the module that you want to execute on the Empire server. |
The JSON output contains a Success
message if the specified module is successfully executed on the specified agent on the Empire server.
Following image displays a sample output:
None.
The JSON output contains a list and details of all credentials that are available on the Empire server. Credential details include host, os, domain, username, etc.
Following image displays a sample output:
The Sample - Empire - 1.0.0
playbook collection comes bundled with the Empire connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Empire connector.
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.
Empire is a pure PowerShell post-exploitation agent built on cytologically-secure communications and a flexible architecture. Empire implements the ability to run PowerShell agents without needing powershell.exe
, rapidly deployable post-exploitation modules ranging from key loggers to Mimikatz, and adaptable communications to evade network detection, all wrapped up in a usability-focused framework.
This document provides information about the Empire connector, which facilitates automated interactions, with an Empire database using FortiSOAR™ playbooks. Add the Empire connector as a step in FortiSOAR™ playbooks and perform automated operations such as creating or terminating listeners, retrieving a list of current listeners, and removing agents.
Connector Version: 1.0.0
FortiSOAR™ Version Tested on: 4.11.0-1161
Empire Version Tested on: 2.5
Authored By: Fortinet.
Certified: Yes
All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum
command to install connectors:
yum install cyops-connector-empire
For the detailed procedure to install a connector, click here.
For the procedure to configure a connector, click here.
In FortiSOAR™ , on the Connectors page, select the Empire connector row, and in the Configuration tab enter the required configuration details.
Parameter | Description |
---|---|
Server URL | Hostname URL or IP address of the Empire server to which you will connect and perform the automated operations. If you not specify the HTTP or HTTPS protocol in this field, then by default the HTTPS protocol is used. |
Server Port | Port number that is used to connect to the Empire server. |
Username | Username to access the Empire endpoint server to which you will connect and perform the automated operations. |
Password | Password to access the Empire endpoint server to which you will connect and perform the automated operations. |
Token | Access token used to access the Empire REST API to which you will connect and perform the automated operations. Note: You must specify either the Username-Password pair or the Token value. |
Verify SSL | Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True . |
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:
Function | Description | Annotation and Category |
---|---|---|
Create Listener | Creates a listener on the Empire server based on the input parameters, such as the listener type and the listener name that you have specified. | create_listener Investigation |
Get Listeners | Retrieves a list and details of all listeners that are available on the Empire server or retrieves the details of a particular listener based on the listener name that you have specified. | get_listeners Investigation |
Get Listener Options | Retrieves a list and details of listener options that are available on the Empire server based on the listener type that you have specified. | get_listener Investigation |
Terminate Listener | Kills all listeners that are available on the Empire server or kills a particular listener based on the listener name that you have specified. | terminate_listener Investigation |
Create Stager | Creates a stager on the Empire server based on the input parameters, such as the stager name and the listener name that you have specified. | create_stager Investigation |
Get Stagers | Retrieves a list and details of all stagers that are available on the Empire server or retrieves the details of a particular stager based on the stager name that you have specified. | get_stager Investigation |
Get Agents | Retrieves a list and details of all agents that are available on the Empire server or retrieves the details of a particular agent based on the agent name that you have specified. | get_agent Investigation |
Get Stale Agents | Retrieves a list and details of all stage agents (past checkin window) from the Empire server. | get_agent Investigation |
Get Agent Results | Retrieves details of a particular agent from the Empire server based on the agent name that you have specified. | get_results Investigation |
Execute Shell Command | Executes a shell command on the Empire server that tasks all agents or a particular agent based on the agent name that you have specified. | run_command Investigation |
Remove Agent | Removes an agent from the Empire server based on the agent name that you have specified or removes all stale agents from the Empire server. | remove_agent Remediation |
Terminate Agent | Kills all agents that are available on the Empire server or kills a particular agent based on the agent name that you have specified. | terminate_agent Remediation |
Remove Agent Results | Removes all stale agent results that are available on the Empire server or removes the result of a particular agent based on the agent name that you have specified. | terminate_agent Investigation |
Get/Search Modules | Retrieves a list and details of all modules that are available on the Empire server or retrieves the details of a particular module based on the module name or search term that you have specified. | search_module Investigation |
Execute Modules | Executes the module that you have specified on a particular agent based on the agent name that you have specified. | run_module Investigation |
Get Credentials | Retrieves a list and details of all credentials currently stored in the Empire server. | get_credentials Investigation |
Parameter | Description |
---|---|
Listener Type | Type of the listener that you want to create on the Empire server. |
Listener Name | Name of the listener that you want to create on the Empire server. |
Additional Listener Values | (Optional) Additional options that you want to add to the listener that you want to create on the Empire server. For more information of additional listener values that you can add, you can use the Get Listener and Get Listener Options operations. |
The JSON output contains a Success
message if the listener based on the input parameters that you have specified is created and started successfully on the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Get Listener By | Options based on which you want to retrieve details of listeners from the Empire server. You can choose from the following options: Get All: Retrieves a list and details of all listeners that are available on the Empire server. Listener Name: Retrieves the details of a particular listener from the Empire server based on the listener name that you have specified. |
Value | Value of the Get Listener By filter option you have selected. If you have selected Get All, then you do not add any input to this field. If you have selected Listener Name, then enter the valid Empire listener name for which you want to retrieve details. |
The JSON output contains a list and details of all listeners that are available on the Empire server or retrieves the details of a particular listener based on the listener name that you have specified. Listener details include listener category, module, name, ID, options, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Listener Type | Type of the listener for which you want to retrieve details from the Empire server. |
The JSON output contains the details of the listener options based on the listener type that you have specified.
Following image displays a sample output:
Parameter | Description |
---|---|
Listener Name | Name of the listener that you want to kill on the Empire server. |
All Listeners | Select this option if you want to kill all listeners from the Empire server. By default, this is set to False . |
The JSON output contains a Success
message if the all the listeners or the listener based on the listener name that you have specified is terminated successfully on the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Stager Name | Name of the stager that you want to create on the Empire server. |
Listener | Name of the listener for which you want to generate the stager on the Empire server. |
Additional Stager Values | (Optional) Additional options that you want to add to the stager that you want to create on the Empire server. For more information of additional stager values that you can add, you can use the Get Stager operation. |
The JSON output contains the details of the stager that is created on the Empire server. Stager details include stager retries, proxy creds, listener, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Get Stager By | Options based on which you want to retrieve details of stagers from the Empire server. You can choose from the following options: Get All: Retrieves a list and details of all stagers that are available on the Empire server. Stager Name: Retrieves the details of a particular stager from the Empire server based on the stager name that you have specified. |
Value | Value of the Get Stager By filter option you have selected. If you have selected Get All, then you do not add any input to this field. If you have selected Stager Name, then enter the valid Empire stager name for which you want to retrieve details. |
The JSON output contains a list and details of all stagers that are available on the Empire server or retrieves the details of a particular stager based on the stager name that you have specified. Stager details include description, name, options, comments, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Get Agent By | Options based on which you want to retrieve details of agents from the Empire server. You can choose from the following options: Get All: Retrieves a list and details of all agents that are available on the Empire server. Agent Name: Retrieves the details of a particular agent from the Empire server based on the agent name that you have specified. |
Value | Value of the Get Agent By filter option you have selected. If you have selected Get All, then you do not add any input to this field. If you have selected Agent Name, then enter the valid Empire agent name for which you want to retrieve details. |
The JSON output contains a list and details of all agents that are available on the Empire server or retrieves the details of a particular agent based on the agent name that you have specified. Agent details include language, hostname, process ID, process name, session key, username, etc.
Following image displays a sample output:
None.
The JSON output contains a list and details of all stale agents that are available on the Empire server. Stale agent details include language, results, high integrity, listener, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Agent Name | Name of the agent whose results you want to retrieve from the Empire server. |
The JSON output contains a list and details of tasks that are run on the particular agent based on the agent name that you have specified. Details include command, result, task ID, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Agent Name | Name of the agent on which you want to execute the shell command on the Empire server. |
Shell Command | Shell command to be run on the Empire server. |
All Agents | Select this option if you want to execute the shell command on all agents on the Empire server. By default, this is set to False . |
The JSON output contains a Success
message and the taskID
if the shell command is run successfully on the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Remove Agent | Select one the following options based on which you want to remove agents from the Empire server:
|
The JSON output contains a Success
message if the specified agent or all stale agents are removed successfully from the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Agent Name | Name of the agent that you want to terminate from the Empire server. |
All Agents | Select this option if you want to terminate all agents from the Empire server. By default, this is set to False . |
The JSON output contains a Success
message if the specified agent or all agents are terminated successfully from the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Agent Name | Name of the agent whose results you want to remove from the Empire server. |
All Results | Select this option if you want to remove results of all agents from the Empire server. By default, this is set to False . |
The JSON output contains a Success
message if the result of the specified agent or results of all the agents are removed successfully from the Empire server.
Following image displays a sample output:
Parameter | Description |
---|---|
Get Module By | Options based on which you want to retrieve details of modules from the Empire server. You can choose from the following options: Get All: Retrieves a list and details of all modules that are available on the Empire server. Module Name: Retrieves the details of a particular module from the Empire server based on the module name that you have specified. Search Term: Retrieves the details of a particular module from the Empire server based on the search term that you have specified. |
Value | Value of the Get Agent By filter option you have selected. If you have selected Get All, then you do not add any input to this field. If you have selected Module Name, then enter the valid Empire module name for which you want to retrieve details. If you have selected Search Term, then enter a term based on which you want to search for module details on the Empire server. |
The JSON output contains a list and details of all modules that are available on the Empire server or retrieves the details of a particular module based on the module name or search term that you have specified. Module details include description, comments, name, author, options, language, etc.
Following image displays a sample output:
Parameter | Description |
---|---|
Module Name | Name of the module that you want to execute on the Empire server. |
Agent Name | Name of the agent on which you want to executed the specified module on the Empire server. |
Additional Module Values | (Optional) Additional options, in the JSON format, which you want to add to the module that you want to execute on the Empire server. |
The JSON output contains a Success
message if the specified module is successfully executed on the specified agent on the Empire server.
Following image displays a sample output:
None.
The JSON output contains a list and details of all credentials that are available on the Empire server. Credential details include host, os, domain, username, etc.
Following image displays a sample output:
The Sample - Empire - 1.0.0
playbook collection comes bundled with the Empire connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Empire connector.
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.