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 https //portal azure com/#blade/microsoft aad registeredapps/applicationslistblade 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 https //docs microsoft com/en us/graph/auth limit mailbox access action setup odata filters information on the filter input formatting can be found https //docs microsoft com/en us/graph/query parameters#filter parameter 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 https //docs microsoft com/en us/graph/api/resources/mailfolder?view=graph rest 1 0 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 https //docs microsoft com/en us/graph/api/resources/booleancolumn?view=graph rest 1 0 this column stores boolean values calculated https //docs microsoft com/en us/graph/api/resources/calculatedcolumn?view=graph rest 1 0 this column's data is calculated based on other columns choice https //docs microsoft com/en us/graph/api/resources/choicecolumn?view=graph rest 1 0 this column stores data from a list of choices currency https //docs microsoft com/en us/graph/api/resources/currencycolumn?view=graph rest 1 0 this column stores currency values datetime https //docs microsoft com/en us/graph/api/resources/datetimecolumn?view=graph rest 1 0 this column stores datetime values geolocation https //docs microsoft com/en us/graph/api/resources/geolocationcolumn?view=graph rest 1 0 this column stores a geolocation lookup https //docs microsoft com/en us/graph/api/resources/lookupcolumn?view=graph rest 1 0 this column's data is looked up from another source in the site number https //docs microsoft com/en us/graph/api/resources/numbercolumn?view=graph rest 1 0 this column stores number values personorgroup https //docs microsoft com/en us/graph/api/resources/personorgroupcolumn?view=graph rest 1 0 this column stores person or group values text https //docs microsoft com/en us/graph/api/resources/textcolumn?view=graph rest 1 0 this column stores text values validation https //docs microsoft com/en us/graph/api/resources/columnvalidation?view=graph rest 1 0 this column stores validation formula and message for the column hyperlinkorpicture https //docs microsoft com/en us/graph/api/resources/hyperlinkorpicturecolumn?view=graph rest 1 0 this column stores hyperlink or picture values term https //docs microsoft com/en us/graph/api/resources/termcolumn?view=graph rest 1 0 this column stores taxonomy terms thumbnail https //docs microsoft com/en us/graph/api/resources/thumbnailcolumn?view=graph rest 1 0 this column stores thumbnail values contentapprovalstatus https //docs microsoft com/en us/graph/api/resources/contentapprovalstatuscolumn?view=graph rest 1 0 this column stores content approval status for a complete version of this table please see https //docs microsoft com/en us/graph/api/resources/columndefinition?view=graph rest 1 0#properties 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 docid\ s5kiirfkmlig wpfudlwh section the column used to filter the output must be indexed, see the https //support microsoft com/en us/office/add an index to a list or library column f3f00554 b7dc 44d1 a2ed d477eac463b0?ui=en us\&rs=en us\&ad=us 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 https //social technet microsoft com/wiki/contents/articles/33525 an introduction to microsoft graph api aspx https //www microsoft com/en us/security/intelligence security api https //docs microsoft com/en us/graph/api/overview?view=graph rest 1 0 https //docs microsoft com/en us/graph/query parameters https //docs microsoft com/en us/azure/active directory/develop/v1 protocols oauth code https //requests oauthlib readthedocs io/en/latest/oauth2 workflow\ html#legacy application flow , 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" "alexw\@m365x809305 onmicrosoft com","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" "admin\@m365x809305 onmicrosoft com"}}},{"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" "kaic\@contoso onmicrosoft com","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" "kaic\@contoso onmicrosoft com","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 value \@odata type 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 value \@odata type 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" "kaic\@contoso onmicrosoft com" 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 value \@odata type 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" "kaic\@contoso onmicrosoft com","classification" " response headers header description example cache control directives for caching mechanisms client request id http response header client request id 8beed643 f868 4fd0 9e15 e0db4c50383e 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 fri, 23 may 2025 10 42 13 gmt location the url to redirect a page to https //graph microsoft com odata version http response header odata version 4 0 request id http response header request id 3763884a 1de2 4f55 a7cd 53a5fda6a36d 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" "000","roleinstance" "pn1pepf00007039"}}