Introducing the release of Attack Simulation Training Write API functionality (available in beta)
Published May 04 2023 01:12 PM 7,272 Views

Attack Simulation Training is an intelligent social engineering phish risk reduction tool that measures behavior change and automates the deployment of an integrated security awareness training program across an organization. It is available with Microsoft 365 E5 or Microsoft Defender for Office 365 P2 plan, and we also have a special teaser version available with Microsoft 365 E3. 

We are excited to announce the release of Attack Simulation Write API functionality, a powerful tool for improving your organization's defense to phishing messages. This new API, available in beta, is part of Microsoft's Graph API suite and offers a range of new features and functionality. The highlights in this release are the ability to create and manage simulations directly through the API. It builds on our previous version of read APIs, providing organizations & partners with even more control and flexibility when it comes to simulating potential attacks on their systems.  

Key benefits of this API are:  

  • It allows security teams to create customized attack scenarios based on real events that are specific to their organization's infrastructure. This makes it easier to identify potential vulnerabilities and test the effectiveness of existing security measures.  
  • Another important feature of the Attack Simulation Graph Write API is its ability to integrate with other security tools and services. This makes it easier for organizations to manage and track their security analytics at one place.  
  • Additionally, it allows managed service providers and cloud solution providers to easily manage multiple tenants as part of their security tools and services.  

The API documentation can be found on Microsoft Learn. 

What’s new:

  • Launch a social engineering simulation using a range of attack techniques, such as credential harvesting, attachment malware, drive-by URLs, links in attachments, and links to malware files. These attacks can be customized using global or tenant payloads available in the tenant. 
  • Edit existing simulations for a tenant via commands – Delete, Exclude, Update and Cancel. 
  • Select all or specific target users for a simulation. 
  • Get the list of available payloads, payload objects and payload details from global and tenant content sources. 
  • Get a payload associated with any simulation.  
  • Track long-running attack simulation operations. 

MicrosoftTeams-image (21).png

Please note that certain properties are currently under development and will take on default settings when creating a new simulation. These include the default GitHub login page, Microsoft recommended training with a due date of 7 days after the simulation ends, Microsoft Landing Page Template 1, and default display of payload indicators in emails. No end-user notifications will be sent by default. 

What’s upcoming: 

Upcoming functionalities include creating a new simulation using OAuth technique, customization of training, login page, landing page, payload indicators, and end-user notifications when creating a new simulation, and the ability to create and edit simulation automation. 

With the updated set of features, the attack simulation API is more powerful and versatile than ever before. With access to user data, security data, device data, collaboration data, and other data types through the Microsoft Graph API, Security Administrators can create effective phishing simulations to identify vulnerabilities and improve the organization's overall security posture. 



Getting Started 

The Microsoft Graph Security API is usually accessed in one of the following ways: 

  • By an application where no user is signed in (or) where the application manages user access (for example, a SIEM solution) 
  • In the context of an authenticated user in User-delegated mode (for example, through Graph Explorer) 

More information on authentication and authorization basics for Microsoft graph can be found here.  


To access Attack Simulation Training via Microsoft Graph APIs: 

  • The application must be created and registered in Azure AD. You also need to grant the AttackSimulation.ReadWrite.All permission scope. If you already have an application with AttackSimulation.Read.All permission, then you can grant the AttackSimulation.ReadWrite.All in the scope. 
  • The Azure AD tenant administrator must then consent to the permissions requested. 
  • If users are associated with the application, the Azure AD tenant administrator will need to add them to the appropriate role (User-delegated mode). 

MicrosoftTeams-image (20).png



For more detailed information about security authorization, please see Authorization and the Microsoft Graph Security API. 


Additionally, MSPs & CSPs will require obtaining least-privileged and time-bound access to Attack Simulation Azure AD roles with GDAP in order to manage their customers’ tenants (Granular delegated admin privileges). 

With the authentication and authorization model set-up, you are now ready to access data. You can get started using the Graph Explorer to study requests and responses or use Postman 


Sample Powershell scripts: 

To help Security Administrators quickly test out the attack simulation API, sample PowerShell scripts are available. These scripts cover two popular scenarios: 

  • Launching monthly simulations automatically for a period of one year by dividing all users into 12 groups and sending different payloads each time. 
  • Sending simulations to top users identified from advanced hunting from real phishing attacks. 

Please note that these scripts are only intended for testing purposes and should not be used in production environments. 


While the APIs are in Beta, please do expect changes, enhancements, and improvements leading into General Availability. We look forward to continuing to improve and develop our API in the future. We are excited to see how you will take advantage of these new capabilities and look forward to your feedback.  

Version history
Last update:
‎May 04 2023 01:12 PM
Updated by: