Naslaginformatie over integratie-API voor on-premises beheerconsoles (openbare preview)

In dit artikel worden de API's vermeld die worden ondersteund voor het integreren van Microsoft Defender voor IoT met partnerservices.

Deze API is bijvoorbeeld momenteel geïmplementeerd met Zelfstudie: ServiceNow integreren met Microsoft Defender voor IoT, via de ServiceNow Service Graph Connector voor Defender for IoT.

Notitie

Integratie-API's zijn bedoeld om continu te worden uitgevoerd en een voortdurend actieve gegevensstroom te maken, bijvoorbeeld om nieuwe gegevens uit de afgelopen vijf minuten op te vragen. Integratie-API's retourneren gegevens met een tijdstempel.

Als u gewoon gegevens wilt opvragen, gebruikt u in plaats daarvan de reguliere, niet-integratie-API's, voor een on-premises beheerconsole om query's uit te voeren op alle apparaten of voor een specifieke sensor om alleen vanaf die sensor een query uit te voeren. Zie Naslaginformatie over Defender for IoT API voor meer informatie.

URI: /external/v3/integration/

apparaten (apparaten maken en bijwerken)

Deze API retourneert gegevens over alle apparaten die zijn bijgewerkt na het opgegeven tijdstempel.

URI: /external/v3/integration/devices/<timestamp>

URI-parameters:

Naam	Beschrijving	Voorbeeld	Vereist/optioneel
Tijdstempel	De begintijd vanaf waaruit resultaten worden geretourneerd, in milliseconden vanaf Epoch-tijd en in UTC-tijdzone.	/external/v3/integration/devices/1664781014000	Vereist

GET

Aanvraag

Queryparameters:

Naam	Beschrijving	Voorbeeld	Vereist/optioneel
sensorId	Alleen apparaten retourneren die door een specifieke sensor worden gezien. Gebruik de id-waarde uit de resultaten van de SENSOREN-API (Sensoren ophalen).	1	Optioneel
notificationType	Bepaalt de typen apparaten die moeten worden geretourneerd. Ondersteunde waarden zijn: - 0: Zowel bijgewerkte als nieuwe apparaten (standaard). - 1: Alleen nieuwe apparaten. - 2: Alleen bijgewerkte apparaten.	2	Optioneel
Pagina	Hiermee definieert u het nummer waar de paginanummering van de resultaatpagina begint. = eerste pagina is bijvoorbeeld 00. Standaard = 0	0	Optioneel
Grootte	Hiermee definieert u de grootte van de pagina. Standaard = 50	75	Optioneel

Response

Type: JSON

Antwoordvelden:

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_count	Geheel getal	Niet nullable	Het aantal objecten in de volledige resultatenset, inclusief alle pagina's.
u_devices	JSON-matrix met apparaatobjecten	Niet nullable	Een matrix van apparaatobjecten, zoals gedefinieerd door de APPARAAT-API (Details ophalen voor een apparaat).

Voorbeeld van antwoord

