Edit

Reports API overview for attack simulation training as part of Microsoft Defender for Office 365

  • Article

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.

This section describes reporting capabilities of Microsoft Defender for Office 365, specifically APIs that access reports on a tenant's participation in attack simulation training. Attack simulation trainings set up benign cyberattack simulations to train users in the tenant to increase their awareness, and help identify vulnerable users.

What role do the attack simulation reports play in enterprise defense?

Attack simulation reports help tenant administrators identify security knowledge gaps, so that they can further train their users to decrease their susceptibility to attacks. The attack simulation training service is part of Microsoft Defender for Office 365 which safeguards your organization against malicious threats posed by email messages, links (URLs), and collaboration tools.

Microsoft Defender for Office 365 belongs to the Microsoft 365 Defender suite which includes the following services:

Microsoft 365 Defender is a unified enterprise defense suite that helps detect security risks, investigate attacks to an organization, and prevent harmful activities automatically. It provides a central administrators portal (https://security.microsoft.com/) that combines protection, detection, investigation, and response to email, collaboration, identity, and device threats.

To access attack simulation training, open the Microsoft 365 Defender portal, go to Email & collaboration > Attack simulation training.

Authorization

Microsoft Graph controls access to resources using permissions. You must specify the permissions you need in order to access reports resources. For more information, see Microsoft Graph permissions reference and reports permissions.

What kinds of data do the reports return?

Kinds of data Resource API
Vulnerable repeat offenders in a tenant attackSimulationRepeatOffender getAttackSimulationRepeatOffenders
Simulation data and results for each user in a tenant attackSimulationSimulationUserCoverage getAttackSimulationSimulationUserCoverage
Training coverage for each user in a tenant attackSimulationTrainingUserCoverage getAttackSimulationTrainingUserCoverage

Caution

Make sure to access the following methods from the https://graph.microsoft.com/beta/reports/security endpoint:

  • getAttackSimulationRepeatOffenders
  • getAttackSimulationSimulationUserCoverage
  • getAttackSimulationTrainingUserCoverage

The query endpoints for these methods have changed from https://graph.microsoft.com/beta/reports to https://graph.microsoft.com/beta/reports/security. Methods on the https://graph.microsoft.com/beta/reports/ endpoint are deprecated as of July 15, 2022, and will stop returning data starting August 20, 2022.

Next steps

Reports resources and APIs can open up new ways for you to engage with users and manage their experiences with Microsoft Graph. To learn more:

  • Drill down on the methods and properties of the resources most helpful to your scenario.
  • Try the API in the Graph Explorer.