--- title: Microsoft Defender IoT slug: connectors/microsoft-defender-iot docTags: createdAt: 2026-06-09T16:30:10.116Z --- 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) ## Notes - [Microsoft Defender IoT API Doc](https://learn.microsoft.com/en-us/azure/defender-for-iot/organizations/references-work-with-defender-for-iot-apis) - [Inventory 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-request) - [Alert management API Doc](https://learn.microsoft.com/en-us/azure/defender-for-iot/organizations/api/sensor-alert-apis?tabs=alerts-request%2Cevents-request) - [Vulnerability 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-request) - [Integration 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) # 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:///#/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://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 |