Microsoft Graph API Security
The Microsoft Graph API Security connector facilitates the integration of Microsoft's security intelligence and management capabilities into automated workflows.
Microsoft Graph API Security serves as a unified interface for accessing a wealth of security insights and actions across Microsoft 365 services. This connector enables Swimlane Turbine users to automate incident management, threat detection, and response workflows by leveraging Microsoft's extensive security ecosystem. By integrating with Microsoft Graph API Security, users can streamline processes such as adding comments to incidents, managing alerts, executing threat hunting queries, and handling eDiscovery cases, all within the Swimlane platform.
Configuration
Prerequisites
To effectively utilize the Microsoft Graph API Security connector, ensure you have the following prerequisites:
- Client Credentials and Tenant ID authentication with these parameters:
- URL: Endpoint for Microsoft Graph API.
- Client ID: Application ID registered in Azure AD.
- Client Secret: Key generated for the application in Azure AD.
- Tenant ID: Directory ID of the Azure AD tenant.
- Scope: Permissions required for the API access.
- OAuth 2.0 Client Credentials with these parameters:
- URL: Endpoint for Microsoft Graph API.
- Client ID: Application ID registered in Azure AD.
- Client Secret: Key generated for the application in Azure AD.
- Token URL: URL to retrieve the oauth2 token.
- Scope: Permissions required for the API access.
- Delegated Flow Authentication with these parameters:
- URL: Endpoint for Microsoft Graph API.
- Tenant ID: Directory ID of the Azure AD tenant. ... and so on
Authentication Methods
OAuth 2.0 client credentials authentication with these parameters:
- url: Endpoint for Microsoft Graph API.
- client_id: Application (client) ID registered in Azure AD.
- client_secret: Client secret (key) generated for the application in Azure AD.
- token_url: URL to retrieve the OAuth token.
- scope: Permissions the app requires.
Password Grant (Delegated Authentication) for acting on behalf of a user:
- url: Endpoint for Microsoft Graph API.
- tenant_id: Directory ID of the Azure AD tenant.
- oauth_un: User's username to authenticate.
- oauth_pwd: User's password to authenticate.
- oauth_cl_id: Application (client) ID registered in Azure AD.
- oauth_cl_secret: Client secret (key) generated for the application in Azure AD.
- login_url: Login URL. Default value is https://login.microsoftonline.com. (Optional).
- scope: Permissions the app requires. Optional field. (Optional).
Asset credentials specific to your organization (Microsoft Graph API Asset - Tenant ID):
- url: Endpoint for Microsoft Graph API.
- client_ID: Application (client) ID registered in Azure AD.
- client_Secret: Client secret (key) generated for the application in Azure AD.
- tenant_id: Directory ID of the Azure AD tenant.
- scope: Permissions the app requires.
Authentication for OAuth2 Refresh Token Grant credentials for Microsoft Graph API authentication
- url: Endpoint for Microsoft Graph API.
- client_ID: Application (client) ID registered in Azure AD.
- client_Secret: Client secret (key) generated for the application in Azure AD.
- refresh_token: Refresh Token.
- scope: Permissions the app requires.
Capabilities
The Microsoft Graph API connector gives the ability to get and update security alerts, and modify user licenses and sessions.
- Add Incident Comment
- Add Alert Comment
- Cancel Security Action
- Create Security Action
- Get Alert
- Get Incident
- Get Repeat Offenders
- Get Security Action
- Get Security Actions List
- Get Simulation
- Get Simulation Coverage for Users
- Get Simulation Overview
- Get Training Coverage for Users
- Get eDiscovery Case
- List Alerts ... and so on
Asset Setup
Client Credential Flow Authentication
Authentication uses Azure application OAuth2. You will need an admin account in Azure to create the application.
Recommended Application Permissions (feel free use custom permissions if you only use certain actions):
- User.ReadWrite.All
- Directory.ReadWrite.All
- Directory.AccessAsUser.All
- SecurityEvents.Read.All
- SecurityEvents.ReadWrite.All
- Mail.ReadBasic.All
- SecurityAnalyzedMessage.ReadWrite.All
- SecurityAlert.ReadWrite.All
- User.ReadWrite.All
- SecurityIncident.ReadWrite.All
- Group.ReadWrite.All
- IdentityRiskyUser.Read.All
In order to set up the asset, you need the following:
- Azure Application Client ID
- Azure Application Client Secret
- Azure Tenant ID
Steps to create the Azure app:
- Go to the App Registration page in the Azure portal.
- Click New Registration.
- Enter a name for your new application and choose Accounts in this organizational directory only, then click Register at the bottom.
- Navigate to the API permissions tab on the left navigation menu.
- Select Add a permission.
- Select Microsoft Graph.
- Select Application permissions, then mark all the permissions you need for the actions you are using (See suggested permissions at the top of the asset setup section).
- Click the Add permissions button at the bottom of the page.
- Select Grant admin consent for your organization, then your permissions should look as below.
- Navigate to the Certificates & secrets tab and select New client secret.
- Fill out the description and expiration, then click the Add button at the bottom.
- The Value of the secret you just created is the Client Secret needed for the Swimlane asset.
- Navigate to the Overview tab on the left menu.
- The Client ID and Tenant ID needed in the asset are shown on this page.
The Client ID, Tenant ID, and Client Secret described in the steps above are the credentials you need for the asset.
Password Flow (Delegated Auth)
- Use Delegated Permissions, instead of Application Permissions, and generate Client ID, Tenant ID, and Client Secret as described in the above Client Credential Flow Authentication.
- We also need an Username and a Password for this authentication.
Authentication flow for OAuth2 Refresh Token
- Oauth 2.0 refresh token grant, which requires a Refresh Token,Tenant ID, Client ID and Client Secret. Use this auth with accounts which have MFA enabled. To generate a refresh token please follow the instructions below.
- In step 3 of the above-mentioned setup instructions, please provide a Redirect URI and select the platform as 'Web', before clicking on Register at the the bottom.
- Proceed with the remaining steps to generate 'Client ID', Tenant ID and Client Secret.
- Add the permissions in Delegated Permissions.
- The Swimlane team will provide a Python script and instructions on how to use the script to generate the Refresh Token.
Limit Access to specific mailboxes
Administrators who want to limit app access to specific mailboxes can create an application access policy by using the New-ApplicationAccessPolicy PowerShell cmdlet. For more information please see the article Limiting application permissions to specific Exchange Online mailboxes.
Action Setup
OData filters
Information on the filter input formatting can be found here.
Keep in mind that not specifying a folder as an input will result in the query affecting all possible folders. Example: If we want to ingest only unread emails, and we don't set the input "folder", we will ingest all unread emails from all folders, including "Deleted Items", "Junk", etc.
Well Known Folders
Well known folders can be used instead of Folder IDs for email actions. All well known folder names can be found here.
Sites Get Site
All the Sites actions require the site ID to be executed. The site ID can be obtained using the action Sites Get Site, in order to run the action the site_hostname and site_name are needed. This two values can be found in a site URL:
https://{site_hostname}.sharepoint.com/sites/{site_name}For example if our site URL is https://swimlaneintegrations.sharepoint.com/sites/IntegrationsSite we should use:
- site_hostname: swimlaneintegrations
- site_name: IntegrationsSite
After the action execution you can find the Site ID on the ID output field.
Sites Create List
In order to create a list with its columns, use the input Columns. You can find all the possible values with its configuration on the following table.
Property name | Type | Description |
|---|---|---|
boolean | This column stores boolean values. | |
calculated | This column's data is calculated based on other columns. | |
choice | This column stores data from a list of choices. | |
currency | This column stores currency values. | |
dateTime | This column stores DateTime values. | |
geolocation | This column stores a geolocation. | |
lookup | This column's data is looked up from another source in the site. | |
number | This column stores number values. | |
personOrGroup | This column stores Person or Group values. | |
text | This column stores text values. | |
validation | This column stores validation formula and message for the column. | |
hyperlinkOrPicture | This column stores hyperlink or picture values. | |
term | This column stores taxonomy terms. | |
thumbnail | This column stores thumbnail values. | |
contentApprovalStatus | This column stores content approval status. |
For a complete version of this table please see the official column definition table.
Create List Column
Refer to the above table to get the Type properties and Column type input. The Type properties are documented within the links in the Type column.
Get list items
In order to use the filter input please refer to the OData filtersο»Ώ section.
The column used to filter the output must be indexed, see the Microsoft documentation to add an index to a list.
Limitations
When using $filter and $orderby in the same query to get messages, make sure to specify properties in the following ways:
- Properties that appear in $orderby must also appear in $filter.
- Properties that appear in $orderby are in the same order as in $filter.
- Properties that are present in $orderby appear in $filter before any properties that aren't.
Failing to do this results in the following error:
- Error code: InefficientFilter
- Error message: The restriction or sort order is too complex for this operation.
The Assign/Remove User License requires either the disabled plans and accompanying SKU IDs to assign licenses or the SKU ID of the license you want to remove.
The Get Security Alert has additional information it can return. There are a large number of fields that don't relate to many alerts, so they are not mapped; you can add them if desired.
Notes
- oauthlib Legacy Application client, this is sort of a hack to bypass manual login (typically required)
Configurations
Microsoft Graph API Asset - Tenant ID
Authenticates using Client Credentials and Tenant ID
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | A URL to the target host. | string | Required |
tenant_id | The Tenant ID. | string | Required |
client_ID | The client ID | string | Required |
client_Secret | The client secret. | string | Required |
scope | List of permission scopes for this action. | array | Required |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Password Grant (Delegated Authentication)
Authenticates on behalf of a user using oauth 2.0 credentials
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | A URL to the target host. | string | Required |
login_url | ο»Ώ | string | Optional |
tenant_id | ο»Ώ | string | Required |
oauth_un | The username for authentication | string | Required |
oauth_pwd | The password for authentication | string | Required |
oauth_cl_id | The client ID | string | Required |
oauth_cl_secret | The client secret. | string | Required |
scope | Permission scopes for this action. | array | Optional |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Oauth 2.0 Client Credentials
Authenticates using oauth 2.0 client credentials
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | A URL to the target host. | string | Required |
token_url | Must start with https://login.microsoftonline.com/ and then continue with the tenant_id, and then be prepended with /oauth2/v2.0/token | string | Required |
client_id | The client ID | string | Required |
client_secret | The client secret. | string | Required |
scope | List of permission scopes for this action. | array | Required |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
MS Graph OpenID Connect Refresh Token Grant
Authenticates using refresh token.
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | A URL to the target host. | string | Required |
cl_id | The client ID. | string | Required |
cl_secret | The client secret. | string | Required |
refresh_token | Refresh Token. | string | Optional |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Actions
Add Incident Comment
Appends a comment to an existing incident in Microsoft Graph API Security using the provided incidentId.
Endpoint
- URL: /v1.0/security/incidents/{{incidentId}}/comments
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.incidentId | string | Required | ID of the Incident. |
@odata.type | string | Optional | Response data |
comment | string | Optional | The comment to be added. |
Input Example
{"json_body":{"@odata.type":"microsoft.graph.security.alertComment","comment":"Demo for docs"},"path_parameters":{"incidentId":"545"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
value | array | Value for the parameter |
value.comment | string | Value for the parameter |
value.createdByDisplayName | string | Name of the resource |
value.createdDateTime | string | Value for the parameter |
Output Example
{"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#security/incidents('545')/comments","value":[{"comment":"Demo for docs","createdByDisplayName":"API-App:Defender - Test - JHYap","createdDateTime":"2024-06-13T06:38:20.6536162Z"},{"comment":"Demo for docs","createdByDisplayName":"API-App:Defender - Test - JHYap","createdDateTime":"2024-06-13T06:51:40.9010261Z"},{"comment":"Demo for docs","createdByDisplayName":"Defender - Test - JHYap","createdDateTime":"2024-06-13T06:54:26.9428449Z"}...
Cancel Security Action
Cancels an ongoing security action in Microsoft Graph API using the provided action_id.
Endpoint
- URL: /beta/security/securityActions/{{action_id}}/cancelSecurityAction
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.action_id | string | Required | Action ID |
Input Example
{"path_parameters":{"action_id":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
response_text | string | Output field: response_text |
Output Example
{"response_text":"string"}
Create Security Action
Initiates a new security action in Microsoft Graph API with details like name, reason, vendor information, and parameters.
Endpoint
- URL: /beta/security/securityActions
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
name | string | Optional | Action Name |
actionReason | string | Optional | Action Reason |
vendorInformation | object | Optional | Vendor Information |
vendorInformation.vendor | string | Required | Vendor |
vendorInformation.provider | string | Required | Provider |
parameters | array | Optional | Collection of parameters (key-value pairs) necessary to invoke the action, for example, URL or fileHash to block). |
parameters.name | string | Required | Parameters for the Create Security Action action |
parameters.value | string | Required | Parameters for the Create Security Action action |
Input Example
{"name":"Example Name","actionReason":"string","vendorInformation":{"vendor":"string","provider":"string"},"parameters":[{"name":"Example Name","value":"string"}]}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
error | object | Error message if any |
error.code | string | Error message if any |
error.message | string | Response message |
error.innerError | object | Error message if any |
error.innerError.date | string | Error message if any |
error.innerError.request-id | string | Unique identifier |
error.innerError.client-request-id | string | Unique identifier |
Output Example
{"error":{"code":"string","message":"string","innerError":{"date":"2024-01-01T00:00:00Z","request-id":"string","client-request-id":"string"}}}
Get Security Action
Retrieve details for a specific security action from Microsoft Graph API using the 'action_id'.
Endpoint
- URL: /beta/security/securityActions/{{action_id}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.action_id | string | Required | Action ID |
parameters.filter | string | Optional | Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter |
parameters.orderBy | string | Optional | Use the orderby query parameter to specify the sort order of the items returned from Microsoft Graph. |
parameters.top | number | Optional | Sets the page size of results. |
Input Example
{"path_parameters":{"action_id":"string"},"parameters":{"filter":"string","orderBy":"string","top":123}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
error | object | Error message if any |
error.code | string | Error message if any |
error.message | string | Response message |
error.innerError | object | Error message if any |
error.innerError.date | string | Error message if any |
error.innerError.request-id | string | Unique identifier |
error.innerError.client-request-id | string | Unique identifier |
Output Example
{"error":{"code":"string","message":"string","innerError":{"date":"2024-01-01T00:00:00Z","request-id":"string","client-request-id":"string"}}}
Get Security Actions List
Retrieve configurations and details of security actions from the Microsoft Graph Security API.
Endpoint
- URL: /beta/security/securityActions
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.filter | string | Optional | Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter |
parameters.orderBy | string | Optional | Use the orderby query parameter to specify the sort order of the items returned from Microsoft Graph. |
parameters.top | number | Optional | Sets the page size of results. |
Input Example
{"parameters":{"filter":"string","orderBy":"string","top":123}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
value | array | Value for the parameter |
value.file_name | string | Name of the resource |
value.file | string | Value for the parameter |
Output Example
{"@odata.context":"string","value":[{"file_name":"Example Name","file":"string"}]}
Add Alert Comment
Appends a comment to an existing alert identified by alert_id in Microsoft Graph API Security.
Endpoint
- URL: /v1.0/security/alerts_v2/{{alert_id}}/comments
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.alert_id | string | Required | ID of the Alert. |
@odata.type | string | Optional | Response data |
comment | string | Optional | The comment to be added. |
Input Example
{"json_body":{"@odata.type":"microsoft.graph.security.alertComment","comment":"Demo for docs"},"path_parameters":{"alert_id":"da637865765418431569_-773071023"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
value | array | Value for the parameter |
value.comment | string | Value for the parameter |
value.createdByDisplayName | string | Name of the resource |
value.createdDateTime | string | Value for the parameter |
Output Example
{"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#security/alerts_v2('da637865765418431...","value":[{"comment":"Demo for docs","createdByDisplayName":"API-App:Defender - Test - JHYap","createdDateTime":"2024-06-13T06:38:20.6536162Z"},{"comment":"Demo for docs","createdByDisplayName":"API-App:Defender - Test - JHYap","createdDateTime":"2024-06-13T06:51:40.9010261Z"},{"comment":"Demo for docs","createdByDisplayName":"Defender - Test - JHYap","createdDateTime":"2024-06-13T06:54:26.9428...
Get Alert
Retrieve detailed information for a specific security alert by using the 'alert_id' from the Microsoft Graph Security API.
Endpoint
- URL: /v1.0/security/alerts_v2/{{alert_id}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.alert_id | string | Required | ID of the Alert. |
Input Example
{"path_parameters":{"alert_id":"fabefb2117-8e9b-d555-b800-08dc0572c0de"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
id | string | Unique identifier |
providerAlertId | string | Unique identifier |
incidentId | string | Unique identifier |
status | string | Status value |
severity | string | Output field: severity |
classification | string | Output field: classification |
determination | string | Output field: determination |
serviceSource | string | Output field: serviceSource |
detectionSource | string | Output field: detectionSource |
productName | string | Name of the resource |
detectorId | string | Unique identifier |
tenantId | string | Unique identifier |
title | string | Output field: title |
description | string | Output field: description |
recommendedActions | string | Output field: recommendedActions |
category | string | Output field: category |
assignedTo | string | Output field: assignedTo |
alertWebUrl | string | URL endpoint for the request |
incidentWebUrl | string | URL endpoint for the request |
actorDisplayName | object | Name of the resource |
threatDisplayName | object | Name of the resource |
threatFamilyName | object | Name of the resource |
Output Example
{"@odata.context":"string","id":"12345678-1234-1234-1234-123456789abc","providerAlertId":"string","incidentId":"string","status":"active","severity":"string","classification":"string","determination":"string","serviceSource":"string","detectionSource":"string","productName":"Example Name","detectorId":"string","tenantId":"string","title":"string","description":"string"}
List Alerts
Retrieve security alerts from the Microsoft Graph Security API to monitor potential threats and anomalies.
Endpoint
- URL: /v1.0/security/alerts_v2
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.$count | string | Optional | Retrieves the total count of matching resources. |
parameters.$skip | number | Optional | Indexes into a result set. Also used by some APIs to implement paging and can be used together with $top to manually page results. |
parameters.$top | number | Optional | Sets the page size of results. |
parameters.$filter | string | Optional | Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter. |
Input Example
{"parameters":{"$count":"string","$skip":123,"$top":123,"$filter":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
value | array | Value for the parameter |
value.id | string | Unique identifier |
value.providerAlertId | string | Unique identifier |
value.incidentId | string | Unique identifier |
value.status | string | Status value |
value.severity | string | Value for the parameter |
value.classification | string | Value for the parameter |
value.determination | string | Value for the parameter |
value.serviceSource | string | Value for the parameter |
value.detectionSource | string | Value for the parameter |
value.productName | string | Name of the resource |
value.detectorId | string | Unique identifier |
value.tenantId | string | Unique identifier |
value.title | string | Value for the parameter |
value.description | string | Value for the parameter |
value.recommendedActions | string | Value for the parameter |
value.category | string | Value for the parameter |
value.assignedTo | string | Value for the parameter |
value.alertWebUrl | string | URL endpoint for the request |
value.incidentWebUrl | string | URL endpoint for the request |
value.actorDisplayName | object | Name of the resource |
value.threatDisplayName | object | Name of the resource |
Output Example
{"@odata.context":"string","value":[{"id":"12345678-1234-1234-1234-123456789abc","providerAlertId":"string","incidentId":"string","status":"active","severity":"string","classification":"string","determination":"string","serviceSource":"string","detectionSource":"string","productName":"Example Name","detectorId":"string","tenantId":"string","title":"string","description":"string","recommendedActions":"string"}]}
Update Alert
Updates an existing alert in the Microsoft Graph Security API using the provided alert_id and additional details.
Endpoint
- URL: /v1.0/security/alerts_v2/{{alert_id}}
- Method: PATCH
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.alert_id | string | Required | ID of the Alert |
assignedTo | string | Optional | Owner of the incident, or null if no owner is assigned. |
determination | string | Optional | Specifies the determination of the alert. |
classification | string | Optional | Specifies the classification of the alert. |
customDetails | string | Optional | User defined custom fields with string values. |
status | string | Optional | Alert lifecycle status (stage). |
Input Example
{"path_parameters":{"alert_id":"string"},"assignedTo":"string","determination":"string","classification":"string","customDetails":"string","status":"active"}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
id | string | Unique identifier |
providerAlertId | string | Unique identifier |
incidentId | string | Unique identifier |
status | string | Status value |
severity | string | Output field: severity |
classification | string | Output field: classification |
determination | object | Output field: determination |
serviceSource | string | Output field: serviceSource |
detectionSource | string | Output field: detectionSource |
productName | string | Name of the resource |
detectorId | string | Unique identifier |
tenantId | string | Unique identifier |
title | string | Output field: title |
description | string | Output field: description |
recommendedActions | string | Output field: recommendedActions |
category | string | Output field: category |
assignedTo | string | Output field: assignedTo |
alertWebUrl | string | URL endpoint for the request |
incidentWebUrl | string | URL endpoint for the request |
actorDisplayName | object | Name of the resource |
threatDisplayName | object | Name of the resource |
threatFamilyName | object | Name of the resource |
Output Example
{"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#security/alerts_v2/$entity","id":"maf25f0fa0-126a-4297-aff6-ae579cb984a3","providerAlertId":"f25f0fa0-126a-4297-aff6-ae579cb984a3","incidentId":"563","status":"new","severity":"medium","classification":"truePositive","determination":null,"serviceSource":"microsoftAppGovernance","detectionSource":"appGovernanceDetection","productName":"App Governance","detectorId":"b62ae531-7aa6-4bc8-91b9-49a9be960145","tenantId":"f5d73c4c-bb3d-421b-8b...
Get eDiscovery Case
Retrieve details and relationships of a specific eDiscovery case in Microsoft Graph API using the provided ediscoveryCaseId.
Endpoint
- URL: /v1.0/security/cases/ediscoveryCases/{{ediscoveryCaseId}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.ediscoveryCaseId | string | Required | eDiscovery Case ID |
Input Example
{"path_parameters":{"ediscoveryCaseId":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
description | string | Output field: description |
lastModifiedDateTime | string | Time value |
status | string | Status value |
closedDateTime | object | Time value |
externalId | string | Unique identifier |
id | string | Unique identifier |
displayName | string | Name of the resource |
createdDateTime | string | Time value |
lastModifiedBy | object | Output field: lastModifiedBy |
closedBy | object | Output field: closedBy |
Output Example
{"@odata.context":"https://graph.microsoft.com/beta/$metadata#security/cases/ediscoveryCases/$entit...","description":"","lastModifiedDateTime":"2022-05-22T18:36:46.597Z","status":"active","closedDateTime":null,"externalId":"324516","id":"22aa2acd-7554-4330-9ba9-ce20014aaae4","displayName":"CONTOSO LITIGATION-005","createdDateTime":"2022-05-22T18:36:46.597Z","lastModifiedBy":null,"closedBy":null}
List eDiscovery Cases
Retrieve a comprehensive list of eDiscoveryCase objects with properties from the Microsoft Graph API.
Endpoint
- URL: /v1.0/security/cases/ediscoveryCases
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.filter | string | Optional | Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter |
parameters.orderBy | string | Optional | Use the orderby query parameter to specify the sort order of the items returned from Microsoft Graph. |
parameters.top | number | Optional | Sets the page size of results. |
Input Example
{"parameters":{"filter":"string","orderBy":"string","top":123}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
@odata.count | number | Response data |
value | array | Value for the parameter |
value.description | string | Value for the parameter |
value.lastModifiedDateTime | string | Value for the parameter |
value.status | string | Status value |
value.closedDateTime | object | Value for the parameter |
value.externalId | string | Unique identifier |
value.id | string | Unique identifier |
value.displayName | string | Name of the resource |
value.createdDateTime | string | Value for the parameter |
value.lastModifiedBy | object | Value for the parameter |
value.lastModifiedBy.application | object | Value for the parameter |
value.lastModifiedBy.user | object | Value for the parameter |
value.lastModifiedBy.user.id | object | Unique identifier |
value.lastModifiedBy.user.displayName | string | Name of the resource |
value.closedBy | object | Value for the parameter |
value.closedBy.application | object | Value for the parameter |
value.closedBy.user | object | Value for the parameter |
value.closedBy.user.id | object | Unique identifier |
value.closedBy.user.displayName | string | Name of the resource |
Output Example
{"@odata.context":"https://graph.microsoft.com/beta/$metadata#security/cases/ediscoveryCases","@odata.count":22,"value":[{"description":"","lastModifiedDateTime":"2022-05-19T23:30:41.23Z","status":"active","closedDateTime":null,"externalId":"","id":"60f86305-ac3e-408b-baa2-ea585dd8b0c0","displayName":"My case 1","createdDateTime":"2022-05-19T23:30:41.23Z","lastModifiedBy":{},"closedBy":{}},{"description":"","lastModifiedDateTime":"2022-05-18T23:05:07.82Z","status":"active","closedDateTime":null,...
List eDiscovery Case Custodians
Retrieve a list of custodian objects and their properties from Microsoft Graph API using a specific ediscoveryCaseId.
Endpoint
- URL: /v1.0/security/cases/ediscoveryCases/{{ediscoveryCaseId}}/custodians
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.ediscoveryCaseId | string | Required | eDiscovery Case ID |
Input Example
{"path_parameters":{"ediscoveryCaseId":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
@odata.count | number | Response data |
value | array | Value for the parameter |
value.status | string | Status value |
value.holdStatus | string | Status value |
value.createdDateTime | string | Value for the parameter |
value.lastModifiedDateTime | string | Value for the parameter |
value.releasedDateTime | object | Value for the parameter |
value.id | string | Unique identifier |
value.displayName | string | Name of the resource |
value.email | string | Value for the parameter |
value.acknowledgedDateTime | string | Value for the parameter |
Output Example
{"@odata.context":"https://graph.microsoft.com/beta/$metadata#security/cases/ediscoveryCases('b0073...","@odata.count":1,"value":[{"status":"active","holdStatus":"notApplied","createdDateTime":"2022-05-23T00:58:19.0702426Z","lastModifiedDateTime":"2022-05-23T00:58:19.0702436Z","releasedDateTime":null,"id":"0053a61a3b6c42738f7606791716a22a","displayName":"Alex Wilber","email":"[email protected]","acknowledgedDateTime":"0001-01-01T00:00:00Z"}]}
List eDiscovery Case Operations
Retrieve caseOperation objects with properties from Microsoft Graph API using a specified ediscoveryCaseId.
Endpoint
- URL: /v1.0/security/cases/ediscoveryCases/{{ediscoveryCaseId}}/operations
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.ediscoveryCaseId | string | Required | eDiscovery Case ID |
Input Example
{"path_parameters":{"ediscoveryCaseId":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
value | array | Value for the parameter |
value.createdDateTime | string | Value for the parameter |
value.completedDateTime | string | Value for the parameter |
value.percentProgress | number | Value for the parameter |
value.status | string | Status value |
value.action | string | Value for the parameter |
value.id | string | Unique identifier |
value.createdBy | object | Value for the parameter |
value.createdBy.application | object | Value for the parameter |
value.createdBy.user | object | Value for the parameter |
value.createdBy.user.id | string | Unique identifier |
value.createdBy.user.displayName | object | Name of the resource |
value.createdBy.user.userPrincipalName | object | Name of the resource |
Output Example
{"@odata.context":"https://graph.microsoft.com/beta/$metadata#security/cases/ediscoveryCases('b0073...","value":[{"createdDateTime":"2022-05-23T01:09:36.834501Z","completedDateTime":"2022-05-23T01:10:08.8710734Z","percentProgress":100,"status":"succeeded","action":"holdUpdate","id":"1ab699d7e53d46de944144c4a650d66f","createdBy":{}}]}
List eDiscovery Case Review Sets
Retrieve eDiscovery review sets for a given case ID via the Microsoft Graph API, requiring the ediscoveryCaseId path parameter.
Endpoint
- URL: /v1.0/security/cases/ediscoveryCases/{{ediscoveryCaseId}}/reviewSets
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.ediscoveryCaseId | string | Required | eDiscovery Case ID |
Input Example
{"path_parameters":{"ediscoveryCaseId":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
value | array | Value for the parameter |
value.displayName | string | Name of the resource |
value.id | string | Unique identifier |
value.createdDateTime | string | Value for the parameter |
value.createdBy | object | Value for the parameter |
value.createdBy.application | object | Value for the parameter |
value.createdBy.user | object | Value for the parameter |
value.createdBy.user.id | string | Unique identifier |
value.createdBy.user.displayName | string | Name of the resource |
value.createdBy.user.userPrincipalName | string | Name of the resource |
Output Example
{"@odata.context":"https://graph.microsoft.com/beta/$metadata#security/cases/ediscoveryCases('b0073...","value":[{"displayName":"My review set","id":"025852b3-5062-4169-9609-9861a6fe2fe5","createdDateTime":"2022-05-23T16:26:08.7203883Z","createdBy":{}}]}
List eDiscovery Case Searches
Retrieve eDiscovery search resources for a specific case ID in Microsoft Graph API, requiring the ediscoveryCaseId.
Endpoint
- URL: /v1.0/security/cases/ediscoveryCases/{{ediscoveryCaseId}}/searches
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.ediscoveryCaseId | string | Required | eDiscovery Case ID |
Input Example
{"path_parameters":{"ediscoveryCaseId":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
value | array | Value for the parameter |
value.dataSourceScopes | string | Response data |
value.description | string | Value for the parameter |
value.lastModifiedDateTime | string | Value for the parameter |
value.contentQuery | string | Value for the parameter |
value.id | string | Unique identifier |
value.displayName | string | Name of the resource |
value.createdDateTime | string | Value for the parameter |
value.lastModifiedBy | object | Value for the parameter |
value.createdBy | object | Value for the parameter |
value.createdBy.user | object | Value for the parameter |
value.createdBy.user.id | string | Unique identifier |
value.createdBy.user.displayName | string | Name of the resource |
value.createdBy.user.userPrincipalName | string | Name of the resource |
value.createdBy.application | object | Value for the parameter |
value.createdBy.application.id | string | Unique identifier |
value.createdBy.application.displayName | string | Name of the resource |
Output Example
{"@odata.context":"https://graph.microsoft.com/beta/$metadata#security/cases/ediscoveryCases('b0073...","value":[{"dataSourceScopes":"none","description":"My first search","lastModifiedDateTime":"2022-05-23T04:38:07.5787454Z","contentQuery":"(Author=\"edison\")","id":"46867792-68e6-41db-9cd0-f651c2290d91","displayName":"My search 2","createdDateTime":"2022-05-23T04:38:07.5787454Z","lastModifiedBy":null,"createdBy":{}},{"dataSourceScopes":"none","description":"My first search","lastModifiedDateTi...
List eDiscovery Case Tags
Retrieves a list of eDiscoveryReviewTag objects for a specified case using the ediscoveryCaseId from Microsoft Graph API.
Endpoint
- URL: /v1.0/security/cases/ediscoveryCases/{{ediscoveryCaseId}}/tags
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.ediscoveryCaseId | string | Required | eDiscovery Case ID |
Input Example
{"path_parameters":{"ediscoveryCaseId":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
@odata.count | number | Response data |
value | array | Value for the parameter |
value.displayName | string | Name of the resource |
value.lastModifiedDateTime | string | Value for the parameter |
value.childSelectability | string | Value for the parameter |
value.id | string | Unique identifier |
value.createdBy | object | Value for the parameter |
value.createdBy.user | object | Value for the parameter |
value.createdBy.user.id | string | Unique identifier |
value.createdBy.user.displayName | string | Name of the resource |
value.createdBy.user.userPrincipalName | string | Name of the resource |
value.description | string | Value for the parameter |
Output Example
{"@odata.context":"https://graph.microsoft.com/beta/$metadata#security/cases/ediscoveryCases('58399...","@odata.count":5,"value":[{"displayName":"My tag","lastModifiedDateTime":"2022-05-23T19:41:01.7432683Z","childSelectability":"Many","id":"062de822f17a4a2e9b833aa3f6c37108","createdBy":{"user":{"id":"c25c3914-f9f7-43ee-9cba-a25377e0cec6","displayName":"MOD Administrator","userPrincipalName":"[email protected]"}}},{"displayName":"Responsive","description":"","lastModifiedDateTime...
Get Incident
Retrieve detailed information and relationships for a specified incident ID from Microsoft Graph API Security.
Endpoint
- URL: /v1.0/security/incidents/{{incidentId}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.incidentId | string | Required | Incident ID |
Input Example
{"path_parameters":{"incidentId":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.type | string | Response data |
id | string | Unique identifier |
incidentWebUrl | string | URL endpoint for the request |
redirectIncidentId | object | Unique identifier |
displayName | string | Name of the resource |
tenantId | string | Unique identifier |
createdDateTime | string | Time value |
lastUpdateDateTime | string | Time value |
assignedTo | string | Output field: assignedTo |
classification | string | Output field: classification |
determination | string | Output field: determination |
status | string | Status value |
severity | string | Output field: severity |
customTags | array | Output field: customTags |
comments | array | Output field: comments |
comments.comment | string | Output field: comments.comment |
comments.createdBy | string | Output field: comments.createdBy |
comments.createdTime | string | Time value |
Output Example
{"@odata.type":"#microsoft.graph.incident","id":"2972395","incidentWebUrl":"https://security.microsoft.com/incidents/2972395?tid=12f988bf-16f1-11af-11ab-1d7...","redirectIncidentId":null,"displayName":"Multi-stage incident involving Initial access & Command and control on multiple ...","tenantId":"b3c1b5fc-828c-45fa-a1e1-10d74f6d6e9c","createdDateTime":"2021-08-13T08:43:35.5533333Z","lastUpdateDateTime":"2021-09-30T09:35:45.1133333Z","assignedTo":"[email protected]","classification":"...
Get Repeat Offenders
Lists users who have been compromised multiple times in simulation and training campaigns through the Microsoft Graph API.
Endpoint
- URL: /V1.0/reports/security/getAttackSimulationRepeatOffenders
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.filter | string | Optional | Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter |
parameters.orderBy | string | Optional | Use the orderby query parameter to specify the sort order of the items returned from Microsoft Graph. |
parameters.top | number | Optional | Sets the page size of results. |
Input Example
{"parameters":{"filter":"string","orderBy":"string","top":123}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
@odata.nextLink | string | Response data |
value | array | Value for the parameter |
value.repeatOffenceCount | number | Value for the parameter |
value.attackSimulationUser | object | Value for the parameter |
value.attackSimulationUser.userId | string | Unique identifier |
value.attackSimulationUser.displayName | string | Name of the resource |
value.attackSimulationUser.email | string | Value for the parameter |
Output Example
{"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.attackSimu...","@odata.nextLink":"https://graph.microsoft.com/v1.0/reports/security/getAttackSimulationRepeatOffen...","value":[{"repeatOffenceCount":5,"attackSimulationUser":{}},{"repeatOffenceCount":638,"attackSimulationUser":{}}]}
Get Simulation
Retrieve details of an attack simulation campaign in Microsoft Graph API using the unique simulationId.
Endpoint
- URL: /V1.0/security/attackSimulation/simulations/{{simulationId}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.simulationId | string | Required | Simulation ID |
Input Example
{"path_parameters":{"simulationId":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.type | string | Response data |
id | string | Unique identifier |
incidentWebUrl | string | URL endpoint for the request |
redirectIncidentId | object | Unique identifier |
displayName | string | Name of the resource |
tenantId | string | Unique identifier |
createdDateTime | string | Time value |
lastUpdateDateTime | string | Time value |
assignedTo | string | Output field: assignedTo |
classification | string | Output field: classification |
determination | string | Output field: determination |
status | string | Status value |
severity | string | Output field: severity |
customTags | array | Output field: customTags |
comments | array | Output field: comments |
comments.comment | string | Output field: comments.comment |
comments.createdBy | string | Output field: comments.createdBy |
comments.createdTime | string | Time value |
Output Example
{"@odata.type":"#microsoft.graph.incident","id":"2972395","incidentWebUrl":"https://security.microsoft.com/incidents/2972395?tid=12f988bf-16f1-11af-11ab-1d7...","redirectIncidentId":null,"displayName":"Multi-stage incident involving Initial access & Command and control on multiple ...","tenantId":"b3c1b5fc-828c-45fa-a1e1-10d74f6d6e9c","createdDateTime":"2021-08-13T08:43:35.5533333Z","lastUpdateDateTime":"2021-09-30T09:35:45.1133333Z","assignedTo":"[email protected]","classification":"...
Get Simulation Coverage for Users
Lists tenant users' training coverage for attack simulation and training campaigns via Microsoft Graph API.
Endpoint
- URL: /V1.0/reports/security/getAttackSimulationSimulationUserCoverage
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.filter | string | Optional | Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter |
parameters.orderBy | string | Optional | Use the orderby query parameter to specify the sort order of the items returned from Microsoft Graph. |
parameters.top | number | Optional | Sets the page size of results. |
Input Example
{"parameters":{"filter":"string","orderBy":"string","top":123}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
@odata.nextLink | string | Response data |
value | array | Value for the parameter |
value.simulationCount | object | Value for the parameter |
value.latestSimulationDateTime | object | Value for the parameter |
value.clickCount | object | Value for the parameter |
value.compromisedCount | object | Value for the parameter |
value.attackSimulationUser | object | Value for the parameter |
value.attackSimulationUser.userId | string | Unique identifier |
value.attackSimulationUser.displayName | string | Name of the resource |
value.attackSimulationUser.email | string | Value for the parameter |
Output Example
{"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.attackSimu...","@odata.nextLink":"https://graph.microsoft.com/v1.0/reports/security/getAttackSimulationSimulationU...","value":[{"simulationCount":1063,"latestSimulationDateTime":"2022-02-10T10:45:50Z","clickCount":0,"compromisedCount":0,"attackSimulationUser":{}},{"simulationCount":null,"latestSimulationDateTime":null,"clickCount":null,"compromisedCount":null,"attackSimulationUser":{}}]}
Get Simulation Overview
Retrieve an overview of a specific attack simulation and training campaign using the simulationId in Microsoft Graph API.
Endpoint
- URL: /V1.0/security/attackSimulation/simulations/{{simulationId}}/report/overview
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.simulationId | string | Required | Simulation ID |
Input Example
{"path_parameters":{"simulationId":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
value | array | Value for the parameter |
string | Response data | |
value.id | string | Unique identifier |
value.displayName | string | Name of the resource |
value.description | string | Value for the parameter |
value.status | string | Status value |
value.createdDateTime | string | Value for the parameter |
value.createdBy | object | Value for the parameter |
value.createdBy.id | string | Unique identifier |
value.createdBy.displayName | string | Name of the resource |
value.createdBy.email | string | Value for the parameter |
value.lastModifiedDateTime | string | Value for the parameter |
value.lastModifiedBy | object | Value for the parameter |
value.lastModifiedBy.id | string | Unique identifier |
value.lastModifiedBy.displayName | string | Name of the resource |
value.lastModifiedBy.email | string | Value for the parameter |
value.lastRunDateTime | string | Value for the parameter |
value.nextRunDateTime | string | Value for the parameter |
Output Example
{"value":[{"@odata.type":"#microsoft.graph.simulationAutomation","id":"fbad62b0-b32d-b6ac-9f48-d84bbea08f96","displayName":"Reed Flores","description":"Sample Simulation Automation Description","status":"running","createdDateTime":"2022-01-01T01:01:01.01Z","createdBy":{},"lastModifiedDateTime":"2022-01-01T01:01:01.01Z","lastModifiedBy":{},"lastRunDateTime":"2022-01-01T01:01:01.01Z","nextRunDateTime":"2022-01-01T01:01:01.01Z"}]}
Get Training Coverage for Users
Lists tenant users' training coverage in attack simulation and training campaigns via Microsoft Graph API.
Endpoint
- URL: /V1.0/reports/security/getAttackSimulationTrainingUserCoverage
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.filter | string | Optional | Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter |
parameters.orderBy | string | Optional | Use the orderby query parameter to specify the sort order of the items returned from Microsoft Graph. |
parameters.top | number | Optional | Sets the page size of results. |
Input Example
{"parameters":{"filter":"string","orderBy":"string","top":123}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.context | string | Response data |
@odata.nextLink | string | Response data |
value | array | Value for the parameter |
value.userTrainings | array | Value for the parameter |
value.userTrainings.assignedDateTime | string | Value for the parameter |
value.userTrainings.completionDateTime | string | Value for the parameter |
value.userTrainings.trainingStatus | string | Status value |
value.userTrainings.displayName | string | Name of the resource |
value.attackSimulationUser | object | Value for the parameter |
value.attackSimulationUser.userId | string | Unique identifier |
value.attackSimulationUser.displayName | object | Name of the resource |
value.attackSimulationUser.email | object | Value for the parameter |
Output Example
{"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.attackSimu...","@odata.nextLink":"https://graph.microsoft.com/v1.0/reports/security/getAttackSimulationTrainingUse...","value":[{"userTrainings":[],"attackSimulationUser":{}}]}
List Incidents
Retrieve and monitor incidents from Microsoft 365 Defender to manage and track organizational attacks.
Endpoint
- URL: /v1.0/security/incidents
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.$count | string | Optional | Retrieves the total count of matching resources. |
parameters.$skip | number | Optional | Indexes into a result set. Also used by some APIs to implement paging and can be used together with $top to manually page results. |
parameters.$top | number | Optional | Sets the page size of results. |
parameters.$expand | string | Optional | Retrieves related resources. |
parameters.$filter | string | Optional | Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter. |
Input Example
{"parameters":{"$count":"string","$skip":123,"$top":123,"$expand":"string","$filter":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
value | array | Value for the parameter |
string | Response data | |
value.id | string | Unique identifier |
value.incidentWebUrl | string | URL endpoint for the request |
value.redirectIncidentId | object | Unique identifier |
value.tenantId | string | Unique identifier |
value.displayName | string | Name of the resource |
value.createdDateTime | string | Value for the parameter |
value.lastUpdateDateTime | string | Value for the parameter |
value.assignedTo | string | Value for the parameter |
value.classification | string | Value for the parameter |
value.determination | string | Value for the parameter |
value.status | string | Status value |
value.severity | string | Value for the parameter |
value.customTags | array | Value for the parameter |
value.comments | array | Value for the parameter |
value.comments.comment | string | Value for the parameter |
value.comments.createdBy | string | Value for the parameter |
value.comments.createdTime | string | Value for the parameter |
Output Example
{"value":[{"@odata.type":"#microsoft.graph.security.incident","id":"2972395","incidentWebUrl":"https://security.microsoft.com/incidents/2972395?tid=12f988bf-16f1-11af-11ab-1d7...","redirectIncidentId":null,"tenantId":"b3c1b5fc-828c-45fa-a1e1-10d74f6d6e9c","displayName":"Multi-stage incident involving Initial access & Command and control on multiple ...","createdDateTime":"2021-08-13T08:43:35.5533333Z","lastUpdateDateTime":"2021-09-30T09:35:45.1133333Z","assignedTo":"[email protected]"...
List Simulation Automations
Retrieve an overview of attack simulation automations and security test settings in a Microsoft Graph tenant.
Endpoint
- URL: /V1.0/security/attackSimulation/simulationAutomations
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.filter | string | Optional | Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter |
parameters.orderBy | string | Optional | Use the orderby query parameter to specify the sort order of the items returned from Microsoft Graph. |
parameters.top | number | Optional | Sets the page size of results. |
Input Example
{"parameters":{"filter":"string","orderBy":"string","top":123}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
value | array | Value for the parameter |
string | Response data | |
value.id | string | Unique identifier |
value.displayName | string | Name of the resource |
value.description | string | Value for the parameter |
value.status | string | Status value |
value.createdDateTime | string | Value for the parameter |
value.createdBy | object | Value for the parameter |
value.createdBy.id | string | Unique identifier |
value.createdBy.displayName | string | Name of the resource |
value.createdBy.email | string | Value for the parameter |
value.lastModifiedDateTime | string | Value for the parameter |
value.lastModifiedBy | object | Value for the parameter |
value.lastModifiedBy.id | string | Unique identifier |
value.lastModifiedBy.displayName | string | Name of the resource |
value.lastModifiedBy.email | string | Value for the parameter |
value.lastRunDateTime | string | Value for the parameter |
value.nextRunDateTime | string | Value for the parameter |
Output Example
{"value":[{"@odata.type":"#microsoft.graph.simulationAutomation","id":"fbad62b0-b32d-b6ac-9f48-d84bbea08f96","displayName":"Reed Flores","description":"Sample Simulation Automation Description","status":"running","createdDateTime":"2022-01-01T01:01:01.01Z","createdBy":{},"lastModifiedDateTime":"2022-01-01T01:01:01.01Z","lastModifiedBy":{},"lastRunDateTime":"2022-01-01T01:01:01.01Z","nextRunDateTime":"2022-01-01T01:01:01.01Z"}]}
List Simulation Users
Retrieve a list of users from an attack simulation campaign in Microsoft Graph API Security using the 'simulationId'.
Endpoint
- URL: /V1.0/security/attackSimulation/simulations/{{simulationId}}/report/simulationUsers
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.simulationId | string | Required | Simulation ID |
Input Example
{"path_parameters":{"simulationId":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
value | array | Value for the parameter |
value.isCompromised | boolean | Value for the parameter |
value.compromisedDateTime | string | Value for the parameter |
value.simulationEvents | array | Value for the parameter |
value.simulationEvents.eventName | string | Name of the resource |
value.simulationEvents.eventDateTime | string | Value for the parameter |
value.simulationEvents.ipAddress | string | Value for the parameter |
value.simulationEvents.osPlatformDeviceDetails | string | Value for the parameter |
value.simulationEvents.browser | string | Value for the parameter |
value.trainingEvents | array | Value for the parameter |
value.trainingEvents.displayName | string | Name of the resource |
value.trainingEvents.latestTrainingStatus | string | Status value |
value.trainingEvents.trainingAssignedProperties | object | Value for the parameter |
value.trainingEvents.trainingAssignedProperties.contentDateTime | string | Value for the parameter |
value.trainingEvents.trainingAssignedProperties.ipAddress | string | Value for the parameter |
value.trainingEvents.trainingAssignedProperties.osPlatformDeviceDetails | string | Value for the parameter |
value.trainingEvents.trainingAssignedProperties.browser | string | Value for the parameter |
value.trainingEvents.trainingAssignedProperties.potentialScoreImpact | number | Value for the parameter |
value.trainingEvents.trainingUpdatedProperties | object | Value for the parameter |
value.trainingEvents.trainingUpdatedProperties.contentDateTime | string | Value for the parameter |
value.trainingEvents.trainingUpdatedProperties.ipAddress | string | Value for the parameter |
value.trainingEvents.trainingUpdatedProperties.osPlatformDeviceDetails | string | Value for the parameter |
value.trainingEvents.trainingUpdatedProperties.browser | string | Value for the parameter |
Output Example
{"value":[{"isCompromised":true,"compromisedDateTime":"2021-01-01T01:02:01.01Z","simulationEvents":[],"trainingEvents":[],"assignedTrainingsCount":1,"completedTrainingsCount":0,"inProgressTrainingsCount":0,"reportedPhishDateTime":"2021-01-01T01:01:01.01Z","simulationUser":{}}]}
List Simulations
Retrieve attack simulation campaigns from a Microsoft Graph tenant to evaluate security preparedness.
Endpoint
- URL: /v1.0/security/attackSimulation/simulations
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.filter | string | Optional | Use the filter query parameter to retrieve just a subset of a collection. For guidance on using filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter |
parameters.orderBy | string | Optional | Use the orderby query parameter to specify the sort order of the items returned from Microsoft Graph. |
parameters.top | number | Optional | Sets the page size of results. |
Input Example
{"parameters":{"filter":"string","orderBy":"string","top":123}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
value | array | Value for the parameter |
value.id | string | Unique identifier |
value.displayName | string | Name of the resource |
value.description | string | Value for the parameter |
value.attackType | string | Type of the resource |
value.attackTechnique | string | Value for the parameter |
value.status | string | Status value |
value.createdDateTime | string | Value for the parameter |
value.createdBy | object | Value for the parameter |
value.createdBy.id | string | Unique identifier |
value.createdBy.displayName | string | Name of the resource |
value.createdBy.email | string | Value for the parameter |
value.lastModifiedDateTime | string | Value for the parameter |
value.lastModifiedBy | object | Value for the parameter |
value.lastModifiedBy.id | string | Unique identifier |
value.lastModifiedBy.displayName | string | Name of the resource |
value.lastModifiedBy.email | string | Value for the parameter |
value.launchDateTime | string | Value for the parameter |
value.completionDateTime | string | Value for the parameter |
value.isAutomated | boolean | Value for the parameter |
value.automationId | string | Unique identifier |
value.payloadDeliveryPlatform | string | Value for the parameter |
Output Example
{"value":[{"id":"f1b13829-3829-f1b1-2938-b1f12938b1f1","displayName":"Sample Simulation","description":"Sample Simulation Description","attackType":"social","attackTechnique":"credentialHarvesting","status":"scheduled","createdDateTime":"2021-01-01T01:01:01.01Z","createdBy":{},"lastModifiedDateTime":"2021-01-01T01:01:01.01Z","lastModifiedBy":{},"launchDateTime":"2021-01-01T02:01:01.01Z","completionDateTime":"2021-01-07T01:01:01.01Z","isAutomated":false,"automationId":"f1b13829-3829-f1b1-2938-b1f...
Run Hunting Query
Execute advanced threat hunting queries via Microsoft Graph API to pinpoint potential threats in Microsoft 365 Defender.
Endpoint
- URL: /v1.0/security/runHuntingQuery
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
query | string | Optional | The hunting query in Kusto Query Language (KQL) |
Input Example
{"query":"string"}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
schema | array | Output field: schema |
schema.Name | string | Name of the resource |
schema.Type | string | Type of the resource |
results | array | Result of the operation |
results.Timestamp | string | Result of the operation |
results.FileName | string | Name of the resource |
results.InitiatingProcessFileName | string | Name of the resource |
Output Example
{"schema":[{"Name":"Timestamp","Type":"DateTime"},{"Name":"FileName","Type":"String"},{"Name":"InitiatingProcessFileName","Type":"String"}],"results":[{"Timestamp":"2020-08-30T06:38:35.7664356Z","FileName":"conhost.exe","InitiatingProcessFileName":"powershell.exe"},{"Timestamp":"2020-08-30T06:38:30.5163363Z","FileName":"conhost.exe","InitiatingProcessFileName":"powershell.exe"}]}
Update Incident
Updates an incident's classification, determination, and custom tags in Microsoft Graph API using a specific incidentId.
Endpoint
- URL: /v1.0/security/incidents/{{incidentId}}
- Method: PATCH
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.incidentId | string | Required | ID of the Incident |
classification | string | Optional | Parameter for Update Incident |
determination | string | Optional | Parameter for Update Incident |
customTags | array | Optional | Parameter for Update Incident |
assignedTo | string | Optional | Owner of the incident, or null if no owner is assigned. Free editable text. |
status | string | Optional | Status value |
Input Example
{"json_body":{"classification":"TruePositive","determination":"MultiStagedAttack","customTags":["Demo"],"assignedTo":"John Smith","status":"unknown"},"path_parameters":{"incidentId":"2972395"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
@odata.type | string | Response data |
id | string | Unique identifier |
incidentWebUrl | string | URL endpoint for the request |
redirectIncidentId | object | Unique identifier |
displayName | string | Name of the resource |
tenantId | string | Unique identifier |
createdDateTime | string | Time value |
lastUpdateDateTime | string | Time value |
assignedTo | string | Output field: assignedTo |
classification | string | Output field: classification |
determination | string | Output field: determination |
status | string | Status value |
severity | string | Output field: severity |
customTags | array | Output field: customTags |
comments | array | Output field: comments |
comments.comment | string | Output field: comments.comment |
comments.createdBy | string | Output field: comments.createdBy |
comments.createdTime | string | Time value |
Output Example
{"@odata.type":"#microsoft.graph.incident","id":"2972395","incidentWebUrl":"https://security.microsoft.com/incidents/2972395?tid=12f988bf-16f1-11af-11ab-1d7...","redirectIncidentId":null,"displayName":"Multi-stage incident involving Initial access & Command and control on multiple ...","tenantId":"b3c1b5fc-828c-45fa-a1e1-10d74f6d6e9c","createdDateTime":"2021-08-13T08:43:35.5533333Z","lastUpdateDateTime":"2021-09-30T09:35:45.1133333Z","assignedTo":"[email protected]","classification":"...
Response Headers
Header | Description | Example |
|---|---|---|
Cache-Control | Directives for caching mechanisms | ο»Ώ |
client-request-id | HTTP response header: client-request-id | 53216e5d-08e9-4dd7-82d1-bbf17db41756 |
Content-Encoding | HTTP response header: Content-Encoding | gzip |
content-length | The length of the response body in bytes | 140 |
Content-Type | The media type of the resource | application/json |
Date | The date and time at which the message was originated | Tue, 27 Dec 2022 21:12:51 GMT |
Location | The URL to redirect a page to | |
OData-Version | HTTP response header: OData-Version | 4.0 |
request-id | HTTP response header: request-id | 53216e5d-08e9-4dd7-82d1-bbf17db41756 |
Strict-Transport-Security | HTTP response header: Strict-Transport-Security | max-age=31536000 |
Transfer-Encoding | HTTP response header: Transfer-Encoding | chunked |
Vary | HTTP response header: Vary | Accept-Encoding |
x-ms-ags-diagnostic | HTTP response header: x-ms-ags-diagnostic | {"ServerInfo":{"DataCenter":"Central India","Slice":"E","Ring":"3","ScaleUnit":"002","RoleInstance":"PN2PEPF000005BA"}} |