Microsoft Defender

the microsoft defender connector enables seamless integration between microsoft defender's security capabilities and swimlane's automation workflows, facilitating real time threat detection and response microsoft defender is a comprehensive endpoint security solution that provides real time protection against a wide range of threats such as malware, phishing, and ransomware the microsoft defender turbine connector enables users to automate and streamline security workflows by integrating with microsoft defender's robust api this integration allows for seamless execution of actions like alert creation, machine isolation, and threat investigation, directly enhancing the incident response capabilities within the swimlane turbine platform prerequisites before you can use the microsoft defender connector for turbine, ensure you have the following prerequisites oauth 2 0 client credentials for service to service authentication url endpoint url for microsoft defender api client id application (client) id registered in azure ad client secret secret key generated for the application in azure ad scope the scope of the access request delegated flow authentication for user based authentication url endpoint url for microsoft defender api tenant id directory (tenant) id in azure ad username the username of the account with permissions to access microsoft defender password the password for the account specified client id application (client) id registered in azure ad client secret secret key generated for the application in azure ad authentication methods oauth 2 0 client credentials authentication with these parameters url endpoint for microsoft defender api client id application id registered in azure ad client secret key generated for the application in azure ad tenant id or token url at least one of these parameters is required for authentication tenant id identifier for the azure ad tenant token url token url for azure ad must start with https //login microsoftonline com/ https //login microsoftonline com/ , followed by the tenant id, and appended with /oauth2/v2 0/token scope permissions the application requires delegated flow authentication with these parameters url endpoint for microsoft defender api tenant id identifier for the azure ad tenant username the username for delegated access password the password for delegated access client id application id registered in azure ad client secret key generated for the application in azure ad login url login url default value is https //login microsoftonline com https //login microsoftonline com (optional) scope permissions the app requires optional field (optional) additional notes about asset please make sure to pass atleast one of the tenant id or token url in the inputs for the asset asset and permissions setup 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 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 apis my organization uses tab or any permissions relevant tab select the relevant options or permissions for the action you want to test or run, 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 capabilities the microsoft defender advanced threat protection integration provides the following capabilities cancel machine action create alert decode generated bearer token delete indicator by id get alert get alert domains get alert files get alert ips get alert machine information get alert user information get alerts get domain related alerts get domain related machines get domain seen organization get domain statistics and so on additional information about capabilities the microsoft defender advanced threat protection api allows the user to run queries against their enrolled systems you can find information about the advanced hunting api here https //docs microsoft com/en us/windows/security/threat protection/microsoft defender atp/run advanced query api additionally, microsoft has provided example queries here https //github com/microsoft/windowsdefenderatp hunting queries installation considerations to utilize this connector, you must have access to an e5 license of microsoft defender atp additionally, you must create a new application in azure active directory start a new trial https //www microsoft com/en us/microsoft 365/windows/microsoft defender atp of microsoft defender atp or use your existing license to access the api if you have not done so already, please follow the initial setup instructions here https //docs microsoft com/en us/windows/security/threat protection/microsoft defender atp/licensing once you have a microsoft defender atp installed on a machine, then you will create a new application in azure active directory application permissions ti readwrite all required for import indicators action configurations microsoft defender password grant (delegated auth) 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 microsoft defender 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 tenant id the tenant id string optional token url must start with https //login microsoftonline com/ https //login microsoftonline com/ and then continue with the tenant id, and then be prepended with /oauth2/v2 0/token string optional 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 actions cancel machine action cancels a pending machine action in microsoft defender by using the provided 'machineactionid' endpoint url /api/machineactions/{{machineactionid}}/cancel method post input argument name type required description machineactionid string required the machine action id comment string optional comment to associate with the cancellation action output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier type string type of the resource scope string output field scope requestor string output field requestor externalid string unique identifier requestsource string output field requestsource commands array output field commands cancellationrequestor string output field cancellationrequestor requestorcomment string output field requestorcomment cancellationcomment string output field cancellationcomment status string status value machineid string unique identifier computerdnsname string name of the resource cancellationdatetimeutc string output field cancellationdatetimeutc creationdatetimeutc string output field creationdatetimeutc lastupdatedatetimeutc string output field lastupdatedatetimeutc title string output field title relatedfileinfo string output field relatedfileinfo example \[ { "status code" 200, "response headers" { "date" "fri, 07 feb 2025 10 57 23 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "mise correlation id" "8d39c870 35e0 4d26 aa40 b15aa1b5c79a", "odata version" "4 0", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "id" "5382f7ea 7557 4ab7 9782 d50480024a4e", "type" "collectinvestigationpackage", "scope" "selective", "requestor" "analyst\@testprd onmicrosoft com", "externalid" "", "requestsource" "", "commands" \[], "cancellationrequestor" "", "requestorcomment" "test for docs", "cancellationcomment" "", "status" "succeeded", "machineid" "7b1f4967d9728e5aa3c06a9e617a22a4a5a17378", "computerdnsname" "desktop test", "cancellationdatetimeutc" "2019 01 02t14 39 38 2262283z", "creationdatetimeutc" "2019 01 02t14 39 38 2262283z" } } ] create alert generates a new alert in microsoft defender using details like machine id, severity, and event time for threat identification endpoint url /api/alerts/createalertbyreference method post input argument name type required description machineid string required id of the device on which the event was identified severity string required severity of the alert title string required title for the alert description string required description of the alert recommendedaction string required security officer needs to take this action when analyzing the alert eventtime string required the precise time of the event as string, as obtained from advanced hunting reportid string required the reportid of the event, as obtained from advanced hunting category string required category of the alert output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier incidentid number unique identifier investigationid object unique identifier assignedto object output field assignedto severity string output field severity status string status value classification object output field classification determination object output field determination investigationstate string output field investigationstate detectionsource string output field detectionsource detectorid string unique identifier category string output field category threatfamilyname object name of the resource title string output field title description string output field description alertcreationtime string time value firsteventtime string time value lasteventtime string time value lastupdatetime string time value resolvedtime object time value machineid string unique identifier computerdnsname string name of the resource rbacgroupname string name of the resource example \[ { "status code" 200, "response headers" { "transfer encoding" "chunked", "content type" "application/json", "content encoding" "gzip", "vary" "accept encoding", "strict transport security" "max age=31536000", "date" "tue, 30 apr 2024 10 36 47 gmt" }, "reason" "ok", "json body" { "id" "da637472900382838869 1364969609", "incidentid" 1126093, "investigationid" null, "assignedto" null, "severity" "low", "status" "new", "classification" null, "determination" null, "investigationstate" "queued", "detectionsource" "windowsdefenderatp", "detectorid" "17e10bbc 3a68 474a 8aad faef14d43952", "category" "execution", "threatfamilyname" null, "title" "low reputation arbitrary code executed by signed executable", "description" "binaries signed by microsoft can be used to run low reputation arbitrary code t " } } ] decode generated bearer token decodes a jwt token to reveal the contents of microsoft defender bearer tokens for integration purposes endpoint method get output parameter type description data object response data aud string output field aud iss string output field iss iat number output field iat nbf number output field nbf exp number output field exp aio string output field aio appid string unique identifier appidacr string unique identifier idp string unique identifier oid string unique identifier rh string output field rh sub string output field sub tenant region scope string output field tenant region scope tid string unique identifier uti string output field uti ver string output field ver example \[ { "data" { "aud" "00000002 0000 0000 c000 000000000000", "iss" "https //sts windows net/f5d73c4c bb3d 421b 8bee 424916a4acca/", "iat" 1711522981, "nbf" 1711522981, "exp" 1711526881, "aio" "e2ngynbqzq9y5r7ip+fo4k0fvva1aqa=", "appid" "c806de2d 6f0a 4fcf 91b9 fc285ee6da31", "appidacr" "1", "idp" "https //sts windows net/f5d73c4c bb3d 421b 8bee 424916a4acca/", "oid" "84e31d9d b042 4ced 8437 7c17db9ee8b4", "rh" "0 as0atdzx9t27g0kl7kjjfqssygiaaaaaaaaawaaaaaaaaaataaa ", "sub" "84e31d9d b042 4ced 8437 7c17db9ee8b4", "tenant region scope" "na", "tid" "f5d73c4c bb3d 421b 8bee 424916a4acca", "uti" "hbp57z85nea5e8fetawzaa" } } ] delete indicator by id removes a specified security indicator from microsoft defender using the unique id provided in path parameters endpoint url /api/indicators/{{id}} method delete input argument name type required description id string required unique identifier 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 example \[ { "status code" 200, "response headers" { "date" "thu, 30 may 2024 10 21 38 gmt", "content length" "0", "connection" "keep alive", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "response text" "" } ] get alert retrieves detailed information for a specified alert in microsoft defender using the unique alert id endpoint url /api/alerts/{{id}} method get input argument name type required description id string required unique identifier 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 incidentid number unique identifier investigationid number unique identifier assignedto string output field assignedto severity string output field severity status string status value classification object output field classification determination object output field determination investigationstate string output field investigationstate detectionsource string output field detectionsource detectorid string unique identifier category string output field category threatfamilyname object name of the resource title string output field title description string output field description alertcreationtime string time value firsteventtime string time value lasteventtime string time value lastupdatetime string time value resolvedtime string time value machineid string unique identifier computerdnsname string name of the resource example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 13 05 30 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#alerts/$entity", "id" "ar638180599315648136 73827727", "incidentid" 400, "investigationid" 6, "assignedto" "api action", "severity" "informational", "status" "resolved", "classification" null, "determination" null, "investigationstate" "benign", "detectionsource" "automatedinvestigation", "detectorid" "5c6b7d86 c91f 4f8c 8aec 9d2086f46527", "category" "suspiciousactivity", "threatfamilyname" null, "title" "automated investigation started manually" } } ] get alert domains retrieve domain information associated with a specific microsoft defender alert using the unique alert id endpoint url /api/{{id}}/domains method get input argument name type required description id string required unique identifier 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 example \[ { "status code" 404, "response headers" { "date" "thu, 04 may 2023 13 08 46 gmt", "content length" "0", "connection" "keep alive", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "not found", "response text" "" } ] get alert ips retrieves ip addresses associated with a specific microsoft defender alert using the provided alert id endpoint url /api/{{id}}/ips method get input argument name type required description id string required unique identifier 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 example \[ { "status code" 404, "response headers" { "date" "thu, 04 may 2023 13 11 16 gmt", "content length" "0", "connection" "keep alive", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "not found", "response text" "" } ] get alert machine information retrieve detailed machine information associated with a specific microsoft defender alert using the unique alert id endpoint url /api/alerts/{{id}}/machine method get input argument name type required description id string required unique identifier 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 mergedintomachineid object unique identifier ispotentialduplication boolean output field ispotentialduplication isexcluded boolean output field isexcluded exclusionreason object response reason phrase computerdnsname string name of the resource firstseen string output field firstseen lastseen string output field lastseen osplatform string output field osplatform osversion object output field osversion osprocessor string output field osprocessor version string output field version lastipaddress string output field lastipaddress lastexternalipaddress string output field lastexternalipaddress agentversion string output field agentversion osbuild number output field osbuild healthstatus string status value devicevalue string value for the parameter rbacgroupid number unique identifier rbacgroupname object name of the resource riskscore string score value exposurelevel string output field exposurelevel example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 13 16 32 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#machines/$entity", "id" "556b3952acb0bff29816d267822305781cc183ec", "mergedintomachineid" null, "ispotentialduplication" false, "isexcluded" false, "exclusionreason" null, "computerdnsname" "se pov desktop", "firstseen" "2023 04 19t13 27 53 1618923z", "lastseen" "2023 05 04t12 47 48 3622932z", "osplatform" "windows10", "osversion" null, "osprocessor" "x64", "version" "21h2", "lastipaddress" "192 168 12 203", "lastexternalipaddress" "172 56 64 139" } } ] get alert user information retrieve detailed user information associated with a specific microsoft defender alert using the unique alert id endpoint url /api/alerts/{{id}}/user method get input argument name type required description id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase error object error message if any code string output field code message string response message target string output field target example \[ { "status code" 404, "response headers" { "date" "thu, 04 may 2023 13 19 32 gmt", "content type" "application/json; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "not found", "json body" { "error" {} } } ] get alerts retrieve a comprehensive list of alerts from microsoft defender to identify potential security threats endpoint url /api/alerts method get input argument name type required description $filter string optional parameter for get alerts $select string optional parameter for get alerts $orderby string optional parameter for get alerts $top number optional parameter for get alerts $skip number optional parameter for get alerts $count boolean optional count value $expand string optional parameter for get alerts 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 id string unique identifier incidentid number unique identifier investigationid object unique identifier assignedto object output field assignedto severity string output field severity status string status value classification object output field classification determination object output field determination investigationstate string output field investigationstate detectionsource string output field detectionsource detectorid string unique identifier category string output field category threatfamilyname object name of the resource title string output field title description string output field description alertcreationtime string time value firsteventtime string time value lasteventtime string time value lastupdatetime string time value resolvedtime object time value machineid string unique identifier example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 12 52 40 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#alerts", "value" \[] } } ] get domain related alerts retrieve microsoft defender alerts specific to a domain by using the 'domain' path parameter for targeted results endpoint url /api/domains/{{domain}}/alerts method get input argument name type required description domain string required parameter for get domain related alerts 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 file name string name of the resource file string output field file example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 17 30 41 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#alerts", "value" \[] } } ] get domain related machines retrieve a list of machines associated with a specified domain in microsoft defender, requiring the 'domain' as a path parameter endpoint url /api/domains/{{domain}}/machines method get input argument name type required description domain string required parameter for get domain related machines 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 id string unique identifier mergedintomachineid object unique identifier ispotentialduplication boolean output field ispotentialduplication isexcluded boolean output field isexcluded exclusionreason object response reason phrase computerdnsname string name of the resource firstseen string output field firstseen lastseen string output field lastseen osplatform string output field osplatform osversion object output field osversion osprocessor string output field osprocessor version string output field version lastipaddress string output field lastipaddress lastexternalipaddress string output field lastexternalipaddress agentversion string output field agentversion osbuild number output field osbuild healthstatus string status value devicevalue string value for the parameter rbacgroupid number unique identifier rbacgroupname object name of the resource riskscore string score value example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 17 32 36 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#machines", "value" \[] } } ] get domain seen organization determines if microsoft defender has observed a specific domain within the organization, requiring the 'domain' as a path parameter endpoint url /api/domains/{{domain}} method get input argument name type required description domain string required parameter for get domain seen organization 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 example \[ { "status code" 404, "response headers" { "date" "thu, 04 may 2023 18 12 16 gmt", "content length" "0", "connection" "keep alive", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "not found", "response text" "" } ] get domain statistics retrieve statistical data for a specified domain from microsoft defender, utilizing the 'domain' path parameter endpoint url /api/domains/{{domain}}/stats method get input argument name type required description domain string required parameter for get domain statistics output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data host string output field host orgprevalence string output field orgprevalence orgfirstseen string output field orgfirstseen orglastseen string output field orglastseen organizationprevalence number output field organizationprevalence example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 17 35 52 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#microsoft windowsdefender ", "host" "google com", "orgprevalence" "1", "orgfirstseen" "2023 04 20t13 07 59 6924183z", "orglastseen" "2023 05 02t12 53 24 2750645z", "organizationprevalence" 1 } } ] get file information retrieve detailed information for a specific file in microsoft defender using the unique file identifier endpoint url /api/files/{{id}} method get input argument name type required description id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data sha1 string output field sha1 sha256 string output field sha256 md5 string output field md5 globalprevalence number output field globalprevalence globalfirstobserved string output field globalfirstobserved globallastobserved string output field globallastobserved size number output field size filetype object type of the resource ispefile boolean output field ispefile filepublisher object output field filepublisher fileproductname object name of the resource signer object output field signer issuer object output field issuer signerhash object output field signerhash isvalidcertificate object unique identifier determinationtype string type of the resource determinationvalue object value for the parameter example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 17 37 52 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#files/$entity", "sha1" "6532ec91d513acc05f43ee0aa3002599729fd3e1", "sha256" "d4447dffdbb2889b4b4e746b0bc882df1b854101614b0aa83953ef3cb66904cf", "md5" "7f05a371d2beffb3784fd2199f81d730", "globalprevalence" 10, "globalfirstobserved" "2018 05 07t14 05 18 4401316z", "globallastobserved" "2022 11 15t03 37 49 4593231z", "size" 391680, "filetype" null, "ispefile" true, "filepublisher" null, "fileproductname" null, "signer" null, "issuer" null, "signerhash" null } } ] get file related alerts retrieve microsoft defender alerts associated with a file using its unique identifier endpoint url /api/files/{{id}}/alerts method get input argument name type required description id string required unique identifier 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 file name string name of the resource file string output field file example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 17 39 45 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#alerts", "value" \[] } } ] get file related machines retrieve a list of machines associated with a specific file's unique id in microsoft defender to assess network impact endpoint url /api/files/{{id}}/machine method get input argument name type required description id string required unique identifier 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 example \[ { "status code" 404, "response headers" { "date" "thu, 04 may 2023 17 41 29 gmt", "content length" "0", "connection" "keep alive", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "not found", "response text" "" } ] get file statistics retrieve detailed statistics for a specific file in microsoft defender using the file's unique identifier endpoint url /api/files/{{id}}/stats method get input argument name type required description id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data sha1 string output field sha1 orgprevalence string output field orgprevalence organizationprevalence number output field organizationprevalence orgfirstseen object output field orgfirstseen orglastseen object output field orglastseen globalprevalence string output field globalprevalence globallyprevalence number output field globallyprevalence globalfirstobserved string output field globalfirstobserved globallastobserved string output field globallastobserved topfilenames array name of the resource file name string name of the resource file string output field file example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 17 42 51 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#microsoft windowsdefender ", "sha1" "6532ec91d513acc05f43ee0aa3002599729fd3e1", "orgprevalence" "0", "organizationprevalence" 0, "orgfirstseen" null, "orglastseen" null, "globalprevalence" "10", "globallyprevalence" 10, "globalfirstobserved" "2018 05 07t14 05 18 4401316z", "globallastobserved" "2022 11 15t03 37 49 4593231z", "topfilenames" \[] } } ] get incident retrieve a specific microsoft defender incident by its unique id endpoint url api/incidents/{{id}} method get input argument name type required description id number required incident id output parameter type description @odata context string response data incidentid number unique identifier incidenturi string unique identifier redirectincidentid object unique identifier incidentname string unique identifier createdtime string time value lastupdatetime string time value assignedto object output field assignedto classification string output field classification determination string output field determination status string status value severity string output field severity tags array output field tags file name string name of the resource file string output field file comments array output field comments file name string name of the resource file string output field file alerts array output field alerts alertid string unique identifier provideralertid string unique identifier incidentid number unique identifier servicesource string output field servicesource creationtime string time value lastupdatedtime string time value example \[ { "@odata context" "https //api security microsoft com/api/$metadata#incidents/$entity", "incidentid" 437, "incidenturi" "https //security microsoft com/incidents/437?tid=f5d73c4c bb3d 421b 8bee 424916a ", "redirectincidentid" null, "incidentname" "unfamiliar sign in properties involving one user", "createdtime" "2023 05 10t09 33 15 32z", "lastupdatetime" "2023 05 10t09 33 15 53z", "assignedto" null, "classification" "unknown", "determination" "notavailable", "status" "active", "severity" "high", "tags" \[], "comments" \[], "alerts" \[ {} ] } ] get incidents list retrieve and sort a list of incidents from microsoft defender to enhance cybersecurity response efforts endpoint url api/incidents method get input argument name type required description $filter string optional filters results on the lastupdatetime , createdtime , status , and assignedto properties for guidance on using filter , see https //learn microsoft com/en us/graph/filter query parameter https //learn microsoft com/en us/graph/filter query parameter $top number optional sets the page size of results $skip number optional indexes into a result set also used by some actions to implement paging and can be used together with top to manually page results output parameter type description @odata context string response data value array value for the parameter incidentid number unique identifier incidenturi string unique identifier redirectincidentid number unique identifier incidentname string unique identifier createdtime string time value lastupdatetime string time value assignedto object output field assignedto classification string output field classification determination string output field determination status string status value severity string output field severity tags array output field tags file name string name of the resource file string output field file comments array output field comments file name string name of the resource file string output field file alerts array output field alerts file name string name of the resource file string output field file @odata nextlink string response data example \[ { "@odata context" "https //api security microsoft com/api/$metadata#incidents", "value" \[ { "incidentid" 437, "incidenturi" "https //security microsoft com/incidents/437?tid=f5d73c4c bb3d 421b 8bee 424916a4acca", "redirectincidentid" null, "incidentname" "unfamiliar sign in properties involving one user", "createdtime" "2023 05 10t09 33 15 32z", "lastupdatetime" "2023 05 10t09 33 15 53z", "assignedto" null, "classification" "unknown", "determination" "notavailable", "status" "active", "severity" "high", "tags" \[], "comments" \[], "alerts" \[ { "alertid" "ad3ef58dc561c3234527be2d9ff82524a967a5fb1c", "provideralertid" "039e0aead168175b4945b6eb116391f45e0701ea8777529e1b9bce5992760803", "incidentid" 437, "servicesource" "aadidentityprotection", "creationtime" "2023 05 10t09 33 14 6226578z", "lastupdatedtime" "2023 05 10t09 33 16 1033333z", "resolvedtime" null, "firstactivity" "2023 05 10t09 29 24 2969531z", "lastactivity" "2023 05 10t09 29 24 2969531z", "title" "unfamiliar sign in properties", "description" "the following properties of this sign in are unfamiliar for the given user asn, browser, device, ip, location, easid, tenantipsubnet", "category" "initialaccess", "status" "new", "severity" "high", "investigationid" null, "investigationstate" "unsupportedalerttype", "classification" null, "determination" null, "detectionsource" "aad", "detectorid" "unfamiliarlocation", "assignedto" null, "actorname" null, "threatfamilyname" null, "mitretechniques" \[ "t1078", "t1078 004" ], "devices" \[], "entities" \[ { "entitytype" "user", "evidencecreationtime" "2023 05 10t09 33 14 89z", "verdict" "suspicious", "remediationstatus" "none", "accountname" "pov", "usersid" "s 1 12 1 1510799150 1340649529 3182594751 1539246002", "aaduserid" "5a0cf72e b039 4fe8 bf8a b2bdb207bf5b", "userprincipalname" "pov\@swimlaneintegrations onmicrosoft com" }, { "entitytype" "ip", "evidencecreationtime" "2023 05 10t09 33 14 89z", "verdict" "suspicious", "remediationstatus" "none", "ipaddress" "93 243 188 4" } ] } ] }, { "incidentid" 419, "incidenturi" "https //security microsoft com/incidents/419?tid=f5d73c4c bb3d 421b 8bee 424916a4acca", "redirectincidentid" null, "incidentname" "multiple threat families detected including ransomware on multiple endpoints", "createdtime" "2023 05 06t05 44 46 2466667z", "lastupdatetime" "2023 05 09t16 28 38 2933333z", "assignedto" null, "classification" "unknown", "determination" "notavailable", "status" "active", "severity" "high", "tags" \[], "comments" \[], "alerts" \[ { "alertid" "da0c2f2b80 48ee 4eb4 806a e756deb586fa 1", "provideralertid" "0c2f2b80 48ee 4eb4 806a e756deb586fa 1", "incidentid" 419, "servicesource" "microsoftdefenderforendpoint", "creationtime" "2023 05 06t05 44 45 3346482z", "lastupdatedtime" "2023 05 06t05 44 47 1866667z", "resolvedtime" null, "firstactivity" "2023 05 06t05 29 45 4250215z", "lastactivity" "2023 05 06t05 29 45 4250215z", "title" "'powerpuff' hacktool was prevented", "description" "readily available tools, such as hacking programs, can be used by unauthorized individuals to spy on users when used by attackers, these tools are often installed without authorization and used to compromise targeted machines \n\nthese tools are often used to collect personal information from browser records, record key presses, access email and instant messages, record voice and video conversations, and take screenshots \n\nthis detection might indicate that microsoft defender antivirus has stopped the tool from being installed and used effectively however, it is prudent to check the machine for the files and processes associated with the detected tool ", "category" "malware", "status" "new", "severity" "low", get indicators retrieves threat indicators from microsoft defender for pinpointing and analyzing malicious activities endpoint url /api/indicators method get input argument name type required description $filter string optional parameter for get indicators $select string optional parameter for get indicators $orderby string optional parameter for get indicators $top number optional parameter for get indicators $skip number optional parameter for get indicators $count boolean optional count value $expand string optional parameter for get indicators 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 id string unique identifier indicatorvalue string value for the parameter indicatortype string type of the resource action string output field action createdby string output field createdby severity string output field severity category number output field category application object output field application educateurl object url endpoint for the request bypassdurationhours object output field bypassdurationhours title string output field title description string output field description recommendedactions object output field recommendedactions creationtimedatetimeutc string output field creationtimedatetimeutc expirationtime object time value lastupdatetime string time value lastupdatedby string output field lastupdatedby rbacgroupnames array name of the resource file name string name of the resource file string output field file rbacgroupids array unique identifier example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 18 25 48 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#indicators", "value" \[] } } ] get investigation retrieves a specific microsoft defender investigation by id, applicable to both investigation and alert ids endpoint url /api/investigations/{{id}} method get input argument name type required description id string required the investigation id output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier starttime string time value endtime string time value state string output field state cancelledby string output field cancelledby statusdetails string status value machineid string unique identifier computerdnsname string name of the resource triggeringalertid string unique identifier example \[ { "status code" 200, "response headers" { "date" "fri, 07 feb 2025 06 30 27 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "mise correlation id" "08ce5338 e4be 4eab a417 d0a5cf40bfac", "odata version" "4 0", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "id" "63004", "starttime" "2020 01 06t13 05 15z", "endtime" "2020 01 06t13 05 15z", "state" "running", "cancelledby" "", "statusdetails" "", "machineid" "e828a0624ed33f919db541065190d2f75e50a071", "computerdnsname" "desktop test123", "triggeringalertid" "da637139127150012465 1011995739" } } ] get investigation collection package retrieve a microsoft defender investigation package for an entity using the unique id provided in path parameters endpoint url /api/machineactions/{{id}}/getpackageuri method get input argument name type required description id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase error object error message if any code string output field code message string response message target string output field target example \[ { "status code" 400, "response headers" { "date" "thu, 04 may 2023 17 45 50 gmt", "content type" "application/json; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "bad request", "json body" { "error" {} } } ] get ip related alerts retrieve alerts related to a specified ip address from microsoft defender, with the ip required as a path parameter endpoint url /api/ips/{{ip}}/alerts method get input argument name type required description ip string required parameter for get ip related alerts 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 file name string name of the resource file string output field file example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 17 46 57 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#alertentitysetname", "value" \[] } } ] get ip related machines retrieve a list of machines associated with a specified ip address in microsoft defender, requiring the 'ip' path parameter endpoint url /api/ips/{{ip}}/machines method get input argument name type required description ip string required parameter for get ip related machines 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 example \[ { "status code" 404, "response headers" { "date" "thu, 04 may 2023 17 50 09 gmt", "content length" "0", "connection" "keep alive", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "not found", "response text" "" } ] get ip seen organization determines if an ip address has been observed by microsoft defender within the organization, requiring an ip path parameter endpoint url /api/ips/{{ip}} method get input argument name type required description ip string required parameter for get ip seen organization 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 example \[ { "status code" 404, "response headers" { "date" "thu, 04 may 2023 18 11 35 gmt", "content length" "0", "connection" "keep alive", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "not found", "response text" "" } ] get ip statistics retrieve statistical data for a specified ip address from microsoft defender, requiring the ip as a path parameter endpoint url /api/ips/{{ip}}/stats method get input argument name type required description ip string required parameter for get ip statistics output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data ipaddress string output field ipaddress orgprevalence string output field orgprevalence organizationprevalence number output field organizationprevalence orgfirstseen object output field orgfirstseen orglastseen object output field orglastseen example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 17 49 46 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#microsoft windowsdefender ", "ipaddress" "192 168 1 1", "orgprevalence" "0", "organizationprevalence" 0, "orgfirstseen" null, "orglastseen" null } } ] get machine retrieves details for a specified machine from microsoft defender using the provided machine id endpoint url /api/machines/{{id}} method get input argument name type required description id string required unique identifier 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 mergedintomachineid object unique identifier ispotentialduplication boolean output field ispotentialduplication isexcluded boolean output field isexcluded exclusionreason object response reason phrase computerdnsname string name of the resource firstseen string output field firstseen lastseen string output field lastseen osplatform string output field osplatform osversion object output field osversion osprocessor string output field osprocessor version string output field version lastipaddress string output field lastipaddress lastexternalipaddress string output field lastexternalipaddress agentversion string output field agentversion osbuild number output field osbuild healthstatus string status value devicevalue string value for the parameter rbacgroupid number unique identifier rbacgroupname object name of the resource riskscore string score value exposurelevel string output field exposurelevel example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 17 56 56 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#machines/$entity", "id" "556b3952acb0bff29816d267822305781cc183ec", "mergedintomachineid" null, "ispotentialduplication" false, "isexcluded" false, "exclusionreason" null, "computerdnsname" "se pov desktop", "firstseen" "2023 04 19t13 27 53 1618923z", "lastseen" "2023 05 04t17 40 05 684607z", "osplatform" "windows10", "osversion" null, "osprocessor" "x64", "version" "21h2", "lastipaddress" "172 20 10 4", "lastexternalipaddress" "174 209 205 235" } } ] get machine action retrieve details of a specific machine action in microsoft defender using the unique action id endpoint url /api/machineactions/{{id}} method get input argument name type required description id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase error object error message if any code string output field code message string response message target string output field target example \[ { "status code" 400, "response headers" { "date" "thu, 04 may 2023 17 56 32 gmt", "content type" "application/json; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "bad request", "json body" { "error" {} } } ] get machine logon users retrieve a list of users who have logged onto a specific machine by using the machine id in microsoft defender endpoint url /api/machines/{{id}}/logonusers method get input argument name type required description id string required unique identifier 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 id string unique identifier accountname string name of the resource accountdomain string output field accountdomain accountsid object unique identifier firstseen string output field firstseen lastseen string output field lastseen mostprevalentmachineid object unique identifier leastprevalentmachineid object unique identifier logontypes string type of the resource logonmachinescount object count value isdomainadmin boolean output field isdomainadmin isonlynetworkuser object output field isonlynetworkuser example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 17 56 11 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#users", "value" \[] } } ] get machine related alerts retrieve microsoft defender alerts associated with a specific machine using its unique id endpoint url /api/machines/{{id}}/alerts method get input argument name type required description id string required unique identifier 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 id string unique identifier incidentid number unique identifier investigationid object unique identifier assignedto object output field assignedto severity string output field severity status string status value classification object output field classification determination object output field determination investigationstate string output field investigationstate detectionsource string output field detectionsource detectorid string unique identifier category string output field category threatfamilyname object name of the resource title string output field title description string output field description alertcreationtime string time value firsteventtime string time value lasteventtime string time value lastupdatetime string time value resolvedtime object time value machineid string unique identifier example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 17 55 47 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#alerts", "value" \[] } } ] get machines retrieve a list of machines registered with microsoft defender, detailing id, computer name, and os information endpoint url /api/machines method get input argument name type required description $filter string optional parameter for get machines $select string optional parameter for get machines $orderby string optional parameter for get machines $top number optional parameter for get machines $skip number optional parameter for get machines $count boolean optional count value $expand string optional parameter for get machines 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 id string unique identifier mergedintomachineid object unique identifier ispotentialduplication boolean output field ispotentialduplication isexcluded boolean output field isexcluded exclusionreason object response reason phrase computerdnsname string name of the resource firstseen string output field firstseen lastseen string output field lastseen osplatform string output field osplatform osversion object output field osversion osprocessor string output field osprocessor version string output field version lastipaddress string output field lastipaddress lastexternalipaddress string output field lastexternalipaddress agentversion string output field agentversion osbuild number output field osbuild healthstatus string status value devicevalue string value for the parameter rbacgroupid number unique identifier rbacgroupname object name of the resource riskscore string score value example \[ { "status code" 200, "response headers" { "date" "thu, 04 may 2023 18 25 21 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#machines", "value" \[] } } ] get user related alerts retrieve alerts associated with a specific user in microsoft defender using the unique 'user' identifier endpoint url /api/users/{{id}}/alerts method get input argument name type required description id string required the id is not the full upn, but only the user name (for example, to retrieve alerts for user1\@contoso com mailto\ user1\@contoso com use /api/users/user1/alerts) 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 id string unique identifier incidentid number unique identifier investigationid object unique identifier assignedto object output field assignedto severity string output field severity status string status value classification object output field classification determination object output field determination investigationstate string output field investigationstate detectionsource string output field detectionsource detectorid string unique identifier category string output field category threatfamilyname object name of the resource title string output field title description string output field description alertcreationtime string time value firsteventtime string time value lasteventtime string time value lastupdatetime string time value resolvedtime object time value machineid string unique identifier example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "@odata context" "string", "value" \[] } } ] get user related machines retrieve a list of machines associated with a specific user in microsoft defender using the user's unique identifier endpoint url /api/users/{{id}}/machines method get input argument name type required description id string required the id is not the full upn, but only the user name (for example, to retrieve machines for user1\@contoso com mailto\ user1\@contoso com use /api/users/user1/machines) 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 id string unique identifier computerdnsname string name of the resource firstseen string output field firstseen lastseen string output field lastseen osplatform string output field osplatform onboardingstatus string status value osprocessor string output field osprocessor version string output field version osbuild number output field osbuild lastipaddress string output field lastipaddress lastexternalipaddress string output field lastexternalipaddress healthstatus string status value rbacgroupname string name of the resource rbacgroupid string unique identifier riskscore string score value aaddeviceid object unique identifier machinetags array output field machinetags exposurelevel string output field exposurelevel devicevalue string value for the parameter ipaddresses array output field ipaddresses ipaddress string output field ipaddress example \[ { "status code" 200, "response headers" { "date" "mon, 26 may 2025 09 21 18 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "mise correlation id" "c6ccd948 929b 4073 be4d df4328ff6798", "odata version" "4 0", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#machines", "value" \[] } } ] get vulnerability by id retrieve detailed information for a specified vulnerability id from microsoft defender endpoint url /api/vulnerabilities/{{vulnerability id}} method get input argument name type required description vulnerability id string required vulnerability id 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 name string name of the resource description string output field description severity string output field severity cvssv3 number output field cvssv3 cvssvector string output field cvssvector exposedmachines number output field exposedmachines publishedon string output field publishedon updatedon string output field updatedon firstdetected object output field firstdetected publicexploit boolean output field publicexploit exploitverified boolean output field exploitverified exploitinkit boolean output field exploitinkit exploittypes array type of the resource file name string name of the resource file string output field file exploituris array output field exploituris file name string name of the resource file string output field file cvesupportability string output field cvesupportability tags array output field tags file name string name of the resource example \[ { "status code" 200, "response headers" { "date" "tue, 30 jul 2024 05 46 08 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#vulnerabilities/$entity", "id" "cve 2024 7163", "name" "cve 2024 7163", "description" "summary seacms 12 9 is vulnerable to cross site scripting (xss) due to improper ", "severity" "low", "cvssv3" 3 5, "cvssvector" "cvss 3 1/av\ n/ac\ l/pr\ l/ui\ r/s\ u/c\ n/i\ l/a\ n", "exposedmachines" 0, "publishedon" "2024 07 28t17 15 09 797z", "updatedon" "2024 07 29t14 12 08 783z", "firstdetected" null, "publicexploit" false, "exploitverified" false, "exploitinkit" false, "exploittypes" \[] } } ] import indicators submits or updates a batch of indicators to microsoft defender using a specified json body format endpoint url api/indicators/import method post input argument name type required description indicators array optional parameter for import indicators indicatorvalue string optional the value of the indicator entity indicatortype string optional the type of the indicator entity action string optional the action that is taken if the indicator is discovered in the organization application string optional the application associated with the indicator source string optional the source of the indicator expirationtime string optional the expiration time of the indicator sourcetype string optional user in case the indicator created by a user (for example, from the portal), aadapp in case it submitted using automated application via the api severity string optional the severity of the indicator the severity of the indicator possible values are informational, low, medium, and high title string optional the title of the indicator description string optional the description of the indicator recommendedactions string optional the recommended actions for the indicator rbacgroupnames array optional rbac device group names where the indicator is exposed and active empty list in case it exposed to all devices output parameter type description status code number http status code of the response reason string response reason phrase value array value for the parameter id string unique identifier indicator string output field indicator isfailed boolean output field isfailed failurereason object response reason phrase example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "value" \[] } } ] invoke collection investigation package initiates the collection of an investigation package from a machine using its id in microsoft defender endpoint url /api/machines/{{id}}/collectinvestigationpackage method post input argument name type required description id string required unique identifier comment string optional parameter for invoke collection investigation package 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 example \[ { "status code" 405, "response headers" { "date" "thu, 04 may 2023 18 07 32 gmt", "content length" "0", "connection" "keep alive", "allow" "post", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "method not allowed", "response text" "" } ] isolate machine initiates isolation of a specified machine in microsoft defender using its unique id and requires a comment endpoint url /api/machines/{{id}}/isolate method post input argument name type required description id string required unique identifier comment string required comment to associate with the action isolationtype string optional type of the isolation allowed values are full or selective isolationtype controls the type of isolation to perform and can be one of the following full full isolation selective restrict only limited set of applications from accessing the network 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 example \[ { "status code" 405, "response headers" { "date" "thu, 04 may 2023 18 07 32 gmt", "content length" "0", "connection" "keep alive", "allow" "post", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "method not allowed", "response text" "" } ] list all remediation activities retrieve comprehensive details on all remediation activities, including statuses and identifiers, within microsoft defender endpoint url /api/remediationtasks method get input argument name type required description $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 $top number optional sets the page size of results top with max value of 10,000 $filter string optional filter on createdon and status properties 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 id string unique identifier title string output field title createdon string output field createdon requesterid string unique identifier requesteremail string output field requesteremail status string status value statuslastmodifiedon string status value description string output field description relatedcomponent string output field relatedcomponent targetdevices number output field targetdevices rbacgroupnames array name of the resource fixeddevices number output field fixeddevices requesternotes string output field requesternotes dueon string output field dueon category string output field category productivityimpactremediationtype string type of the resource priority string output field priority completionmethod string http method to use completerid string unique identifier completeremail string output field completeremail scid string unique identifier example \[ { "status code" 200, "response headers" { "date" "mon, 10 feb 2025 05 20 10 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "mise correlation id" "245dc196 fb84 44dd adc4 d91b3abec8da", "odata version" "4 0", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter windows com/api/$metadata#remediationtasks", "value" \[] } } ] list devices by vulnerability retrieves a list of devices affected by a specified vulnerability in microsoft defender using the provided vulnerability id endpoint url /api/vulnerabilities/{{vulnerability id}}/machinereferences method get input argument name type required description vulnerability id string required vulnerability id 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 id string unique identifier computerdnsname string name of the resource osplatform string output field osplatform rbacgroupname string name of the resource example \[ { "status code" 200, "response headers" { "date" "tue, 30 jul 2024 05 49 03 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#collection(microsoft wind ", "@odata count" 0, "value" \[] } } ] list vulnerabilities retrieve a comprehensive list of vulnerabilities identified by microsoft defender for proactive threat mitigation endpoint url /api/vulnerabilities method get input argument name type required description $filter string optional filter the vulnerabilities using id, name, description, cvssv3, publishedon, severity, and updatedon properties $top number optional the number of items in the queried collection to be included in the response max value of 8,000 $skip number optional the number of items in the queried collection that are to be skipped and not included in the response 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 id string unique identifier name string name of the resource description string output field description severity string output field severity cvssv3 number output field cvssv3 cvssvector string output field cvssvector exposedmachines number output field exposedmachines publishedon string output field publishedon updatedon string output field updatedon firstdetected object output field firstdetected publicexploit boolean output field publicexploit exploitverified boolean output field exploitverified exploitinkit boolean output field exploitinkit exploittypes array type of the resource file name string name of the resource file string output field file exploituris array output field exploituris file name string name of the resource file string output field file cvesupportability string output field cvesupportability example \[ { "status code" 200, "response headers" { "date" "tue, 30 jul 2024 05 38 55 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#vulnerabilities", "@odata count" 8000, "value" \[], "@odata nextlink" "https //api securitycenter microsoft com/api/vulnerabilities?$skip=8000" } } ] list vulnerabilities by machine and software retrieve a categorized list of vulnerabilities by machine and software from microsoft defender endpoint url /api/vulnerabilities/machinesvulnerabilities method get input argument name type required description $filter string optional filter the vulnerabilities using id, cveid, machineid, fixingkbid, productname, productversion, severity, and productvendor properties $top number optional the number of items in the queried collection to be included in the response max value of 10,000 $skip number optional the number of items in the queried collection that are to be skipped and not included in the response 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 id string unique identifier cveid string unique identifier machineid string unique identifier fixingkbid string unique identifier productname string name of the resource productvendor string output field productvendor productversion string output field productversion severity string output field severity example \[ { "status code" 200, "response headers" { "date" "tue, 30 jul 2024 05 42 20 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#collection(microsoft wind ", "@odata count" 0, "value" \[] } } ] offboard machine initiates the offboarding of a machine from microsoft defender using the provided unique machine id endpoint url /api/machines/{{id}}/offboard method post input argument name type required description id string required unique identifier comment string optional parameter for offboard machine 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 example \[ { "status code" 405, "response headers" { "date" "thu, 04 may 2023 18 07 32 gmt", "content length" "0", "connection" "keep alive", "allow" "post", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "method not allowed", "response text" "" } ] query advanced hunting executes an advanced hunting query in microsoft defender to identify threats, requiring a 'query' parameter endpoint url /api/advancedhunting/run method post input argument name type required description query string required the query to run output parameter type description status code number http status code of the response reason string response reason phrase stats object output field stats executiontime number time value resource usage object output field resource usage cache object output field cache memory object output field memory disk object output field disk cpu object output field cpu user string output field user kernel string output field kernel total cpu string output field total cpu memory object output field memory peak per node number output field peak per node dataset statistics array response data table row count number count value table size number output field table size schema array output field schema name string name of the resource type string type of the resource results array result of the operation file name string name of the resource file string output field file example \[ { "status code" 200, "response headers" { "date" "thu, 05 sep 2024 07 29 53 gmt", "content type" "application/json; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "stats" {}, "schema" \[], "results" \[] } } ] remove app restriction removes an existing application restriction in microsoft defender using the specified unique identifier (id) endpoint url /api/machines/{{id}}/unrestrictcodeexecution method post input argument name type required description id string required unique identifier comment string optional parameter for remove app restriction isolationtype string optional type of the resource 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 example \[ { "status code" 405, "response headers" { "date" "thu, 04 may 2023 18 07 32 gmt", "content length" "0", "connection" "keep alive", "allow" "post", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "method not allowed", "response text" "" } ] restrict app execution initiates an application execution restriction in microsoft defender using a specific entity id endpoint url /api/machines/{{id}}/restrictcodeexecution method post input argument name type required description id string required unique identifier comment string optional parameter for restrict app execution 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 example \[ { "status code" 405, "response headers" { "date" "thu, 04 may 2023 18 07 32 gmt", "content length" "0", "connection" "keep alive", "allow" "post", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "method not allowed", "response text" "" } ] run antivirus scan initiates a microsoft defender antivirus scan on a specified entity by machine id, allowing customization of the comment and scan type endpoint url /api/machines/{{id}}/runantivirusscan method post input argument name type required description id string required unique identifier comment string required comment to associate with the action scantype string required defines the type of the scan possible values are quick or full quick perform quick scan on the device full perform full scan on the device output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier type string type of the resource scope string output field scope requestor string output field requestor requestorcomment string output field requestorcomment status string status value machineid string unique identifier computerdnsname string name of the resource creationdatetimeutc string output field creationdatetimeutc lastupdatedatetimeutc string output field lastupdatedatetimeutc relatedfileinfo object output field relatedfileinfo example \[ { "status code" 201, "response headers" { "date" "fri, 13 dec 2024 07 45 13 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "id" "5382f7ea 7557 4ab7 9782 d50480024a4e", "type" "isolate", "scope" "selective", "requestor" "analyst\@testprd onmicrosoft com", "requestorcomment" "test for docs", "status" "succeeded", "machineid" "7b1f4967d9728e5aa3c06a9e617a22a4a5a17378", "computerdnsname" "desktop test", "creationdatetimeutc" "2019 01 02t14 39 38 2262283z", "lastupdatedatetimeutc" "2019 01 02t14 40 44 6596267z", "relatedfileinfo" null } } ] run query executes a custom query in microsoft defender and returns the results a 'query' must be specified in the json body endpoint url /api/advancedqueries/run method post input argument name type required description query string required parameter for run query output parameter type description status code number http status code of the response reason string response reason phrase error object error message if any code string output field code message string response message target string output field target example \[ { "status code" 400, "response headers" { "date" "thu, 04 may 2023 18 35 41 gmt", "content type" "application/json; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "bad request", "json body" { "error" {} } } ] start investigation initiates an automated investigation on a device in microsoft defender using the specified id and comment endpoint url /api/machines/{{id}}/startinvestigation method post input argument name type required description id string required the machine id comment string required comment to associate with the action output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier starttime string time value endtime string time value state string output field state cancelledby string output field cancelledby statusdetails string status value machineid string unique identifier computerdnsname string name of the resource triggeringalertid string unique identifier example \[ { "status code" 201, "response headers" { "date" "fri, 07 feb 2025 06 30 27 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "mise correlation id" "08ce5338 e4be 4eab a417 d0a5cf40bfac", "odata version" "4 0", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "id" "63004", "starttime" "2020 01 06t13 05 15z", "endtime" "2020 01 06t13 05 15z", "state" "running", "cancelledby" "", "statusdetails" "", "machineid" "e828a0624ed33f919db541065190d2f75e50a071", "computerdnsname" "desktop test123", "triggeringalertid" "da637139127150012465 1011995739" } } ] stop and quarantine file initiates the stoppage and quarantine of a file using its 'id' to mitigate threats in microsoft defender endpoint url /api/machines/{{id}}/stopandquarantinefile method post input argument name type required description id string required unique identifier comment string optional parameter for stop and quarantine file sha1 string optional parameter for stop and quarantine file output parameter type description status code number http status code of the response reason string response reason phrase error object error message if any code string output field code message string response message target string output field target example \[ { "status code" 400, "response headers" { "date" "thu, 04 may 2023 18 35 41 gmt", "content type" "application/json; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "bad request", "json body" { "error" {} } } ] submit indicator enhance tracking, alerting, and threat detection with a new indicator submission to microsoft defender endpoint url /api/indicators method post input argument name type required description indicatorvalue string optional value for the parameter indicatortype string optional type of the resource action string optional parameter for submit indicator title string optional parameter for submit indicator expirationtime string optional time value severity string optional parameter for submit indicator description string optional parameter for submit indicator recommendedactions string optional parameter for submit indicator 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 example \[ { "status code" 405, "response headers" { "date" "thu, 04 may 2023 18 07 32 gmt", "content length" "0", "connection" "keep alive", "allow" "post", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "method not allowed", "response text" "" } ] unisolate machine reverses the isolation of a specified machine in microsoft defender using the provided machine id endpoint url /api/machines/{{id}}/unisolate method post input argument name type required description id string required unique identifier comment string optional parameter for unisolate machine isolationtype string optional type of the resource 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 example \[ { "status code" 405, "response headers" { "date" "thu, 04 may 2023 18 07 32 gmt", "content length" "0", "connection" "keep alive", "allow" "post", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "method not allowed", "response text" "" } ] update alert updates an existing alert in microsoft defender by specifying the unique alert id endpoint url /api/alerts/{{id}} method patch input argument name type required description id string required unique identifier status string optional status value assignedto string optional parameter for update alert classification string optional parameter for update alert determination string optional parameter for update alert 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 example \[ { "status code" 405, "response headers" { "date" "thu, 04 may 2023 18 07 32 gmt", "content length" "0", "connection" "keep alive", "allow" "post", "strict transport security" "max age=15724800; includesubdomains" }, "reason" "method not allowed", "response text" "" } ] update incident by id updates an existing incident's details in microsoft defender, including status, determination, and classification, using the incident id endpoint url api/incidents/{{id}} method patch input argument name type required description id number required incident id status string optional specifies the current status of the incident assignedto string optional owner of the incident classification string optional specification of the incident determination string optional specifies the determination of the incident tags array optional list of incident tags comment string optional comment to be added to the incident output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data incidentid number unique identifier incidenturi string unique identifier redirectincidentid object unique identifier incidentname string unique identifier createdtime string time value lastupdatetime string time value assignedto object output field assignedto classification string output field classification determination string output field determination status string status value severity string output field severity tags array output field tags file name string name of the resource file string output field file comments array output field comments file name string name of the resource file string output field file alerts array output field alerts alertid string unique identifier provideralertid string unique identifier incidentid number unique identifier servicesource string output field servicesource example \[ { "status code" 200, "response headers" { "date" "thu, 05 sep 2024 07 20 44 gmt", "content type" "application/json; odata metadata=minimal; odata streaming=true; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "content encoding" "deflate", "vary" "accept encoding", "odata version" "4 0", "strict transport security" "max age=31536000; includesubdomains" }, "reason" "ok", "json body" { "@odata context" "https //api securitycenter microsoft com/api/$metadata#incidents/$entity", "incidentid" 552, "incidenturi" "https //security microsoft com/incidents/552?tid=f5d73c4c bb3d 421b 8bee 424916a ", "redirectincidentid" null, "incidentname" "email messages containing malicious file removed after delivery\u200b", "createdtime" "2024 08 30t08 55 32 21z", "lastupdatetime" "2024 09 05t07 20 44 9089383z", "assignedto" null, "classification" "unknown", "determination" "notavailable", "status" "resolved", "severity" "informational", "tags" \[], "comments" \[], "alerts" \[] } } ] response headers header description example allow http response header allow post connection http response header connection keep alive content encoding http response header content encoding deflate content length the length of the response body in bytes 0 content type the media type of the resource application/json; charset=utf 8 date the date and time at which the message was originated thu, 04 may 2023 17 35 52 gmt mise correlation id http response header mise correlation id 08ce5338 e4be 4eab a417 d0a5cf40bfac odata version http response header odata version 4 0 strict transport security http response header strict transport security max age=31536000; includesubdomains transfer encoding http response header transfer encoding chunked vary http response header vary accept encoding notes use these scopes in the asset as per the action requirement https //api securitycenter microsoft com/ default https //api securitycenter microsoft com/ defaulthttps //security microsoft com/mtp/ default https //security microsoft com/mtp/ default whenever you are using a particular action, please make sure you visit the relevant api docs and provide the required permissions needed in your application for that action to run without issues