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/ , 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 (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 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 notes use these scopes in the asset as per the action requirement https //api securitycenter microsoft com/ 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 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 https //docs microsoft com/en us/windows/security/threat protection/microsoft defender atp/run advanced query api additionally, microsoft has provided example queries 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 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 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/ 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 path parameters machineactionid string required the machine action id comment string optional comment to associate with the cancellation action input example {"json body" {"comment" "machine action was canceled by automation"},"path parameters" {"machineactionid" "988cc94e 7a8f 4b28 ab65 54970c5d5018"}} 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 output 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 d50480024a 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 optional id of the device on which the event was identified severity string optional severity of the alert title string optional title for the alert description string optional description of the alert recommendedaction string optional security officer needs to take this action when analyzing the alert eventtime string optional the precise time of the event as string, as obtained from advanced hunting reportid string optional the reportid of the event, as obtained from advanced hunting category string optional category of the alert input example {"json body" {"machineid" "1e5bc9d7e413ddd7902c2932e418702b84d0cc07","severity" "low","title" "low reputation arbitrary code executed by signed executable","description" "binaries signed by microsoft can be used to run low reputation arbitrary code this technique hides the execution of malicious code within a trusted process as a result, the trusted process might exhibit suspicious behaviors, such as opening a listening port or connecting to a command and control (c\&c) server ","recommendedaction" "nothing","eventtime" "2018 08 03t16 45 21 7115183z","reportid" "20776","category" "exploit"}} 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 output 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" "windows 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 data aud string response data data iss string response data data iat number response data data nbf number response data data exp number response data data aio string response data data appid string response data data appidacr string response data data idp string response data data oid string response data data rh string response data data sub string response data data tenant region scope string response data data tid string response data data uti string response data data ver string response data output 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", 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 path parameters id string required parameters for the delete indicator by id action input example {"path parameters" {"id" "995"}} 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 {"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 path parameters id string required parameters for the get alert action input example {"path parameters" {"id" "ar638180599315648136 73827727"}} 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 output 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" "ar6381 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 path parameters id string required parameters for the get alert domains action input example {"path parameters" {"id" "ar638180599315648136 73827727"}} 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 {"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 path parameters id string required parameters for the get alert ips action input example {"path parameters" {"id" "ar638180599315648136 73827727"}} 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 {"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 path parameters id string required parameters for the get alert machine information action input example {"path parameters" {"id" "ar638180599315648136 73827727"}} 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 output 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" "556b 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 path parameters id string required parameters for the get alert user information action input example {"path parameters" {"id" "ar638180599315648136 73827727"}} 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 target string error message if any output 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" {"code" "resourcenotfound","message" "there is no user related to alert ar638180599315648136 73827727","target" "|f712eef2 447d37a1beaf6d2b "}}} 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 parameters $filter string optional parameters for the get alerts action parameters $select string optional parameters for the get alerts action parameters $orderby string optional parameters for the get alerts action parameters $top number optional parameters for the get alerts action parameters $skip number optional parameters for the get alerts action parameters $count boolean optional parameters for the get alerts action parameters $expand string optional parameters for the get alerts action input example {"parameters" {"$filter" "type eq 'microsoft compute/virtualmachines' and name eq 'myvm'","$select" "property1,property2","$orderby" "property name asc","$top" 10,"$skip" 0,"$count"\ true,"$expand" "related entity name"}} 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 incidentid number unique identifier value investigationid object unique identifier value assignedto object value for the parameter value severity string value for the parameter value status string status value value classification object value for the parameter value determination object value for the parameter value investigationstate string value for the parameter value detectionsource string value for the parameter value detectorid string unique identifier value category string value for the parameter value threatfamilyname object name of the resource value title string value for the parameter value description string value for the parameter value alertcreationtime string value for the parameter value firsteventtime string value for the parameter value lasteventtime string value for the parameter value lastupdatetime string value for the parameter value resolvedtime object value for the parameter value machineid string unique identifier output 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" \[{"id" "ar63 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 path parameters domain string required parameters for the get domain related alerts action input example {"path parameters" {"domain" "google com"}} 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 {"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 path parameters domain string required parameters for the get domain related machines action input example {"path parameters" {"domain" "google com"}} 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 mergedintomachineid object unique identifier value ispotentialduplication boolean value for the parameter value isexcluded boolean value for the parameter value exclusionreason object value for the parameter value computerdnsname string name of the resource value firstseen string value for the parameter value lastseen string value for the parameter value osplatform string value for the parameter value osversion object value for the parameter value osprocessor string value for the parameter value version string value for the parameter value lastipaddress string value for the parameter value lastexternalipaddress string value for the parameter value agentversion string value for the parameter value osbuild number value for the parameter value healthstatus string status value value devicevalue string value for the parameter value rbacgroupid number unique identifier value rbacgroupname object name of the resource value riskscore string value for the parameter output 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 path parameters domain string required parameters for the get domain seen organization action input example {"path parameters" {"domain" "facebook net"}} 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 {"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 path parameters domain string required parameters for the get domain statistics action input example {"path parameters" {"domain" "google com"}} 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 output 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 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 path parameters id string required parameters for the get file information action input example {"path parameters" {"id" "6532ec91d513acc05f43ee0aa3002599729fd3e1"}} 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 output 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" "6532e 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 path parameters id string required parameters for the get file related alerts action input example {"path parameters" {"id" "6532ec91d513acc05f43ee0aa3002599729fd3e1"}} 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 {"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 path parameters id string required parameters for the get file related machines action input example {"path parameters" {"id" "6532ec91d513acc05f43ee0aa3002599729fd3e1"}} 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 {"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 path parameters id string required parameters for the get file statistics action input example {"path parameters" {"id" "6532ec91d513acc05f43ee0aa3002599729fd3e1"}} 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 topfilenames file name string name of the resource topfilenames file string name of the resource output 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 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 path parameters id number required incident id input example {"path parameters" {"id" 437}} 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 tags file name string name of the resource tags file string output field tags file comments array output field comments comments file name string name of the resource comments file string output field comments file alerts array output field alerts alerts alertid string unique identifier alerts provideralertid string unique identifier alerts incidentid number unique identifier alerts servicesource string output field alerts servicesource alerts creationtime string time value alerts lastupdatedtime string time value output 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" \[] 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 parameters $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 parameters $top number optional sets the page size of results parameters $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 input example {"parameters" {"$filter" "string","$top" 123,"$skip" 123}} output parameter type description @odata context string response data value array value for the parameter value incidentid number unique identifier value incidenturi string unique identifier value redirectincidentid number unique identifier value incidentname string unique identifier value createdtime string value for the parameter value lastupdatetime string value for the parameter value assignedto object 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 tags array value for the parameter value tags file name string name of the resource value tags file string value for the parameter value comments array value for the parameter value comments file name string name of the resource value comments file string value for the parameter value alerts array value for the parameter value alerts file name string name of the resource value alerts file string value for the parameter @odata nextlink string response data output 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 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 parameters $filter string optional parameters for the get indicators action parameters $select string optional parameters for the get indicators action parameters $orderby string optional parameters for the get indicators action parameters $top number optional parameters for the get indicators action parameters $skip number optional parameters for the get indicators action parameters $count boolean optional parameters for the get indicators action parameters $expand string optional parameters for the get indicators action input example {"parameters" {"$filter" "type eq 'microsoft compute/virtualmachines' and name eq 'myvm'","$select" "property1,property2","$orderby" "property name asc","$top" 10,"$skip" 0,"$count"\ true,"$expand" "related entity name"}} 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 indicatorvalue string value for the parameter value indicatortype string type of the resource value action string value for the parameter value createdby string value for the parameter value severity string value for the parameter value category number value for the parameter value application object value for the parameter value educateurl object url endpoint for the request value bypassdurationhours object value for the parameter value title string value for the parameter value description string value for the parameter value recommendedactions object value for the parameter value creationtimedatetimeutc string value for the parameter value expirationtime object value for the parameter value lastupdatetime string value for the parameter value lastupdatedby string value for the parameter value rbacgroupnames array name of the resource value rbacgroupnames file name string name of the resource value rbacgroupnames file string name of the resource value rbacgroupids array unique identifier output 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" \[{"id" " 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 path parameters id string required the investigation id input example {"path parameters" {"id" "63017"}} 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 output 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 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 path parameters id string required parameters for the get investigation collection package action input example {"path parameters" {"id" "5b1c0caf 14fe 41e1 83bf 118b1a9e391d"}} 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 target string error message if any output 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" {"code" "invalidinput","message" "provided guid is not a valid id for a collectinvestigationpackage action","target" "|76dce355 471ae6d819782413 "}}} 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 path parameters ip string required parameters for the get ip related alerts action input example {"path parameters" {"ip" "192 168 1 1"}} 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 {"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 path parameters ip string required parameters for the get ip related machines action input example {"path parameters" {"ip" "192 168 1 1"}} 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 {"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 path parameters ip string required parameters for the get ip seen organization action input example {"path parameters" {"ip" "192 168 1 1"}} 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 {"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 path parameters ip string required parameters for the get ip statistics action input example {"path parameters" {"ip" "192 168 1 1"}} 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 output 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 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 path parameters id string required parameters for the get machine action input example {"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 output 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" "556b 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 path parameters id string required parameters for the get machine action action input example {"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 target string error message if any output 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" {"code" "badrequest","message" "the key value (556b3952acb0bff29816d267822305781cc183ec) from request is not val ","target" "|b1838e63 40a6640ddd2719ac "}}} 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 path parameters id string required parameters for the get machine logon users action input example {"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 accountname string name of the resource value accountdomain string value for the parameter value accountsid object unique identifier value firstseen string value for the parameter value lastseen string value for the parameter value mostprevalentmachineid object unique identifier value leastprevalentmachineid object unique identifier value logontypes string type of the resource value logonmachinescount object value for the parameter value isdomainadmin boolean value for the parameter value isonlynetworkuser object value for the parameter output 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 path parameters id string required parameters for the get machine related alerts action input example {"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 incidentid number unique identifier value investigationid object unique identifier value assignedto object value for the parameter value severity string value for the parameter value status string status value value classification object value for the parameter value determination object value for the parameter value investigationstate string value for the parameter value detectionsource string value for the parameter value detectorid string unique identifier value category string value for the parameter value threatfamilyname object name of the resource value title string value for the parameter value description string value for the parameter value alertcreationtime string value for the parameter value firsteventtime string value for the parameter value lasteventtime string value for the parameter value lastupdatetime string value for the parameter value resolvedtime object value for the parameter value machineid string unique identifier output 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" \[{"id" "ar63 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 parameters $filter string optional parameters for the get machines action parameters $select string optional parameters for the get machines action parameters $orderby string optional parameters for the get machines action parameters $top number optional parameters for the get machines action parameters $skip number optional parameters for the get machines action parameters $count boolean optional parameters for the get machines action parameters $expand string optional parameters for the get machines action input example {"parameters" {"$filter" "type eq 'microsoft compute/virtualmachines' and name eq 'myvm'","$select" "property1,property2","$orderby" "property name asc","$top" 10,"$skip" 0,"$count"\ true,"$expand" "related entity name"}} 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 mergedintomachineid object unique identifier value ispotentialduplication boolean value for the parameter value isexcluded boolean value for the parameter value exclusionreason object value for the parameter value computerdnsname string name of the resource value firstseen string value for the parameter value lastseen string value for the parameter value osplatform string value for the parameter value osversion object value for the parameter value osprocessor string value for the parameter value version string value for the parameter value lastipaddress string value for the parameter value lastexternalipaddress string value for the parameter value agentversion string value for the parameter value osbuild number value for the parameter value healthstatus string status value value devicevalue string value for the parameter value rbacgroupid number unique identifier value rbacgroupname object name of the resource value riskscore string value for the parameter output 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 path parameters id string required the id is not the full upn, but only the user name (for example, to retrieve alerts for mailto\ user1\@contoso com use /api/users/user1/alerts) input example {"path parameters" {"id" "chris phillips"}} 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 incidentid number unique identifier value investigationid object unique identifier value assignedto object value for the parameter value severity string value for the parameter value status string status value value classification object value for the parameter value determination object value for the parameter value investigationstate string value for the parameter value detectionsource string value for the parameter value detectorid string unique identifier value category string value for the parameter value threatfamilyname object name of the resource value title string value for the parameter value description string value for the parameter value alertcreationtime string value for the parameter value firsteventtime string value for the parameter value lasteventtime string value for the parameter value lastupdatetime string value for the parameter value resolvedtime object value for the parameter value machineid string unique identifier output example {"@odata context" "string","value" \[{"id" "12345678 1234 1234 1234 123456789abc","incidentid" 123,"investigationid" {},"assignedto" {},"severity" "string","status" "active","classification" {},"determination" {},"investigationstate" "string","detectionsource" "string","detectorid" "string","category" "string","threatfamilyname" {},"title" "string","description" "string"}]} 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 path parameters id string required the id is not the full upn, but only the user name (for example, to retrieve machines for mailto\ user1\@contoso com use /api/users/user1/machines) input example {"path parameters" {"id" "chris phillips"}} 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 computerdnsname string name of the resource value firstseen string value for the parameter value lastseen string value for the parameter value osplatform string value for the parameter value onboardingstatus string status value value osprocessor string value for the parameter value version string value for the parameter value osbuild number value for the parameter value lastipaddress string value for the parameter value lastexternalipaddress string value for the parameter value healthstatus string status value value rbacgroupname string name of the resource value rbacgroupid string unique identifier value riskscore string value for the parameter value aaddeviceid object unique identifier value machinetags array value for the parameter value exposurelevel string value for the parameter value devicevalue string value for the parameter value ipaddresses array value for the parameter value ipaddresses ipaddress string value for the parameter output 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 securityce 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 path parameters vulnerability id string required vulnerability id input example {"path parameters" {"vulnerability id" "cve 2024 7163"}} 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 exploittypes file name string name of the resource exploittypes file string type of the resource exploituris array output field exploituris exploituris file name string name of the resource exploituris file string output field exploituris file cvesupportability string output field cvesupportability tags array output field tags tags file name string name of the resource output 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 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 indicators indicatorvalue string optional the value of the indicator entity indicators indicatortype string optional the type of the indicator entity indicators action string optional the action that is taken if the indicator is discovered in the organization indicators application string optional the application associated with the indicator indicators source string optional the source of the indicator indicators expirationtime string optional the expiration time of the indicator indicators 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 indicators severity string optional the severity of the indicator the severity of the indicator possible values are informational, low, medium, and high indicators title string optional the title of the indicator indicators description string optional the description of the indicator indicators recommendedactions string optional the recommended actions for the indicator indicators rbacgroupnames array optional rbac device group names where the indicator is exposed and active empty list in case it exposed to all devices input example {"json body" {"indicators" \[{"indicatorvalue" "881c0f10c75e64ec39d257a131fcd531f47dd2cff2070ae94baa347d375126fd","indicatortype" "filesha256","action" "alertandblock","application" "windowsdefenderatp","source" "user\@contoso onmicrosoft com","expirationtime" "2021 12 12t00 00 00z","sourcetype" "user","severity" "informational","title" "michael test","description" "test","recommendedactions" "nothing","rbacgroupnames" \["team1"]}]}} 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 indicator string value for the parameter value isfailed boolean value for the parameter value failurereason object value for the parameter output 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 path parameters id string required parameters for the invoke collection investigation package action comment string optional parameter for invoke collection investigation package input example {"json body" {"comment" "a comment","isolationtype" "isolationtype"},"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 {"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 path parameters id string required parameters for the isolate machine action comment string optional 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 input example {"json body" {"comment" "isolate machine due to alert 1234","isolationtype" "full"},"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 {"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 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 top with max value of 10,000 parameters $filter string optional filter on createdon and status properties input example {"parameters" {"$skip" 1,"$top" 1,"$filter" "createdon gt 2018 08 01z"}} 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 title string value for the parameter value createdon string value for the parameter value requesterid string unique identifier value requesteremail string value for the parameter value status string status value value statuslastmodifiedon string status value value description string value for the parameter value relatedcomponent string value for the parameter value targetdevices number value for the parameter value rbacgroupnames array name of the resource value fixeddevices number value for the parameter value requesternotes string value for the parameter value dueon string value for the parameter value category string value for the parameter value productivityimpactremediationtype string type of the resource value priority string value for the parameter value completionmethod string http method to use value completerid string unique identifier value completeremail string value for the parameter value scid string unique identifier output 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 securityce 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 path parameters vulnerability id string required vulnerability id input example {"path parameters" {"vulnerability id" "cve 2024 7163"}} 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 id string unique identifier value computerdnsname string name of the resource value osplatform string value for the parameter value rbacgroupname string name of the resource output 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 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 parameters $filter string optional filter the vulnerabilities using id, name, description, cvssv3, publishedon, severity, and updatedon properties parameters $top number optional the number of items in the queried collection to be included in the response max value of 8,000 parameters $skip number optional the number of items in the queried collection that are to be skipped and not included in the response input example {"parameters" {"$filter" "publishedon+ge+2019 11 22t00 00 00z","$top" 10,"$skip" 15}} 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 id string unique identifier value name string name of the resource value description string value for the parameter value severity string value for the parameter value cvssv3 number value for the parameter value cvssvector string value for the parameter value exposedmachines number value for the parameter value publishedon string value for the parameter value updatedon string value for the parameter value firstdetected object value for the parameter value publicexploit boolean value for the parameter value exploitverified boolean value for the parameter value exploitinkit boolean value for the parameter value exploittypes array type of the resource value exploittypes file name string name of the resource value exploittypes file string type of the resource value exploituris array value for the parameter value exploituris file name string name of the resource value exploituris file string value for the parameter value cvesupportability string value for the parameter output 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 cou 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 parameters $filter string optional filter the vulnerabilities using id, cveid, machineid, fixingkbid, productname, productversion, severity, and productvendor properties parameters $top number optional the number of items in the queried collection to be included in the response max value of 10,000 parameters $skip number optional the number of items in the queried collection that are to be skipped and not included in the response input example {"parameters" {"$filter" "publishedon+ge+2019 11 22t00 00 00z","$top" 10,"$skip" 15}} 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 id string unique identifier value cveid string unique identifier value machineid string unique identifier value fixingkbid string unique identifier value productname string name of the resource value productvendor string value for the parameter value productversion string value for the parameter value severity string value for the parameter output 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 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 path parameters id string required parameters for the offboard machine action comment string optional parameter for offboard machine input example {"json body" {"comment" "a comment"},"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 {"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 optional the query to run input example {"json body" {"query" "deviceprocessevents | where initiatingprocessfilename = \\"powershell exe\\" | project timestamp, filename, initiatingprocessfilename | order by timestamp desc | limit 2"}} output parameter type description status code number http status code of the response reason string response reason phrase stats object output field stats stats executiontime number time value stats resource usage object output field stats resource usage stats resource usage cache object output field stats resource usage cache stats resource usage cache memory object output field stats resource usage cache memory stats resource usage cache disk object output field stats resource usage cache disk stats resource usage cpu object output field stats resource usage cpu stats resource usage cpu user string output field stats resource usage cpu user stats resource usage cpu kernel string output field stats resource usage cpu kernel stats resource usage cpu total cpu string output field stats resource usage cpu total cpu stats resource usage memory object output field stats resource usage memory stats resource usage memory peak per node number output field stats resource usage memory peak per node stats dataset statistics array response data stats dataset statistics table row count number response data stats dataset statistics table size number response data 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 file name string name of the resource results file string result of the operation output 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" {"executiontime" 0 171881,"resource usage" {},"dataset statistics" \[]},"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 path parameters id string required parameters for the remove app restriction action comment string optional parameter for remove app restriction isolationtype string optional type of the resource input example {"json body" {"comment" "a comment","isolationtype" "isolationtype"},"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 {"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 path parameters id string required parameters for the restrict app execution action comment string optional parameter for restrict app execution input example {"json body" {"comment" "a comment"},"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 {"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 path parameters id string required parameters for the run antivirus scan action comment string optional comment to associate with the action scantype string optional 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 input example {"json body" {"comment" "check machine for viruses due to alert 3212","scantype" "full"},"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 output 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 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 optional parameter for run query input example {"json body" {"query" "a 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 error code string error message if any error message string response message error target string error message if any output 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" {"code" "badrequest","message" "a recognition error occurred fix syntax errors in your query ","target" "|1d25001e 48e8e09dbddde4f4 "}}} 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 path parameters id string required the machine id comment string optional comment to associate with the action input example {"json body" {"comment" "test investigation"},"path parameters" {"id" "1e5bc9d7e413ddd7902c2932e418702b84d0cc07"}} 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 output 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 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 path parameters id string required parameters for the stop and quarantine file action comment string optional parameter for stop and quarantine file sha1 string optional parameter for stop and quarantine file input example {"json body" {"comment" "a comment","sha1" "some file"},"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 target string error message if any output 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" {"code" "badrequest","message" "a recognition error occurred fix syntax errors in your query ","target" "|1d25001e 48e8e09dbddde4f4 "}}} 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 input example {"json body" {"indicatorvalue" "192 168 1 1","indicatortype" "domainname","action" "alertandblock","title" "malicious ip address","expirationtime" "2020 12 12t00 00 00z","severity" "high","description" "my indicator description","recommendedactions" "my recommendations are "}} 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 {"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 path parameters id string required parameters for the unisolate machine action comment string optional parameter for unisolate machine isolationtype string optional type of the resource input example {"json body" {"comment" "a comment","isolationtype" "isolationtype"},"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 {"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 path parameters id string required parameters for the update alert action 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 input example {"json body" {"status" "a comment","assignedto" "assignedto","classification" "classification","determination" "determination"},"path parameters" {"id" "556b3952acb0bff29816d267822305781cc183ec"}} 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 {"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 path parameters 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 input example {"json body" {"status" "resolved","assignedto" "secop2\@contoso com","classification" "truepositive","determination" "malware","tags" \["yossi's playground","don't mess with the zohan"],"comment" "pen testing"},"path parameters" {"id" 437}} 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 tags file name string name of the resource tags file string output field tags file comments array output field comments comments file name string name of the resource comments file string output field comments file alerts array output field alerts alerts alertid string unique identifier alerts provideralertid string unique identifier alerts incidentid number unique identifier alerts servicesource string output field alerts servicesource output 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","incident 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 gzip content length the length of the response body in bytes 0 content type the media type of the resource application/json date the date and time at which the message was originated thu, 04 may 2023 17 42 51 gmt mise correlation id http response header mise correlation id c6ccd948 929b 4073 be4d df4328ff6798 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