Update: As of October 31, 2023, the status of the 'Create Simulation Graph' API has changed from beta to v1 (General Availability). Learn more
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 is now GA and 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.
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).
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.