{
    "u_devices": [{
        "u_operating_system": "",
        "u_ip_address_objects": [{
            "u_ip_address": "10.10.50.5",
            "u_guessed_mac_addresses": [{
                "u_mac_address": "00:02:a2:1f:1c:59"
            }]
        }],
        "u_zone": "asd",
        "u_name": "10.10.50.5",
        "u_mac_address_objects": [{
            "u_mac_address": "00:02:a2:1f:1c:59"
        }],
        "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_sensor_id": 1
        }],
        "u_appliance": "Management console (CM)",
        "u_site": "asd",
        "u_device_type": {
            "u_category": "ICS",
            "u_purdue_layer": "Process Control",
            "u_name": "PLC"
        },
        "u_firmwares": [],
        "u_last_activity": 1664782791000,
        "u_purdue_layer": "N/A",
        "u_device_urls": [{
            "u_device_url": "https://<IP address>9/#/assets/highlight/1"
        }],
        "u_vlans": [{
            "u_vlan": "1"
        }],
        "u_groups": ["asd"],
        "u_first_discovered": 1664781051000,
        "u_id": 1,
        "u_protocol_objects": [{
            "u_protocol": "MODBUS"
        }]
    }, {
        "u_operating_system": "",
        "u_ip_address_objects": [{
            "u_ip_address": "10.10.20.10",
            "u_guessed_mac_addresses": [{
                "u_mac_address": "00:02:a2:1f:02:ba"
            }]
        }],
        "u_zone": "asd",
        "u_name": "10.10.20.10",
        "u_mac_address_objects": [{
            "u_mac_address": "00:02:a2:1f:02:ba"
        }],
        "u_last_update": 1664782859000,
        "u_vendor": "HILSCHER GMBH",
        "u_cm_device_url": "https://<IP address>/#/sites/1/zones/1/devices-maps?devices=50",
        "u_sensor_ids": [{
            "u_sensor_id": 1
        }],
        "u_appliance": "Management console (CM)",
        "u_site": "asd",
        "u_device_type": {
            "u_category": "ICS",
            "u_purdue_layer": "Process Control",
            "u_name": "PLC"
        },
        "u_firmwares": [],
        "u_last_activity": 1664782786000,
        "u_purdue_layer": "N/A",
        "u_device_urls": [{
            "u_device_url": "https://<IP address>9/#/assets/highlight/50"
        }],
        "u_vlans": [{
            "u_vlan": "1"
        }],
        "u_groups": ["asd"],
        "u_first_discovered": 1664781052000,
        "u_id": 50,
        "u_protocol_objects": [{
            "u_protocol": "MODBUS"
        }]
    }],
    "u_count": 204
}

cURL-opdracht

Type: GET

API:

curl -k -H "Authorization: <Authorization token>" "https://<IP address>/external/v3/integration/devices/<Timestamp>"

Voorbeeld:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/devices/<Timestamp>"

verbindingen (apparaatverbindingen ophalen)

Deze API retourneert gegevens over alle apparaatverbindingen die zijn bijgewerkt na de opgegeven tijdstempel.

URI: /external/v3/integration/connections/<timestamp>

URI-parameters:

Naam	Beschrijving	Voorbeeld	Vereist/optioneel
Tijdstempel	De begintijd vanaf waaruit resultaten worden geretourneerd, in milliseconden vanaf Epoch-tijd en in UTC-tijdzone.	/external/v3/integration/devices/1664781014000	Vereist

GET

Aanvraag

Queryparameters:

Naam	Beschrijving	Voorbeeld	Vereist/optioneel
Pagina	Hiermee definieert u het nummer waar de paginanummering van de resultaatpagina begint. = eerste pagina is bijvoorbeeld 00. Standaard = 0	0	Optioneel
Grootte	Hiermee definieert u de grootte van de pagina. Standaard = 50	75	Optioneel

Response

Type: JSON

Antwoordvelden:

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_count	Geheel getal	Niet nullable	Het aantal objecten in de volledige resultatenset, inclusief alle pagina's.
u_connections	JSON-matrix met verbindingsobjecten	Niet nullable	Een matrix van verbindingsobjecten

verbindingsvelden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_appliance	Tekenreeks	Niet nullable	De naam van de sensor die de verbinding heeft gedetecteerd.
u_src_device_id	Geheel getal	Niet nullable	De id van het bronapparaat van de verbinding.
u_src_device_name	Tekenreeks	Niet nullable	De naam van het bronapparaat van de verbinding.
u_dest_device_id	Geheel getal	Niet nullable	De id van het doelapparaat van de verbinding.
u_dest_device_name	Tekenreeks	Niet nullable	De naam van het doelapparaat van de verbinding.
u_connection_type	Tekenreeks	Niet nullable	Een van de volgende: One Way, Two Way, Multicast

Voorbeeld van antwoord

