title	Update simulation
description	Update an attack simulation campaign for a tenant.
author	stuartcl
ms.localizationpriority	medium
ms.subservice	security
doc_type	apiPageType
ms.date	04/04/2024

Update simulation

Namespace: microsoft.graph

Update an attack simulation campaign for a tenant.

[!INCLUDE national-cloud-support]

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

[!INCLUDE permissions-table]

HTTP request

PATCH /security/attackSimulation/simulations/{simulationId}

Request headers

Header	Value
Authorization	Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type	application/json

Request body

[!INCLUDE table-intro]

Property	Type	Description
attackTechnique	simulationAttackTechnique	The social engineering technique used in the attack simulation and training campaign. Supports `$filter` and `$orderby`. Possible values are: `unknown`, `credentialHarvesting`, `attachmentMalware`, `driveByUrl`, `linkInAttachment`, `linkToMalwareFile`, `unknownFutureValue`, `oAuthConsentGrant`. Use the `Prefer: include-unknown-enum-members` request header to get the following values from this evolvable enum: `oAuthConsentGrant`. For more information about the types of social engineering attack techniques, see simulations.
attackType	simulationAttackType	Attack type of the attack simulation and training campaign. Supports `$filter` and `$orderby`. Possible values are: `unknown`, `social`, `cloud`, `endpoint`, `unknownFutureValue`.
displayName	String	Display name of the attack simulation and training campaign. Supports `$filter` and `$orderby`.
durationInDays	Int32	Simulation duration in days.
excludedAccountTarget	accountTargetContent	Users excluded from the simulation.
includedAccountTarget	accountTargetContent	Users targeted in the simulation.
payload	payload	Payload associated with the simulation.
status	simulationStatus	Status of the attack simulation and training campaign. Supports `$filter` and `$orderby`. Possible values are: `unknown`, `draft`, `running`, `scheduled`, `succeeded`, `failed`, `cancelled`, `excluded`, `unknownFutureValue`.

Response

If successful, this method returns a 202 Accepted response code and a tracking header named location in the response.

Examples

Example 1: Update an attack simulation campaign

The following example shows how to update an attack simulation campaign for a tenant.

Request

The following example shows a request.

HTTP

PATCH https://graph.microsoft.com/v1.0/security/attackSimulation/simulations/2f5548d1-0dd8-4cc8-9de0-e0d6ec7ea3dc
Content-type: application/json

{
  "@odata.etag": "\"0100aa9b-0000-0100-0000-6396fa270000\"",
  "displayName": "Graph Simulation",
  "payload@odata.bind":"https://graph.microsoft.com/v1.0/security/attacksimulation/payloads/12345678-9abc-def0-123456789a",
  "durationInDays": 7,
  "attackTechnique": "credentialHarvesting",
  "attackType": "social",
  "status": "scheduled",
  "includedAccountTarget": {
    "@odata.type": "#microsoft.graph.addressBookAccountTargetContent",
    "type" : "addressBook",
    "accountTargetEmails" : [
        "faiza@contoso.com"
    ]
  },
  "excludedAccountTarget": {
    "@odata.type": "#microsoft.graph.addressBookAccountTargetContent",
    "type" : "addressBook",
    "accountTargetEmails" : [
        "sam@contoso.com"
    ]
  }
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

CLI

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

HTTP/1.1 202 Accepted

Example 2: Update an attack simulation campaign from draft to scheduled

The following example shows how to schedule an attack simulation campaign. The simulation request is validated when scheduling a simulation. All the required parameters need to be propagated in such request.

Request

The following example shows a request.

HTTP

PATCH https://graph.microsoft.com/v1.0/security/attackSimulation/simulations/2f5548d1-0dd8-4cc8-9de0-e0d6ec7ea3dc
Content-type: application/json

{
  "@odata.etag": "\"0100aa9b-0000-0100-0000-6396fa270000\"",
  "id": "2f5548d1-0dd8-4cc8-9de0-e0d6ec7ea3dc",
  "displayName": "Graph Simulation",
  "payload@odata.bind":"https://graph.microsoft.com/v1.0/security/attacksimulation/payloads/12345678-9abc-def0-123456789a",
  "durationInDays": 7,
  "attackTechnique": "credentialHarvesting",
  "attackType": "social",
  "status": "scheduled",
  "includedAccountTarget": {
    "@odata.type": "#microsoft.graph.addressBookAccountTargetContent",
    "type" : "addressBook",
    "accountTargetEmails" : [
        "faiza@contoso.com"
    ]
  },
  "excludedAccountTarget": {
    "@odata.type": "#microsoft.graph.addressBookAccountTargetContent",
    "type" : "addressBook",
    "accountTargetEmails" : [
        "sam@contoso.com"
    ]
  }
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

CLI

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

HTTP/1.1 202 Accepted

Example 3: Cancel an attack simulation campaign

The following example shows how to cancel an attack simulation campaign for a tenant. You can cancel a simulation when its state is either scheduled or running.

Request

The following example shows a request.

HTTP

PATCH https://graph.microsoft.com/v1.0/security/attackSimulation/simulations/2f5548d1-0dd8-4cc8-9de0-e0d6ec7ea3dc
Content-type: application/json

{
  "@odata.etag": "\"0100aa9b-0000-0100-0000-6396fa270000\"",
  "id": "2f5548d1-0dd8-4cc8-9de0-e0d6ec7ea3dc",
  "status": "cancelled"
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

CLI

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

HTTP/1.1 202 Accepted

Example 4: Exclude an attack simulation campaign

The following example shows how to exclude an attack simulation campaign for a tenant. You can only exclude a simulation from any reporting when its state is cancelled.

Request

The following example shows a request.

HTTP

PATCH https://graph.microsoft.com/v1.0/security/attackSimulation/simulations/2f5548d1-0dd8-4cc8-9de0-e0d6ec7ea3dc
Content-type: application/json

{
  "@odata.etag": "\"0100aa9b-0000-0100-0000-6396fa270000\"",
  "id": "2f5548d1-0dd8-4cc8-9de0-e0d6ec7ea3dc",
  "status": "excluded"
}