Microsoft Defender IoT

the microsoft defender iot connector integrates with swimlane turbine microsoft defender for iot provides comprehensive threat detection for iot/ot environments, with multiple deployment options that include cloud connected, fully on premises, or hybrid prerequisites the microsoft defender iot asset requires an url and an api key to interact with the api capabilities this connector provides the following capabilities inventory management endpoints to access device information, connection details, and cves get connections get connections per device get cves get cves per ip address get devices alert management endpoints designed to retrieve alert information and related timeline events get alerts get events vulnerability management endpoints to gather information about operational vulnerabilities, device specific vulnerabilities, mitigation steps, and security vulnerabilities retrieve device vulnerability information retrieve mitigation steps retrieve operational vulnerabilities retrieve security vulnerabilities integration apis these endpoints are for continuous data streaming, including retrieving device connections, device details, device cves, creating/updating devices, etc create and update devices get deleted devices get details for a device get device connections get device cves get sensors asset setup generate an api access token to generate a token in the system settings window, select integrations > access tokens select generate token in description, describe what the new token is for, and select generate the access token appears copy it, because it won't be displayed again select finish the tokens that you create appear in the access tokens dialog box the used indicates the last time an external call with this token was received n/a in the used field indicates that the connection between the sensor and the connected server isn't working tasks setup get events type field filter results for a specific type only any value other than supported types is ignored for more information, see event type and title reference https //learn microsoft com/en us/azure/defender for iot/organizations/api/sensor alert apis?tabs=alerts request%2cevents request#event type and title reference configurations microsoft defender iot api key authentication authenticates using an api key configuration parameters parameter description type required url a url to the target host string required authorization access token string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions create and update devices create and update devices this api returns data about all devices that were updated after the given timestamp endpoint url /external/v3/integration/devices/{{timestamp}} method get input argument name type required description timestamp number required the start time from which results are returned, in milliseconds from epoch time and in utc timezone sensorid number optional return only devices seen by a specific sensor notificationtype number optional determines the types of devices to return supported values include 0 both updated and new devices, 1 only new devices and 2 only updated devices page number optional defines the number where the result page numbering begins for example, 0 = first page is 0 size number optional defines the page sizing output parameter type description status code number http status code of the response reason string response reason phrase u devices array output field u devices u operating system string output field u operating system u ip address objects array output field u ip address objects u ip address string output field u ip address u guessed mac addresses array output field u guessed mac addresses u mac address string output field u mac address u zone string output field u zone u name string name of the resource u mac address objects array output field u mac address objects u mac address string output field u mac address u last update number date value u vendor string output field u vendor u cm device url string url endpoint for the request u sensor ids array unique identifier u sensor id number unique identifier u appliance string output field u appliance u site string output field u site u device type object type of the resource u category string output field u category u purdue layer string output field u purdue layer u name string name of the resource u firmwares array output field u firmwares file name string name of the resource example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "u devices" \[], "u count" 204 } } ] get alerts retrieve alert information list of all the alerts that the defender for iot sensor has detected endpoint url /api/v1/alerts method get input argument name type required description state string optional get only handled or unhandled alerts supported values are handled, unhandled fromtime number optional get alerts created starting at a given time, in milliseconds from epoch time and in utc timezone totime number optional get alerts created only before at a given time, in milliseconds from epoch time and in utc timezone type string optional get alerts of a specific type only supported values are unexpected new devices and disconnections all other values are ignored output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ {}, {} ] } ] get connections retrieve device connection information list of all device connections endpoint url /api/v1/devices/connections method get input argument name type required description discoveredbefore number optional filter results that were detected before a given time, where the given time is defined in milliseconds from epoch time, and in utc timezone discoveredafter number optional filter results that were detected after a given time, where the given time is defined in milliseconds from epoch time, and in utc timezone lastactiveinminutes number optional filter results by a given time frame during which connections were active defined backwards, in minutes, from the current time output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ {}, {} ] } ] get connections per device retrieve specific device connection information list of all the connections per device endpoint url /api/v1/devices/{{deviceid}}/connections method get input argument name type required description deviceid string required get connections for the given device discoveredbefore number optional filter results that were detected before a given time, where the given time is defined in milliseconds from epoch time, and in utc timezone discoveredafter number optional filter results that were detected after a given time, where the given time is defined in milliseconds from epoch time, and in utc timezone lastactiveinminutes number optional filter results by a given time frame during which connections were active defined backwards, in minutes, from the current time output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ {}, {} ] } ] get cves retrieve information on cves list of all known cves discovered on devices in the network, sorted by descending cve score endpoint url /api/v1/devices/cves method get input argument name type required description top number optional determine how many top scored cves to get for each device ip address output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ {}, {} ] } ] get cves per ip address retrieve specific information on cves list of all known cves discovered on devices in the network for a specific ip address endpoint url /api/v1/devices/{{ipaddress}}/cves method get input argument name type required description ipaddress string required get cves for the given ip address top number optional determine how many top scored cves to get for each device ip address output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ {}, {} ] } ] get deleted devices get deleted devices this api returns a list of ids of recently deleted devices, from the supplied timestamp endpoint url /external/v3/integration/deleteddevices/{{timestamp}} method get input argument name type required description timestamp number required the start time from which results are returned, in milliseconds from epoch time and in utc timezone output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ { "u id" 192 }, { "u id" 66 }, { "u id" 4 } ] } ] get details for a device get details for a device this api returns data about a specific device per a given device id endpoint url /external/v3/integration/device/{{deviceid}} method get input argument name type required description deviceid string required the id of the requested device on the on premises management console output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ {} ] } ] get device connections get device connections this api returns data about all device connections that were updated after the given timestamp endpoint url /external/v3/integration/connections/{{timestamp}} method get input argument name type required description timestamp number required the start time from which results are returned, in milliseconds from epoch time and in utc timezone page number optional defines the number where the result page numbering begins for example, 0= first page is 0 size number optional defines the page sizing output parameter type description status code number http status code of the response reason string response reason phrase u count number count value u connections array output field u connections u src device id number unique identifier u dest device name string name of the resource u src device name string name of the resource u appliance string output field u appliance u connection type string type of the resource u dest device id number unique identifier example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "u count" 106, "u connections" \[] } } ] get device cves get device cves this api returns a list of active cves for all devices that were updated since the supplied timestamp endpoint url /external/v3/integration/devicecves/{{timestamp}} method get input argument name type required description timestamp number required the start time from which results are returned, in milliseconds from epoch time and in utc timezone page number optional defines the number where the result page numbering begins size number optional defines the page sizing sensorid number optional shows results from a specific sensor, as defined by the given sensor id score number optional determines a minimum cve score to be retrieved all results will have a cve score equal to or greater than the given value deviceids number optional a comma separated list of device ids from which you want to show results output parameter type description status code number http status code of the response reason string response reason phrase u count number count value u device cves array output field u device cves u ip address objects array output field u ip address objects u ip address string output field u ip address u guessed mac addresses array output field u guessed mac addresses u mac address string output field u mac address u name string name of the resource u mac address objects array output field u mac address objects u mac address string output field u mac address u last update number date value u last activity number output field u last activity u id number unique identifier u cves array output field u cves u cve id string unique identifier u score string score value u ip address string output field u ip address u description string output field u description u attack vector string output field u attack vector example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "u count" 2, "u device cves" \[] } } ] get devices retrieve device information list of all devices detected by this sensor endpoint url /api/v1/devices method get input argument name type required description authorized boolean optional true filter for data on authorized devices only false filter for data on unauthorized devices only output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier ipaddresses object output field ipaddresses mystringarray array output field mystringarray name string name of the resource vendor string output field vendor operatingsystem string output field operatingsystem macaddresses object output field macaddresses mystringarray array output field mystringarray type string type of the resource engineeringstation boolean output field engineeringstation authorized boolean output field authorized scanner boolean output field scanner protocols object output field protocols firmware object output field firmware mystringarray array output field mystringarray hasdynamicaddress boolean output field hasdynamicaddress example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "id" 1, "ipaddresses" {}, "name" "device name", "vendor" "device's vendor", "operatingsystem" "engineering", "macaddresses" {}, "type" "domain", "engineeringstation" true, "authorized" true, "scanner" false, "protocols" {}, "firmware" {}, "hasdynamicaddress" true } } ] get events retrieve timeline events list of events reported to the event timeline endpoint url /api/v1/events method get input argument name type required description minutestimeframe number optional filter results by a given time frame during which events were reported defined backwards from the current time maximum = 4320 (3 days) any larger value is treated as 4320, with no error type string optional filter results for a specific type only any value other than supported types is ignored for more information, see readme output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ { "severity" "info", "title" "back to normal", "timestamp" 1504097077000, "content" "device 10 2 1 15 was found responsive, after being suspected as disconnected", "owner" null, "type" "back to normal" }, { "severity" "alert", "title" "alert detected", "timestamp" 1504096909000, "content" "device 10 2 1 15 is suspected to be disconnected (unresponsive) ", "owner" null, "type" "alert reported" }, { "severity" "alert", "title" "alert detected", "timestamp" 1504094446000, "content" "a dnp3 master 10 2 1 14 attempted to initiate a request which is not allowed by policy \nthe policy indicates the allowed function codes, address ranges, point indexes and time intervals \nit is recommended to notify the security officer of the incident ", "owner" null, "type" "alert reported" } ] } ] get sensors get sensors this api returns a list of sensor objects for connected ot network sensors endpoint url /external/v3/integration/sensors method get output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ {} ] } ] retrieve device vulnerability information retrieve device vulnerability information use this api to request vulnerability assessment results for each device endpoint url /api/v1/reports/vulnerabilities/devices method get output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ {} ] } ] retrieve mitigation steps retrieve mitigation steps use this api to request a mitigation assessment this assessment provides recommended steps for mitigating detected vulnerabilities it's based on general network and system information and not on a specific device evaluation endpoint url /api/v1/reports/vulnerabilities/mitigation method get output parameter type description status code number http status code of the response reason string response reason phrase notifications array output field notifications mitigation array output field mitigation content string response content details object output field details name string name of the resource description object output field description name string name of the resource important boolean output field important warning boolean output field warning headers array http headers for the request rows array output field rows 0 string output field 0 1 string output field 1 2 string output field 2 scoreimprovement number output field scoreimprovement example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "notifications" \[], "mitigation" \[] } } ] retrieve operational vulnerabilities retrieve operational vulnerabilities use this api to request results of a general vulnerability assessment this assessment provides insight into the operational status of your network endpoint url /api/v1/reports/vulnerabilities/operational method get output parameter type description status code number http status code of the response reason string response reason phrase backupserver array output field backupserver backupmaximalinterval string output field backupmaximalinterval source string output field source destination string output field destination port number output field port transport string output field transport lastseenbackup number output field lastseenbackup ipnetworks array output field ipnetworks addresses string output field addresses network string output field network mask string output field mask protocolproblems array output field protocolproblems protocol string output field protocol addresses array output field addresses alert string output field alert reporttime number time value protocoldatavolumes array response data protocol string output field protocol volume string output field volume disconnections array output field disconnections assetaddress string output field assetaddress assetname string name of the resource lastdetectiontime number time value example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "backupserver" \[], "ipnetworks" \[], "protocolproblems" \[], "protocoldatavolumes" \[], "disconnections" \[] } } ] retrieve security vulnerabilities retrieve security vulnerabilities use this api to request results of a general vulnerability assessment report this assessment provides insight into your system's security level endpoint url /api/v1/reports/vulnerabilities/operational method get output parameter type description status code number http status code of the response reason string response reason phrase unauthorizeddevices array output field unauthorizeddevices address string output field address name string name of the resource firstdetectiontime number time value lastseen number output field lastseen redundantfirewallrules array output field redundantfirewallrules sources string output field sources destinations string output field destinations ports string output field ports connectionsbetweensubnets array output field connectionsbetweensubnets server string output field server client string output field client industrialmalwareindications array output field industrialmalwareindications detectiontime number time value alertmessage string response message description string output field description addresses array output field addresses illegaltrafficbyfirewallrules array output field illegaltrafficbyfirewallrules server string output field server port string output field port client string output field client transport string output field transport internetconnections array output field internetconnections example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "tue, 19 dec 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "unauthorizeddevices" \[], "redundantfirewallrules" \[], "connectionsbetweensubnets" \[], "industrialmalwareindications" \[], "illegaltrafficbyfirewallrules" \[], "internetconnections" \[], "accesspoints" \[], "weakfirewallrules" \[] } } ] response headers header description example content length the length of the response body in bytes 140 content type the media type of the resource application/json date the date and time at which the message was originated tue, 19 dec 2023 20 37 23 gmt notes microsoft defender iot api doc https //learn microsoft com/en us/azure/defender for iot/organizations/references work with defender for iot apisinventory management api doc https //learn microsoft com/en us/azure/defender for iot/organizations/api/sensor inventory apis?tabs=connections request%2cconnections device request%2ccves request%2ccves ip request%2cdevices requestalert management api doc https //learn microsoft com/en us/azure/defender for iot/organizations/api/sensor alert apis?tabs=alerts request%2cevents requestvulnerability management api doc https //learn microsoft com/en us/azure/defender for iot/organizations/api/sensor vulnerability apis?tabs=devices request%2csecurity request%2coperational request%2cmitigation requestintegration api doc https //learn microsoft com/en us/azure/defender for iot/organizations/api/management integration apis?tabs=devices request%2cconnections request%2cdevice request%2cdeleteddevices request%2csensors request%2cdevicecves request