{
    "u_count": 106,
    "u_connections": [{
        "u_src_device_id": 103,
        "u_dest_device_name": "10.10.10.16",
        "u_src_device_name": "10.10.10.18",
        "u_appliance": "Management console (CM)",
        "u_connection_type": "Two Way",
        "u_dest_device_id": 95
    }, {
        "u_src_device_id": 115,
        "u_dest_device_name": "10.10.10.64",
        "u_src_device_name": "10.10.10.30",
        "u_appliance": "Management console (CM)",
        "u_connection_type": "Two Way",
        "u_dest_device_id": 19
    }, {
        "u_src_device_id": 176,
        "u_dest_device_name": "10.10.45.7",
        "u_src_device_name": "10.10.45.100",
        "u_appliance": "Management console (CM)",
        "u_connection_type": "Two Way",
        "u_dest_device_id": 134
    },

cURL-opdracht

Type: GET

API:

curl -k -H "Authorization: <Authorization token>" "https://<IP address>/external/v3/integration/connections/1664781014000"

Voorbeeld:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/connections/1664781014000"

apparaat (Details voor een apparaat ophalen)

Deze API retourneert gegevens over een specifiek apparaat per bepaalde apparaat-id.

URI: /external/v3/integration/device/{deviceId}

GET

Aanvraag

Queryparameters:

Naam	Beschrijving	Voorbeeld	Vereist/optioneel
deviceId	De id van het aangevraagde apparaat in de on-premises beheerconsole	1	Vereist

Response

Type: JSON

Antwoordvelden:

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_id	Lang geheel getal	Niet nullable	De id van het apparaat in de on-premises beheerconsole.
u_vendor	Tekenreeks	Null-waarde toegestaan	De naam van de leverancier van het apparaat.
u_appliance	Tekenreeks	Niet nullable	De naam van de sensor die het apparaat heeft gedetecteerd.
u_mac_address_objects	JSON-matrix met tekenreeksen	Niet nullable	Een matrix met u_mac_address waarden, waarin de MAC-adressen van het apparaat worden weergegeven.
u_groups	JSON-matrix met tekenreeksen	Niet nullable	Een matrix van de groepen die het apparaat bevatten.
u_site	Tekenreeks	Niet nullable	De naam van de site van het apparaat.
u_zone	Tekenreeks	Niet nullable	De naam van de site van het apparaat.
u_last_activity	DateTime	Niet nullable	Het tijdstempel van de laatste keer dat het apparaat actief was.
u_first_discovered	DateTime	Niet nullable	De tijdstempel van de detectietijd van het apparaat.
u_device_type	Tekenreeks	Niet nullable	Het apparaattype
u_name	Tekenreeks	Niet nullable	Hiermee definieert u de apparaatnaam.
u_ip_address_objects	JSON-matrix met IP-adressen	Niet nullable	Matrix van IP-adresobjecten
u_mac_address_objects	JSON-matrix met MAC-adressen	Niet nullable	Matrix van MAC-adresobjecten
u_protocol_objects	JSON-matrix met protocollen	Niet nullable	Een matrix van protocolobjecten
u_vlans	JSON-matrix van VLAN-objecten	Niet nullable	Een matrix met VLAN-objecten
u_purdue_layer	Tekenreeks	Niet nullable	Definieert de standaard purdue-laag voor dit apparaattype.
u_sensor_ids	JSON-matrix van sensor-id-objecten	Niet nullable	Een matrix van sensor-id-objecten
u_cm_device_url	Tekenreeks	Niet nullable	De URL die wordt gebruikt voor toegang tot het apparaat in de on-premises beheerconsole.
u_device_urls	JSON-matrix met URL-objecten	Niet nullable	Een matrix van apparaat-URL-objecten
u_last_update	Lang geheel getal	Niet nullable	Hiermee definieert u de tijdstempel van de laatste updatetijd van het apparaat.
u_firmwares	JSON-matrix van firmwareobjecten	Niet nullable	Een matrix van firmwareobjecten

ip_address_object velden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_ip_address	Tekenreeks	Niet nullable	Een van de IP-adressen van het apparaat
u_guessed_mac_address	Tekenreeks	Niet nullable	De geraden MAC-adressen die zijn gekoppeld aan het IP-adres

mac_address_object velden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_mac_address	Tekenreeks	Niet nullable	Een van de MAC-adressen van het apparaat.

protocol_object velden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_protocol	Tekenreeks	Niet nullable	Een van de protocollen die door het apparaat worden gebruikt.

vlan_object velden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_vlan	Tekenreeks	Niet nullable	Een van de VLAN's waar het apparaat wordt gevonden.

sensor_id_object velden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_sensor_id	Tekenreeks	Niet nullable	De id van de sensor die het apparaat heeft gedetecteerd.

device_url_object velden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_device_url	Tekenreeks	Niet nullable	De URL's die worden gebruikt om het apparaat weer te geven in de on-premises beheerconsole.

firmware_object velden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_appliance	Tekenreeks	Niet nullable	De naam van de on-premises beheerconsole die het apparaat beheert.
u_id	Lang geheel getal	Niet nullable	De id van het apparaat op de on-premises beheerconsole
u_asset	Tekenreeks	Niet nullable	De naam van het apparaat
u_address	Tekenreeks	Niet nullable	Het firmwareadres van het apparaat
u_module_address	Tekenreeks	Null-waarde toegestaan	Het adres van de firmwaremodule van het apparaat
u_serial	Tekenreeks	Null-waarde toegestaan	Het serienummer van de firmware van het apparaat
u_model	Tekenreeks	Null-waarde toegestaan	Het firmwaremodel van het apparaat
u_version	Tekenreeks	Null-waarde toegestaan	De firmwareversie van het apparaat
u_additional_data	Tekenreeks	Null-waarde toegestaan	Aanvullende gegevens van de leverancier van de firmware van het apparaat

Voorbeeld van antwoord

[{
    "u_operating_system": "",
    "u_ip_address_objects": [{
        "u_ip_address": "10.10.50.5",
        "u_guessed_mac_addresses": [{
            "u_mac_address": "00:02:a2:1f:1c:59"
        }]
    }],
    "u_zone": "asd",
    "u_name": "10.10.50.5",
    "u_mac_address_objects": [{
        "u_mac_address": "00:02:a2:1f:1c:59"
    }],
    "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_sensor_id": 1
    }],
    "u_appliance": "Management console (CM)",
    "u_site": "asd",
    "u_device_type": {
        "u_category": "ICS",
        "u_purdue_layer": "Process Control",
        "u_name": "PLC"
    },
    "u_firmwares": [],
    "u_last_activity": 1664782791000,
    "u_purdue_layer": "N/A",
    "u_device_urls": [{
        "u_device_url": "https://<IP address>9/#/assets/highlight/1"
    }],
    "u_vlans": [{
        "u_vlan": "1"
    }],
    "u_groups": ["asd"],
    "u_first_discovered": 1664781051000,
    "u_id": 1,
    "u_protocol_objects": [{
        "u_protocol": "MODBUS"
    }]
}]

