Edit

Create simulation

  • Article

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Create an attack simulation campaign for a tenant.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet
✅ ❌ ❌ ❌

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.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) AttackSimulation.ReadWrite.All Not available.
Delegated (personal Microsoft account) Not supported. Not supported.
Application AttackSimulation.ReadWrite.All Not available.

HTTP request

POST /security/attackSimulation/simulations

Request headers

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

Request body

In the request body, supply a JSON representation of a simulation object.

The following table lists the properties that are required when you create the simulation.

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. Note that you must 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.
createdBy emailIdentity Identity of the user who created the attack simulation and training campaign.
displayName String Display name of the attack simulation and training campaign. Supports $filter and $orderby.
durationInDays Int32 Simulation duration in days. Optional.
endUserNotificationSetting endUserNotificationSetting The end user notification setting for the attack simulation and training campaign.
includedAccountTarget accountTargetContent Users targeted in the simulation.
landingPage landingPage The landing page associated with the attack simulation and training campaign.
lastModifiedBy emailIdentity Identity of the user who most recently modified the attack simulation and training campaign.
launchDateTime DateTimeOffset Date and time of the launch/start of the attack simulation and training campaign. Supports $filter and $orderby. The timestamp represents date and time information using ISO 8601 format and is always in UTC. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z.
loginPage loginPage The login page associated with the attack simulation and training campaign.
oAuthConsentAppDetail oAuthConsentAppDetail Details required for the oAuthConsentGrant technique.
payload payload The payload associated with the attack simulation and training campaign.
payloadDeliveryPlatform payloadDeliveryPlatform Method of delivery of the phishing payload used in the attack simulation and training campaign. Possible values are: unknown, sms, email, teams, unknownFutureValue.
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.
trainingSetting trainingSetting The training setting for the attack simulation and training campaign.

Response

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

Examples

Request

The following example shows a request.

POST https://graph.microsoft.com/beta/security/attackSimulation/simulations
Content-type: application/json

{
  "displayName": "Graph Simulation",
  "payload@odata.bind": "https://graph.microsoft.com/beta/security/attacksimulation/payloads/12345678-9abc-def0-123456789a",
  "loginPage@odata.bind": "https://graph.microsoft.com/beta/security/attacksimulation/loginPages/1w345678-9abc-def0-123456789a",
  "landingPage@odata.bind": "https://graph.microsoft.com/beta/security/attacksimulation/landingPages/1c345678-9abc-def0-123456789a",
  "createdBy": {
    "email": "john@contoso.com"
  },
  "durationInDays": "3",
  "attackTechnique": "credentialHarvesting",
  "status": "scheduled",
  "includedAccountTarget": {
    "@odata.type": "#microsoft.graph.addressBookAccountTargetContent",
    "type": "addressBook",
    "accountTargetEmails": [
      "john@contoso.com"
    ]
  },
  "trainingSetting": {
    "settingType": "noTraining"
  },
  "endUserNotificationSetting": {
    "notificationPreference": "microsoft",
    "settingType": "noTraining",
    "positiveReinforcement": {
      "deliveryPreference": "deliverAfterCampaignEnd",
      "endUserNotification": "https://graph.microsoft.com/beta/security/attacksimulation/endUserNotifications/1ewer3678-9abc-def0-123456789a",
      "defaultLanguage": "en"
    },
    "simulationNotification": {
      "targettedUserType": "compromised",
      "endUserNotification@odata.bind": "https://graph.microsoft.com/beta/security/attacksimulation/endUserNotifications/12wer3678-9abc-def0-123456789a",
      "defaultLanguage": "en"
    }
  }
}

Response

The following example shows the response.

HTTP/1.1 202 Accepted