Simulation Deployment¶
Local Simulations¶
PurpleSharp can be used to run simulation playbooks on local endpoints through an interactive session. This type of deployment can be used to test detection and prevention controls on host we have physical access to. The only requirement for this type of simulations is to copy the PurpleSharp assembly on the host.
Depending on the used techniques in the playbook, the simulation may interact with remote hosts in the network. For example, running the PowerShell (T1059.001) technique will execute PowerShell commandlets locally. However, the Password Spraying (T1110.003) technique, will interact with the domain controller or others hosts in the network.
Below is an example of locally running three Process Injection techniques using PurpleSharp’s command line parameters (T1055.002, T1055.003 and T1055.004):
PurpleSharp.exe /t T1055.002,T1055.003,T1055.004
The same simulation playbook can be executed locally using a JSON file as shown below.
{
"type": "local",
"sleep": 5,
"playbooks": [
{
"name": "Process Injection Simulation Playbook",
"enabled": true,
"tasks": [
{
"technique_id": "T1055.002",
"variation": 1
},
{
"technique_id": "T1055.003",
"variation": 1
},
{
"technique_id": "T1055.004",
"variation": 1
}
]
}
]
}
PurpleSharp.exe /pb simulation.json
A demo video of the above simulation can be found here.
Remote Simulations¶
PurpleSharp can be also used to deploy simulation playbooks on remote endpoints. This type of deployment can be used to test the detection and prevention controls on a remote endpoint that may be sitting at a different location across the globe.
To achieve this, PurpleSharp interacts with the remote host trough the network leveraging native Windows features like SMB and RPC. The core requirements for a remote simulation to work include:
- Administrative credentials on the remote host
- Network connectivty to SMB port TCP/445
- Network connectivty to RPC ports TCP/135 and
Below is an example of using PurpleSharp’s command line parameter to deploy a remote simulation:
PurpleSharp.exe /rhost win10-1 /ruser psharp /rpwd Passw0rd1 /d hacklabz.com /t T059.001
The same simulation playbook can be executed remotely using a JSON file as shown below.
{
"type": "remote",
"domain": "labz.com",
"username": "SuperUser",
"sleep": 5,
"playbooks": [
{
"name": "Process Injection Simulation Playbook",
"remote_host": "192.168.1.2",
"scout_full_path": "C:\\Windows\\Temp\\Installer.exe",
"simulator_relative_path": "AppData\\Local\\Temp\\tmp12345.exe",
"enabled": true,
"tasks": [
{
"technique_id": "T1055.002",
"variation": 1
},
{
"technique_id": "T1055.003",
"variation": 1
},
{
"technique_id": "T1055.004",
"variation": 1
}
]
}
]
}
PurpleSharp.exe /pb simulation.json
A demo video of the above simulation can be found on this link.
Command line Cheat Sheet¶
Warning
Using command line parameters to execute simulations with PurpleSharp does not leverage all available features. If you are looking to customize the simulations with more flexibility, you should use JSON playbooks.
- Execute the T1059.001 technique on local host:
PurpleSharp.exe /t T1059.001
- Execute 3 techniques on local host:
PurpleSharp.exe /t T1055.002,T1055.003,T1055.004
PurpleSharp.exe /t "T1055.002, T1055.003, T1055.004"
Note
When using a space between techniques, make sure to add double quotes.
- Execute 3 techniques on local host adding a sleep time of 5 seconds between technique:
PurpleSharp.exe /t "T1055.002, T1055.003, T1055.004" /pbsleep 5
- Execute the T1059.001 technique on a remote host:
PurpleSharp.exe /rhost win10-1 /ruser psharp /d hacklabz /t T1059.001
PurpleSharp.exe /rhost 192.168.1.10 /ruser psharp /d hacklabz /t T1059.001
- Execute 3 chained techniques on a remote host and wait 30 seconds between each technique:
PurpleSharp.exe /rhost win10-1 /ruser psharp /d hacklabz /t T1059.001,T1059.002,T1059.003 /pbsleep 30
PurpleSharp.exe /rhost 192.168.1.10 /ruser psharp /d hacklabz /t T1059.001,T1059.002,T1059.003 /pbsleep 30
- Execute a techniques on a remote host using custom Scout and Simulator paths:
PurpleSharp.exe /rhost win10-1 /ruser psharp /d hacklabz /t T1059.001 /scoutpath C:\PSEXSVC.exe /simpath \AppData\Local\Temp\invoice.exe
- Obtain the Windows Event Subscription settings from a remote host:
PurpleSharp.exe /rhost win10-1 /ruser psharp /d hacklabz /scout wef
Command Line Parameters¶
Warning
Using command line parameters to execute simulations with PurpleSharp does not leverage all available features. If you are looking to customize the simulations with more flexibility, you should use JSON playbooks.
Required Simulation Parameters¶
Remote Host (/rhost)¶
Defines the remote host the simulation will run on.
Note
If set to ‘random’, PurpleSharp will perform LDAP queries on the defined domain controller and randomly pick a simulation target.
Remote User (/ruser)¶
Defines the domain user used to deploy the simulation. This user needs to be part of the ‘Administrators’ group on the remote host.
Domain (/d)¶
Defines the domain the simulation target is part of.
Technique(s) (/t)¶
Defines the MITRE ATT&CK Framework technique id or ids to use in the simulation.
Note
When using more than one technique, use a comma to separate them and no space between them.
PurpleSharp.exe /t T1055.002,T1055.003,T1055.004
Optional Simulation Parameters¶
Remote Password (/rpwd)¶
Defines the password for the user used to deploy the simulation. If not present, PurpleSharp will prompt for the password.
Domain Controller (/dc)¶
When deploying simulations on a random host, this settings specifices the Domain Controller to run the LDAP queries on.
Verbose (/v)¶
When set, the Scout logs will be presented as part of the output.
Playbook Sleep Time (/pbsleep)¶
When simulating more than one technique, this parameter defines the amount of time in seconds to sleep between each technique execution.
Technique Sleep Time (/tsleep)¶
Certain techniques also support an internal sleep time defined with this parameter in seconds.
Note
When used with the Kerberoasting technique, PurpleSharp will sleep between each Kerberos Service Ticket request.
Scout Path (/scoutpath)¶
Defines the absolute path where the Scout will be uploaded to on the remote host. If not set, PurpleSharp will use the default path: C:\Windows\Scout.exe.
Simulator Path (/simpath)¶
Defines the relative path where the Simulator will be uploaded to on the remote host. If not set, PurpleSharp will use the default path: \Downloads\Firefox_Installer.exe.
No Clean Up (/nocleanup)¶
Certain techniques will create an artifact on the remote endpoint. PurpleSharp will by default delete the artifact as part of the clean up process when a simulation is completed. When this parameter is set, the clean phase for the particular technique will be skipped.
Note
As an example, when using the Windows Service technique (T1543.003) with /nocleanup, PurpleSharp will not delete the created Windows Service from the simulation target after installing it.
No Opsec (/noopsec)¶
When set, PurpleSharp will not use the Parent Process ID Spoofing technique the execute the Simulator. This will result in the Simulator running in the context of the service account used to deploy the simulation.
Other Parameters¶
Scout (/scout)¶
PurpleSharp can execute reconoissance tasks on remote hosts with the goal of providing the operator relevant information about them before running simulations. The following scout tasks are supported:
- auditpol: This action will retrieve the remote endpoint’s advanced audit policy settings.
- wef: This action will retrieve the remote endpoint’s Windows Event Subscription settings.
- pws: This action will retrieve the remote endpoint’s Module Logging, Transcription Logging and SecriptBlock Logging PowerShell settints.
- ps: This action will retrieve the remote endpoint’s running processes.
- svcs: This action will retrieve the remote endpoint’s running Windows services.
- all: This option will execute all of the above tasks.
PurpleSharp.exe PurpleSharp.exe /scout all /rhost host /ruser user /d domain
Playbook (/pb)¶
This parameter defines the JSON Playbook to use as an input for the simulation.
PurpleSharp.exe /pb SimulationPlaybook.json
JSON Playbooks¶
Using command line parameters became a limitation when trying to run adversary simulation playbooks that execute several techniques with mulitple variations. Thats why PurpleSharp also supports the use of JSON files to describe one or more multi-technique playbooks.
Using JSON files also enables us to further customize the simulation with technique-specific parameters. Each technique may leverage multiple parameters. These parameters may also be used across more than one technique. For example, the serviceName parameter is only relevant for the Create Service technique but the dllPath parameter can be use for several techniques like Rundll32.exe and Regsvr32.exe. If not explicitly defined, a default value is used to execute a technique.
The following JSON playbook instructs PurpleShap to executes 4 techniques sequentially with a 10 second sleep time between each.
Note
Some of the parameters of the playbook below are just informational and are not required nor used by PurpleSharp.
{
"type": "local",
"sleep": 10,
"playbooks": [
{
"name": "Simulation Playbook",
"enabled": true,
"tasks": [
{
"technique_name": "Create or Modify System Process: Windows Service",
"technique_id": "T1543.003",
"serviceName": "Legit Service",
"servicePath": "C:\\Windows\\SysWOW64\\WindowsPowerShell\\v1.0\\powershell.exe",
"cleanup": true,
"variation": 1,
"description": "This variation uses the Win32 APIs: CreateService, OpenService and DeleteService to create a service",
},
{
"technique_name": "Create or Modify System Process: Windows Service",
"technique_id": "T1543.003",
"serviceName": "Legit Service",
"servicePath": "C:\\Windows\\System32\\msiexec.exe",
"cleanup": false,
"variation": 2,
"description": "This variation executes the command 'sc create Legit Service binpath= C:\\Windows\\System32\\msiexec.exe' to create a service",
"description2": "The service will not be deleted as per the cleanup variable",
}
}
]
}
We can execute this playbook using the /pb parameter as shown below. If you want to avoid the use of command line parameteres altogether and have PurpleSharp automatically execute a playbook, you can embed your JSON playbook to the PurpleSharp assembly as a resource. PurpleSharp will automatically read and execute the Playbook.json embedded resource. At the moment, the only way of achieveing this is by manually adding your playbook to the project and building it with Visual Studio. More details here.
PurpleSharp.exe /pb simulation_playbook.json
For more simulation playbooks examples, visit the Active Directory Purple Team Playbook, a repository of ready-to-use JSON playbooks for PurpleSharp.
If you want to create custom playbooks and want to know about all the possible parameters each technique supports, or all the possible simulation parameters visit the Supported Techniques section or review the projects Model.cs source file.
Execution¶
T1059.001 - Command and Scripting Interpreter: PowerShell¶
Variations¶
| Variation | Description |
| 1 | This module uses the Win32 API CreateProcess to execute the specified
commandlet:
powershell.exe -command {commandlet}
|
| 2 | This module uses the the System.Management.Automation .NET namespace
to execute the specified commandlet.
|
Parameters¶
| Parameter | Description |
| commandlet | The PowerShell commandlet to be executed in the simulation. |
T1059.003 Command and Scripting Interpreter: Windows Command Shell¶
Variations¶
| Variation | Description |
| 1 | This module uses the Win32 API CreateProcess to execute the specified
command:
cmd.exe /c command
|
Parameters¶
| Parameter | Description |
| command | The command shell to be executed in the simulation. |
T1059.005 Command and Scripting Interpreter: Visual Basic¶
Variations¶
| Variation | Description |
| 1 | This module uses the Win32 API CreateProcess to execute the specified
VB script:
wscript.exe file_path
|
Parameters¶
| Parameter | Description |
| file_path | The local file path of the VB script. |
T1059.007 Command and Scripting Interpreter: JavaScript/JScript¶
Variations¶
| Variation | Description |
| 1 | This module uses the Win32 API CreateProcess to execute the specified
JS script:
wscript.exe file_path
|
Parameters¶
| Parameter | Description |
| file_path | The local file path of the JS script. |
T1053.005 Scheduled Task/Job: Scheduled Task¶
Variations¶
| Variation | Description |
| 1 | This module uses the Win32 API CreateProcess to create a scheduled
task:
SCHTASKS /CREATE /SC DAILY /TN taskName /TR taskPath /ST 13:00
|
Parameters¶
| Parameter | Description |
| taskName | The name of the task to be created. |
| taskPath | The path of the binary to be executed by the scheduled task. |
| cleanup | Bool parameter to delete the scheduled task after created. |
Persistence¶
T1136.001 - Create Account: Local Account¶
Variations¶
| Variation | Description |
| 1 | This module uses the Win32 API NetUserAdd to create a local account
with the specified parameters.
|
| 2 | This module uses the Win32 API CreateProcess to create a local account
with the specified parameters.
net user user password /add
|
Parameters¶
| Parameter | Description |
| user | The user to be created. |
| password | The password to be used. |
| cleanup | Bool parameter to delete the user after created. |
T1543.003 - Create or Modify System Process: Windows Service¶
Variations¶
| Variation | Description |
| 1 | This module uses the Win32 API CreateService to create a Windows
Service with the specified parameters.
|
| 2 | This module uses the Win32 API CreateProcess to create a Windows
Service with the specified parameters.
sc create serviceName binpath= servicePath type= own start= auto
|
Parameters¶
| Parameter | Description |
| serviceName | The name of the Windows service to be created. |
| servicePath | The path of the binary that will be executed by the service. |
| serviceDisplayName | The service display name. |
| cleanup | Bool parameter to delete the Service after created. |
T1547.001 - Boot or Logon Autostart Execution: Registry Run Keys¶
Variation 1¶
Variation 2¶
Variations¶
| Variation | Description |
| 1 | This module uses the Microsoft.Win32 .NET namespace to create a
Registry Key with the specified parameters.
|
| 2 | This module uses the Win32 API CreateProcess to create a Registry
Key with the specified parameters.
reg add reg_ /V BadApp /t REG_SZ /F /D C:WindowsTempxyz12345.exe
|
Parameters¶
| Parameter | Description |
| serviceName | The name of the Windows service to be created. |
| servicePath | The path of the binary that will be executed by the service. |
| serviceDisplayName | The service display name. |
| cleanup | Bool parameter to delete the Service after created. |
Defense Evasion¶
T1055.002 - Process Injection: Portable Executable Injection¶
T1055.004 - Process Injection: Asynchronous Procedure Call¶
T1220 XSL - Script Processing¶
Variation 1¶
Variation 2¶
T1218.011 - Signed Binary Proxy Execution: Rundll32¶
T1218.003 - Signed Binary Proxy Execution: CMSTP¶
T1218.005 - Signed Binary Proxy Execution: Mshta¶
T1140 - Deobfuscate/Decode Files or Information¶
T1218.010 - Signed Binary Proxy Execution: Regsvr32¶
T1218.009 - Signed Binary Proxy Execution: Regsvcs/Regasm¶
Credential Access¶
T1110.003 - Brute Force: Password Spraying¶
Variation 1¶
Variation 2¶
Discovery¶
T1049 - System Network Connections Discovery¶
T1033 - System Owner/User Discovery¶
T1007 - System Service Discovery¶
T1087.002 - Account Discovery: Domain Account¶
Variation 1¶
Variation 2¶
T1046 - Network Service Scanning¶
T1087.001 - Account Discovery: Local Account¶
Presentations¶
Blue Team Village at DEF CON 28 (2019)¶
Purple On My Mind: Cost Effective Automated Adversary Simulation
Derbycon 9.0 (2019)¶
I sim(ulate), therefore i catch: enhancing detection engineering with adversary simulation
Demos¶
Attack Range + PurpleSharp Integration¶
Demos @ BlackHat Arsenal 2021¶
Demos @ Defcon 29 Aversary Village¶
Demo 1 @ Purple Team Summit 2021¶
Demo 2 @ Purple Team Summit 2021¶
Demo 1 @ BlackHat Arsenal 2020¶
Demo 2 @ BlackHat Arsenal 2020¶
Demo 1 @ Defcon 28 Safe Mode - Blue Team Village¶
Demo 2 @ Defcon 28 Safe Mode - Blue Team Village¶
Demo 3 @ Defcon 28 Safe Mode - Blue Team Village¶
Demo 1 @ EU ATT&CK Community Workshop¶
Demo 2 @ EU ATT&CK Community Workshop¶
Defending enterprise networks against attackers continues to present a difficult challenge for blue teams. Prevention has fallen short; improving detection & response capabilities has proven to be a step in the right direction. However, without the telemetry produced by adversary behavior, building new and testing existing detection capabilities will be constrained.
PurpleSharp is an open source adversary simulation tool written in C# that executes adversary techniques within Windows Active Directory environments. The resulting telemetry can be leveraged to measure and improve the efficacy of a detection engineering program. PurpleSharp leverages the MITRE ATT&CK Framework and executes different techniques across the attack life cycle: execution, persistence, privilege escalation, credential access, lateral movement, etc. It currently supports 47 unique ATT&CK techniques.
PurpleSharp was first presented at Derbycon IX on September 2019. An updated version was released on August 6th 2020 as part of BlackHat Arsenal 2020. The latest version was released on August 2021 as part of BlackHat Arsenal 2021.
Visit the Demos section to see PurpleSharp in action.
Goals / Use Cases¶
The attack telemetry produced by simulating techniques with PurpleSharp aids detection teams in:
- Building new detection analytics
- Testing existing detection analytics
- Validating detection resiliency
- Identifying gaps in visibility
- Identifing issues with event logging pipeline
Quick Start Guide¶
Build from Source¶
PurpleSharp can be built with Visual Studio Community 2019 or 2020.
Download Latest Release¶
Download the latest release binary ready to be used to execute TTP simulations.
Simulate¶
The PurpleSharp assembly is all you need to start simulating attacks.
For simulation ideas, check out the Active Directory Purple Team Playbook, a repository of ready-to-use JSON playbooks for PurpleSharp.
Acknowledgments¶
The community is a great source of ideas and feedback. Thank you all.