cURL-opdracht

Type: GET

API:

curl -k -H "Authorization: <Authorization token>" "https://<IP address>/external/v3/integration/device/<device ID>"

Voorbeeld:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/device/1"

deleteddevices (Verwijderde apparaten ophalen)

Deze API retourneert een lijst met id's van onlangs verwijderde apparaten uit de opgegeven tijdstempel.

URI: /external/v3/integration/deleteddevices/

GET

Aanvraag

URI-parameters:

Naam	Beschrijving	Voorbeeld	Vereist/optioneel
Tijdstempel	De begintijd vanaf waaruit resultaten worden geretourneerd, in milliseconden vanaf Epoch-tijd en in UTC-tijdzone.	/external/v3/integration/deleteddevices/1664781014000	Vereist

Response

Type: JSON-matrix met verwijderde apparaten

Verwijderde apparaatvelden:

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_id	Lang geheel getal	Niet nullable	Een id van een verwijderd apparaat

Voorbeeld van antwoord

[{
    "u_id": 192
}, {
    "u_id": 66
}, {
    "u_id": 4
}, {
    "u_id": 22
}, {
    "u_id": 24
}]

cURL-opdracht

Type: GET

API:

curl -k -H "Authorization: <Authorization token>" "https://<IP address>/external/v3/integration/deleteddevices/<timestamp>"

Voorbeeld:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/deleteddevices/1664781014000"

sensoren (sensoren ophalen)

Deze API retourneert een lijst met sensorobjecten voor verbonden OT-netwerksensoren.

URI: /external/v3/integration/sensors/

GET

Aanvraag

URI: /sensors

Geen queryparameters

Response

Type: JSON

Antwoordvelden:

