Announcing Attack Simulation Training Read APIs - now in Beta!
Since GA of Attack Simulation Training earlier this year, one of the most common asks we have heard from our customers and the community has been around exposing APIs to access simulation and reporting information. We are pleased to announce the availability of the Attack Simulation Training Read APIs - currently in Beta!
Attack Simulation Training APIs are onboarded to the Microsoft Graph, and this provides a unified interface and schema to integrate with security solutions from Microsoft and ecosystem partners. The availability of these APIs lights up various business scenarios such as:
- Monitor, track, and integrate Attack Simulation Training data with downstream reporting systems or tools.
- Integrate the data into existing compliance management or learning management systems to drive user awareness.
- Integrate Attack Simulation Training data with other existing systems for security analytics etc.
What’s new?
The following Attack Simulation Training read APIs are now published to Beta and available to be consumed.
1. List Simulations: Retrieve the list of simulations run by the organization.
API endpoint:
https://graph.microsoft.com/beta/security/attackSimulation/simulations
2. Simulation details overview: Retrieve the overview details of a given simulation, such as the number of emails delivered, total clicked count, total compromised count, etc.
API endpoint:
https://graph.microsoft.com/beta/security/attackSimulation/simulations/<simulationId>/report/overview
3. View users' report for a given simulation: Retrieve the detailed report of a given simulation containing actions taken by each user targeted in the simulation.
API endpoint:
https://graph.microsoft.com/beta/security/attackSimulation/simulations/<simulationId>/report/simulationUsers
4. Advanced report – get details of the user coverage report: Retrieve the tenant level aggregate report about overall user coverage.
API endpoint:
https://graph.microsoft.com/beta/reports/getAttackSimulationSimulationUserCoverage
5. Advanced report – get details of the training coverage report: Retrieve the tenant level aggregate report about overall training coverage.
API endpoint:
https://graph.microsoft.com/beta/reports/getAttackSimulationTrainingUserCoverage
6. Advanced report – get details of the repeat offender report: Retrieve the tenant level aggregate report about overall repeat offenders.
API endpoint:
https://graph.microsoft.com/beta/reports/getAttackSimulationRepeatOffenders
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 data via Microsoft Graph APIs:
- The application must be created and registered in Azure AD. You also need to grant the SecurityEvents.Read.All and Reports.Read.All permission scopes. For next steps, we are also working on introducing Attack Simulation Training specific graph permissions which will be available in v1.
- 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 Security Reader role (User-delegated mode).
For more detailed information about security authorization, please see Authorization and the Microsoft Graph Security API.
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.
Please refer to the following documentation for further details on how to use the APIs:
With these APIs, we can now enable a wide variety of custom scenarios. While the possibilities are numerous, a few examples are:
- A notification system that sends an Email or Teams message to admins when there is a simulation status change or an upcoming simulation.
- Using simulation results from Attack Simulation Training to assign trainings using a third-party Learning Management System.
- A power BI report that gives managers a view of simulation results within a team.
While the APIs are in Beta, please do expect changes, enhancements, and improvements leading into General Availability. We are super excited to share this feature availability with you all and look forward to hearing your thoughts and feedback as you start using the APIs!!
