Blog Post

Security, Compliance, and Identity Blog
3 MIN READ

Announcing Attack Simulation Training Read APIs - Now in Beta!

Gopal-MSFT's avatar
Gopal-MSFT
Icon for Microsoft rankMicrosoft
Oct 08, 2021

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!!

Updated Oct 08, 2021
Version 1.0
  • Reid Culp's avatar
    Reid Culp
    Brass Contributor

    Does Microsoft Attack Simulator exclude the admin who is setting up the simulation? I have tried to run two simulations and both seem to exclude me from the simulation (i.e., it did not send me an email). We are a small firm, and we need to document training for compliance purposes.

  • Aragorn's avatar
    Aragorn
    Iron Contributor

    User a separate account for all admin functions. Use this account for setting up your simulation so that your actual account receives the simulations.

  • PatrickF11's avatar
    PatrickF11
    Steel Contributor

    Is there any planned timeline when this will get general available?

     

    Edit: I've just tested v1.0 and some queries are already working. But i can't find anything that confirms this.. 😄 (e.g. the list all simulations)