Een matrix van de volgende velden:

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_id	Lang geheel getal	Niet nullable	Hiermee definieert u de interne sensor-id die moet worden gebruikt in de API voor apparaten (apparaten maken en bijwerken).
u_name	Tekenreeks	Niet nullable	Hiermee definieert u de naam van het sensorapparaat.
u_interface_address	Tekenreeks	Niet nullable	Definieert het netwerkadres van het sensorapparaat.
u_connection_state	Tekenreeks	Niet nullable	Definieert de verbindingsstatus van het apparaat met een on-premises beheerconsole met behulp van een van de volgende waarden: - GESYNCHRONISEERD: de verbinding is geslaagd. - OUT_OF_SYNC: de on-premises beheerconsole kan geen gegevens verwerken die zijn ontvangen van de sensor. - TIME_DIFF_OFFSET: Tijdsdrift gedetecteerd. De on-premises beheerconsole is losgekoppeld van de sensor. DISCONNECTED: Sensor communiceert niet met de beheerconsole. Controleer de netwerkverbinding.
u_version	Tekenreeks	Niet nullable	Een tekenreeksweergave van de softwareversie van de sensor.
u_alert_count	Lang geheel getal	Niet nullable	Het huidige aantal waarschuwingen dat door de sensor wordt geactiveerd.
u_device_count	Lang geheel getal	Niet nullable	Het huidige aantal apparaten dat door de sensor is gedetecteerd.
u_unhandled_alert_count	Lang geheel getal	Niet nullable	Het huidige aantal momenteel niet-verwerkte waarschuwingen op de sensor.
u_is_activated	Booleaans	Niet nullable	Hiermee bepaalt u of de sensor wordt geactiveerd.
u_data_intelligence_version	Tekenreeks	Niet nullable	Een tekenreeksweergave van de versie van bedreigingsinformatie die op de sensor is geïnstalleerd.
u_uid	Tekenreeks	Niet nullable	Definieert de globally unique identifier van de sensor.
u_zone_id	Lang geheel getal	Null-waarde toegestaan	Definieer de zone van het apparaat.
u_is_in_learning_mode	Booleaans	Niet nullable	Bepaalt of de sensor zich in de leermodus bevindt.
u_remote_upgrade_stage	Tekenreeks	Null-waarde toegestaan	Definieert een huidige fase in een versie-updateproces als een van de volgende: - UPLOADING - PREPARE_TO_INSTALL - STOPPING_PROCESSES - BACKING_UP_DATA - TAKING_SNAPSHOT - UPDATING_CONFIGURATION - UPDATING_DEPENDENCIES - UPDATING_LIBRARIES - PATCHING_DATABASES - STARTING_PROCESSES - VALIDATING_SYSTEM_SANITY - VALIDATION_SUCCEEDED_REBOOTING - SUCCESS - FAILURE - UPGRADE_STARTED - STARTING_INSTALLATION - INSTALLING_OPERATING_SYSTEM

Voorbeeld van antwoord

[
  {
    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: 6,
    u_remote_upgrade_stage: "",
    u_id: 1,
    u_version: "22.2.5.7-r-2121448",
  },
];

cURL-opdracht

Type: GET

API:

curl -k -H "Authorization: <Authorization token>" "https://<IP Address>/external/v3/integration/sensors"

Voorbeeld:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/sensors"

