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 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 notes https //learn microsoft com/en us/azure/defender for iot/organizations/references work with defender for iot apis 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 request https //learn microsoft com/en us/azure/defender for iot/organizations/api/sensor alert apis?tabs=alerts request%2cevents request https //learn microsoft com/en us/azure/defender for iot/organizations/api/sensor vulnerability apis?tabs=devices request%2csecurity request%2coperational request%2cmitigation request 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 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 path parameters timestamp number required the start time from which results are returned, in milliseconds from epoch time and in utc timezone parameters sensorid number optional return only devices seen by a specific sensor parameters 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 parameters page number optional defines the number where the result page numbering begins for example, 0 = first page is 0 parameters size number optional defines the page sizing input example {"parameters" {"sensorid" 1,"notificationtype" 2,"page" 0,"size" 50},"path parameters" {"timestamp" 1664781014000}} 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 devices u operating system string output field u devices u operating system u devices u ip address objects array output field u devices u ip address objects u devices u ip address objects u ip address string output field u devices u ip address objects u ip address u devices u ip address objects u guessed mac addresses array output field u devices u ip address objects u guessed mac addresses u devices u ip address objects u guessed mac addresses u mac address string output field u devices u ip address objects u guessed mac addresses u mac address u devices u zone string output field u devices u zone u devices u name string name of the resource u devices u mac address objects array output field u devices u mac address objects u devices u mac address objects u mac address string output field u devices u mac address objects u mac address u devices u last update number date value u devices u vendor string output field u devices u vendor u devices u cm device url string url endpoint for the request u devices u sensor ids array unique identifier u devices u sensor ids u sensor id number unique identifier u devices u appliance string output field u devices u appliance u devices u site string output field u devices u site u devices u device type object type of the resource u devices u device type u category string type of the resource u devices u device type u purdue layer string type of the resource u devices u device type u name string name of the resource u devices u firmwares array output field u devices u firmwares u devices u firmwares file name string name of the resource output 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 parameters state string optional get only handled or unhandled alerts supported values are handled, unhandled parameters fromtime number optional get alerts created starting at a given time, in milliseconds from epoch time and in utc timezone parameters totime number optional get alerts created only before at a given time, in milliseconds from epoch time and in utc timezone parameters type string optional get alerts of a specific type only supported values are unexpected new devices and disconnections all other values are ignored input example {"parameters" {"state" "handled","fromtime" 1594550986000,"totime" 20,"type" "disconnections"}} output parameter type description status code number http status code of the response reason string response reason phrase output 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" \[{"engine" "policy violation","severity" "major","title" "internet access detected","additionalinformation" {},"sourcedevice"\ null,"destinationdevice"\ null,"time" 1509881077000,"message" "device 192 168 0 13 tried to access an external ip address which is an address i ","id" 1},{"engine" "protocol violation","severity" "major","title" 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 parameters 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 parameters 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 parameters lastactiveinminutes number optional filter results by a given time frame during which connections were active defined backwards, in minutes, from the current time input example {"parameters" {"discoveredbefore" 1707297788138,"discoveredafter" 1807257788139,"lastactiveinminutes" 1607296788134}} output parameter type description status code number http status code of the response reason string response reason phrase output 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" \[{"firstdeviceid" 171,"seconddeviceid" 22,"lastseen" 1511281457933,"discovered" 1511872830000,"ports" \[],"protocols" \[]},{"firstdeviceid" 171,"seconddeviceid" 23,"lastseen" 1511281457933,"discovered" 1511872830000,"ports" \[],"protocols" \[]}]} 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 path parameters deviceid string required get connections for the given device parameters 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 parameters 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 parameters lastactiveinminutes number optional filter results by a given time frame during which connections were active defined backwards, in minutes, from the current time input example {"parameters" {"discoveredbefore" 1594550986000,"discoveredafter" 1594550986000,"lastactiveinminutes" 20},"path parameters" {"deviceid" "2"}} output parameter type description status code number http status code of the response reason string response reason phrase output 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" \[{"firstdeviceid" 171,"seconddeviceid" 22,"lastseen" 1511281457933,"discovered" 1511872830000,"ports" \[],"protocols" \[]},{"firstdeviceid" 171,"seconddeviceid" 23,"lastseen" 1511281457933,"discovered" 1511872830000,"ports" \[],"protocols" \[]}]} 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 parameters top number optional determine how many top scored cves to get for each device ip address input example {"parameters" {"top" 100}} output parameter type description status code number http status code of the response reason string response reason phrase output 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" \[{"cveid" "cve 2007 0099","score" "9 3","ipaddress" "10 35 1 51","attackvector" "network","description" "race condition in the msxml3 module in microsoft xml core services 3 0, as used "},{"cveid" "cve 2009 1547","score" "9 3","ipaddress" "10 35 1 51","attackvector" "network","description" "unspecified vulnerability in microsoft inte 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 path parameters ipaddress string required get cves for the given ip address parameters top number optional determine how many top scored cves to get for each device ip address input example {"parameters" {"top" 50},"path parameters" {"ipaddress" "10 10 10 15"}} output parameter type description status code number http status code of the response reason string response reason phrase output 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" \[{"cveid" "cve 2007 0099","score" "9 3","ipaddress" "10 35 1 51","attackvector" "network","description" "race condition in the msxml3 module in microsoft xml core services 3 0, as used "},{"cveid" "cve 2009 1547","score" "9 3","ipaddress" "10 35 1 51","attackvector" "network","description" "unspecified vulnerability in microsoft inte 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 path parameters timestamp number required the start time from which results are returned, in milliseconds from epoch time and in utc timezone input example {"path parameters" {"timestamp" 1664781014000}} output parameter type description status code number http status code of the response reason string response reason phrase output 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 path parameters deviceid string required the id of the requested device on the on premises management console input example {"path parameters" {"deviceid" "2"}} output parameter type description status code number http status code of the response reason string response reason phrase output 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 operating system" "","u ip address objects" \[],"u zone" "asd","u name" "10 10 50 5","u mac address objects" \[],"u last update" 1664782919000,"u vendor" "hilscher gmbh","u cm device url" "https //\<ip address>/#/sites/1/zones/1/devices maps?devices=1","u sensor ids" \[],"u appliance" "management console (cm)","u site" "asd","u device 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 path parameters timestamp number required the start time from which results are returned, in milliseconds from epoch time and in utc timezone parameters page number optional defines the number where the result page numbering begins for example, 0= first page is 0 parameters size number optional defines the page sizing input example {"parameters" {"page" 0,"size" 50},"path parameters" {"timestamp" 1664781014000}} 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 connections u src device id number unique identifier u connections u dest device name string name of the resource u connections u src device name string name of the resource u connections u appliance string output field u connections u appliance u connections u connection type string type of the resource u connections u dest device id number unique identifier output 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 path parameters timestamp number required the start time from which results are returned, in milliseconds from epoch time and in utc timezone parameters page number optional defines the number where the result page numbering begins parameters size number optional defines the page sizing parameters sensorid number optional shows results from a specific sensor, as defined by the given sensor id parameters 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 parameters deviceids number optional a comma separated list of device ids from which you want to show results input example {"parameters" {"page" 0,"size" 50,"sensorid" 1,"score" 0,"deviceids" 123},"path parameters" {"timestamp" 1664781014000}} 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 device cves u ip address objects array output field u device cves u ip address objects u device cves u ip address objects u ip address string output field u device cves u ip address objects u ip address u device cves u ip address objects u guessed mac addresses array output field u device cves u ip address objects u guessed mac addresses u device cves u ip address objects u guessed mac addresses u mac address string output field u device cves u ip address objects u guessed mac addresses u mac address u device cves u name string name of the resource u device cves u mac address objects array output field u device cves u mac address objects u device cves u mac address objects u mac address string output field u device cves u mac address objects u mac address u device cves u last update number date value u device cves u last activity number output field u device cves u last activity u device cves u id number unique identifier u device cves u cves array output field u device cves u cves u device cves u cves u cve id string unique identifier u device cves u cves u score string score value u device cves u cves u ip address string output field u device cves u cves u ip address u device cves u cves u description string output field u device cves u cves u description u device cves u cves u attack vector string output field u device cves u cves u attack vector output 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 parameters authorized boolean optional true filter for data on authorized devices only false filter for data on unauthorized devices only input example {"parameters" {"authorized"\ true}} 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 ipaddresses mystringarray array output field ipaddresses mystringarray name string name of the resource vendor string output field vendor operatingsystem string output field operatingsystem macaddresses object output field macaddresses macaddresses mystringarray array output field macaddresses 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 firmware mystringarray array output field firmware mystringarray hasdynamicaddress boolean output field hasdynamicaddress output 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" {"mystringarray" \[]},"name" "device name","vendor" "device's vendor","operatingsystem" "engineering","macaddresses" {"mystringarray" \[]},"type" "domain","engineeringstation"\ true,"authorized"\ true,"scanner"\ false,"protocols" {},"firmware" {"mystringarray" \[]},"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 parameters 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 parameters type string optional filter results for a specific type only any value other than supported types is ignored for more information, see readme input example {"parameters" {"minutestimeframe" 20,"type" "device connection created"}} output parameter type description status code number http status code of the response reason string response reason phrase output 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 (unrespon 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 output 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 connection state" "synced","u uid" "fab58081 1fde 4d3f 8eea 9aa723abbd55","u name" "microsoft defender for iot","u is activated"\ true,"u alert count" 6,"u device count" 202,"u interface address" "https //\<ip address>9","u zone id" 1,"u data intelligence version" "may 26, 2022","u is in learning mode"\ false,"u unhandled alert count" 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 output 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" \[{"name" "ied 10","ipaddresses" \[],"securityscore" 100,"vendor" "abb switzerland ltd, power systems","firmwareversion"\ null,"model"\ null,"operatingsystem" {},"vulnerabilities" {}}]} 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 mitigation content string response content mitigation details object output field mitigation details mitigation details name string name of the resource mitigation details description object output field mitigation details description mitigation details description name string name of the resource mitigation details description important boolean output field mitigation details description important mitigation details description warning boolean output field mitigation details description warning mitigation details headers array http headers for the request mitigation details rows array output field mitigation details rows mitigation details rows 0 string output field mitigation details rows 0 mitigation details rows 1 string output field mitigation details rows 1 mitigation details rows 2 string output field mitigation details rows 2 mitigation scoreimprovement number output field mitigation scoreimprovement output 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" \["firewall policy import","marking \\"important devices\\"","further device information import"],"mitigation" \[{"content" "install an antivirus solution to increase protection of the workstations","details"\ null,"scoreimprovement" 10},{"content" "investigate all malware indicators (contact your incident response team or s 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 backupserver backupmaximalinterval string output field backupserver backupmaximalinterval backupserver source string output field backupserver source backupserver destination string output field backupserver destination backupserver port number output field backupserver port backupserver transport string output field backupserver transport backupserver lastseenbackup number output field backupserver lastseenbackup ipnetworks array output field ipnetworks ipnetworks addresses string output field ipnetworks addresses ipnetworks network string output field ipnetworks network ipnetworks mask string output field ipnetworks mask protocolproblems array output field protocolproblems protocolproblems protocol string output field protocolproblems protocol protocolproblems addresses array output field protocolproblems addresses protocolproblems alert string output field protocolproblems alert protocolproblems reporttime number time value protocoldatavolumes array response data protocoldatavolumes protocol string response data protocoldatavolumes volume string response data disconnections array output field disconnections disconnections assetaddress string output field disconnections assetaddress disconnections assetname string name of the resource disconnections lastdetectiontime number time value output 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 unauthorizeddevices address string output field unauthorizeddevices address unauthorizeddevices name string name of the resource unauthorizeddevices firstdetectiontime number time value unauthorizeddevices lastseen number output field unauthorizeddevices lastseen redundantfirewallrules array output field redundantfirewallrules redundantfirewallrules sources string output field redundantfirewallrules sources redundantfirewallrules destinations string output field redundantfirewallrules destinations redundantfirewallrules ports string output field redundantfirewallrules ports connectionsbetweensubnets array output field connectionsbetweensubnets connectionsbetweensubnets server string output field connectionsbetweensubnets server connectionsbetweensubnets client string output field connectionsbetweensubnets client industrialmalwareindications array output field industrialmalwareindications industrialmalwareindications detectiontime number time value industrialmalwareindications alertmessage string response message industrialmalwareindications description string output field industrialmalwareindications description industrialmalwareindications addresses array output field industrialmalwareindications addresses illegaltrafficbyfirewallrules array output field illegaltrafficbyfirewallrules illegaltrafficbyfirewallrules server string output field illegaltrafficbyfirewallrules server illegaltrafficbyfirewallrules port string output field illegaltrafficbyfirewallrules port illegaltrafficbyfirewallrules client string output field illegaltrafficbyfirewallrules client illegaltrafficbyfirewallrules transport string output field illegaltrafficbyfirewallrules transport internetconnections array output field internetconnections output 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