devicecves (APPARAAT-CVE's ophalen)

Deze API retourneert een lijst met actieve CVE's voor alle apparaten die zijn bijgewerkt sinds de opgegeven tijdstempel.

URI: /external/v3/integration/devicecves/

GET

Aanvraag

URI: /external/v3/integration/devicecves/<timestamp>

URI-parameters

Naam	Beschrijving	Voorbeeld	Vereist/optioneel
Tijdstempel	De begintijd vanaf waaruit resultaten worden geretourneerd, in milliseconden vanaf Epoch-tijd en in UTC-tijdzone.	/external/v3/integration/devicecves/1664781014000	Vereist

Queryparameters

Naam	Beschrijving	Voorbeeld	Vereist/optioneel
Pagina	Hiermee definieert u het nummer waar de paginanummering van de resultaatpagina begint.	0= eerste pagina is 0. Standaard = 0	Optioneel
Grootte	Hiermee definieert u de grootte van de pagina.	Standaard = 50	Optioneel
sensorId	Toont resultaten van een specifieke sensor, zoals gedefinieerd door de opgegeven sensor-id.	1	Optioneel
Score	Bepaalt een minimale CVE-score die moet worden opgehaald. Alle resultaten hebben een CVE-score die gelijk is aan of groter is dan de opgegeven waarde.	Standaard = 0.	Optioneel
deviceIds	Een door komma's gescheiden lijst met apparaat-id's waarvan u de resultaten wilt weergeven.	Bijvoorbeeld: 1232,34,2,456	Optioneel

Response

Type: Aantal en JSON-matrix van apparaat-CVE's

Antwoordvelden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_count	Geheel getal	Niet nullable	Het aantal objecten in de volledige resultatenset, inclusief alle pagina's.
u_device_cves	JSON-matrix van CVE-objecten voor apparaten	Niet nullable	Een matrix met CVE-objecten voor apparaten

CVE-velden voor apparaat

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_id	Geheel getal	Niet nullable	De id van het apparaat in de on-premises beheerconsole.
u_name	Tekenreeks	Niet nullable	De naam van het apparaat.
u_ip_address_objects	JSON-matrix met IP-adresobjecten	Niet nullable	Matrix van u_ip_address waarden, waarmee de IP-adressen van apparaten worden gedefinieerd.
u_mac_address_objects	JSON-matrix met MAC-adresobjecten	Niet nullable	Een matrix met u_mac_address waarden, waarin de MAC-adressen van het apparaat worden vermeld.
u_last_activity	Geheel getal	Niet nullable	Tijdstempel van de laatste keer dat verkeer van of naar het apparaat is gezien.
u_last_update	Geheel getal	Niet nullable	Het tijdstempel van de laatste keer dat een eigenschap op het apparaat is gewijzigd, inclusief gebruikerswijzigingen en geautomatiseerde systeemwijzigingen.
u_cves	JSON-matrix met CVE's	Niet nullable	Een matrix van CVE-detailsobjecten

Notitie

Als Defender for IoT het MAC-adres van een van de IP-adressen kan identificeren, wordt het MAC-adres rechtstreeks in het u_mac_address_objects veld geretourneerd.

Als Defender for IoT niet volledig zeker is van een MAC-adres, bijvoorbeeld als het verkeer is gerouteerd via een router, wordt het MAC-adres in plaats daarvan geretourneerd in het u_guessed_mac_address veld, als onderdeel van de JSON-matrix met IP-adressen.

u_ip_address_objects velden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_ip_address	Tekenreeks	Niet nullable	Een van de IP-adressen van het apparaat
u_guessed_mac_address	JSON-matrix met MAC-adresobjecten	Niet nullable	JSON-matrix met MAC-adressen

u_mac_address_objects velden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_mac_address	Tekenreeks	Niet nullable	Een van de MAC-adressen van het apparaat

u_cves velden

Naam	Type	Nullable /Not nullable	Lijst met waarden
u_address	Tekenreeks	Niet nullable	Adres van de specifieke interface, met de specifieke firmware waar de CVE is gedetecteerd.
u_cve_id	Tekenreeks	Niet nullable	Definieert de CVE-id
u_score	Tekenreeks	Niet nullable	Definieert de CVE-risicoscore
u_attack_vector	Tekenreeks	Niet nullable	Definieert de aanvalsvector als een van de volgende: ADJACENT_NETWORK, LOCAL, NETWORK
u_description	Tekenreeks	Niet nullable	Definieert de CVE-beschrijving

Voorbeeld van antwoord

{
    "u_count": 2,
    "u_device_cves": [{
        "u_ip_address_objects": [{
            "u_ip_address": "192.168.1.127",
            "u_guessed_mac_addresses": [{
                "u_mac_address": "00:0f:38:67:4f:1c"
            }]
        }],
        "u_name": "192.168.1.127",
        "u_mac_address_objects": [{
            "u_mac_address": "00:0f:38:67:4f:1c"
        }],
        "u_last_update": 1664787209000,
        "u_last_activity": 1664782792000,
        "u_id": 135,
        "u_cves": [{
            "u_cve_id": "CVE-2015-2373",
            "u_score": "10.0",
            "u_ip_address": "192.168.1.127",
            "u_description": "The Remote Desktop Protocol (RDP) server service in Microsoft Windows 7 SP1, Windows 8, and Windows Server 2012 allows remote attackers to execute arbitrary code via a series of crafted packets, aka \"Remote Desktop Protocol (RDP) Remote Code Execution Vulnerability.\"",
            "u_attack_vector": "NETWORK"
        }, {
            "u_cve_id": "CVE-2015-1635",
            "u_score": "10.0",
            "u_ip_address": "192.168.1.127",
            "u_description": "HTTP.sys in Microsoft Windows 7 SP1, Windows Server 2008 R2 SP1, Windows 8, Windows 8.1, and Windows Server 2012 Gold and R2 allows remote attackers to execute arbitrary code via crafted HTTP requests, aka \"HTTP.sys Remote Code Execution Vulnerability.\"",
            "u_attack_vector": "NETWORK"
        }, {
            "u_cve_id": "CVE-2015-0014",
            "u_score": "10.0",
            "u_ip_address": "192.168.1.127",
            "u_description": "Buffer overflow in the Telnet service in Microsoft Windows Server 2003 SP2, Windows Vista SP2, Windows Server 2008 SP2 and R2 SP1, Windows 7 SP1, Windows 8, Windows 8.1, and Windows Server 2012 Gold and R2 allows remote attackers to execute arbitrary code via crafted packets, aka \"Windows Telnet Service Buffer Overflow Vulnerability.\"",
            "u_attack_vector": "NETWORK"
        }]
    }, {
        "u_ip_address_objects": [{
            "u_ip_address": "10.13.10.5",
            "u_guessed_mac_addresses": [{
                "u_mac_address": "00:05:f0:00:0f:cd"
            }]
        }],
        "u_name": "10.13.10.5",
        "u_mac_address_objects": [{
            "u_mac_address": "00:05:f0:00:0f:cd"
        }],
        "u_last_update": 1664787149000,
        "u_last_activity": 1664782792000,
        "u_id": 181,
        "u_cves": [{
            "u_cve_id": "CVE-2016-7182",
            "u_score": "10.0",
            "u_ip_address": "10.13.10.5",
            "u_description": "The Graphics component in Microsoft Windows Vista SP2; Windows Server 2008 SP2 and R2 SP1; Windows 7 SP1; Windows 8.1; Windows Server 2012 Gold and R2; Windows RT 8.1; Windows 10 Gold, 1511, and 1607; Office 2007 SP3; Office 2010 SP2; Word Viewer; Skype for Business 2016; Lync 2013 SP1; Lync 2010; Lync 2010 Attendee; and Live Meeting 2007 Console allows attackers to execute arbitrary code via a crafted True Type font, aka \"True Type Font Parsing Elevation of Privilege Vulnerability.\"",
            "u_attack_vector": "NETWORK"
        }, {
            "u_cve_id": "CVE-2016-3270",
            "u_score": "10.0",
            "u_ip_address": "10.13.10.5",
            "u_description": "The Graphics component in the kernel in Microsoft Windows Vista SP2; Windows Server 2008 SP2 and R2 SP1; Windows 7 SP1; Windows 8.1; Windows Server 2012 Gold and R2; Windows RT 8.1; and Windows 10 Gold, 1511, and 1607 allows local users to gain privileges via a crafted application, aka \"Win32k Elevation of Privilege Vulnerability.\"",
            "u_attack_vector": "NETWORK"
        }, {
            "u_cve_id": "CVE-2016-3266",
            "u_score": "10.0",
            "u_ip_address": "10.13.10.5",
            "u_description": "The kernel-mode drivers in Microsoft Windows Vista SP2, Windows Server 2008 SP2 and R2 SP1, Windows 7 SP1, Windows 8.1, Windows Server 2012 Gold and R2, Windows RT 8.1, and Windows 10 Gold, 1511, and 1607 allow local users to gain privileges via a crafted application, aka \"Win32k Elevation of Privilege Vulnerability,\" a different vulnerability than CVE-2016-3376, CVE-2016-7185, and CVE-2016-7211.",
            "u_attack_vector": "NETWORK"
        }]
    }]
}

cURL-opdracht

Type: GET

API:

curl -k -H "Authorization: <Authorization token>" "https://<IP Address>/external/v3/integration/devicecves/<timestamp>"

Voorbeeld:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://127.0.0.1/external/v3/integration/devicecves/1664781014000"

Volgende stappen

Zie voor meer informatie:

• Overzicht van naslaginformatie voor Defender for IoT API
• Zelfstudie: ServiceNow integreren met Microsoft Defender for IoT