Sensor- und Verwaltungskonsolen-APIs für Defender für IoT

Defender für IoT-APIs unterliegen der Microsoft-API-Lizenz und den Nutzungsbedingungen.

Verwenden Sie eine externe REST-API, um auf die von Sensoren und Verwaltungskonsolen ermittelten Daten zuzugreifen und Aktionen mit diesen Daten auszuführen.

Die Verbindungen sind durch SSL gesichert.

Generieren eines Token

Generell gilt: Wenn Sie eine externe API auf dem Microsoft Defender für IoT-Sensor oder der lokalen Verwaltungskonsole verwenden, müssen Sie ein Zugriffstoken generieren. Für Authentifizierungs-APIs, die Sie auf dem Sensor und in der lokalen Verwaltungskonsole verwenden, sind keine Token erforderlich.

So generieren Sie ein Token

  1. Wählen Sie im Fenster Systemeinstellungen die Option Integrationen>Zugriffstoken aus.
  2. Wählen Sie Generate token (Token generieren) aus.
  3. Beschreiben Sie unter Beschreibung, wofür das neue Token vorgesehen ist, und wählen Sie Generieren aus.
  4. Das Zugriffstoken wird angezeigt. Kopieren Sie das Token, da es nicht noch einmal angezeigt wird.
  5. Wählen Sie Fertig stellen aus.
    • Die von Ihnen erstellten Token werden im Dialogfeld Zugriffstoken angezeigt. Verwendet gibt den letzten Zeitpunkt an, zu dem ein externer Aufruf mit diesem Token empfangen wurde.
    • N/V im Feld Verwendet gibt an, dass die Verbindung zwischen dem Sensor und dem verbundenen Server nicht funktioniert.

Fügen Sie nach dem Generieren des Tokens Ihrer Anforderung einen HTTP-Header mit dem Titel Autorisierung hinzu, und legen Sie den Wert auf das von Ihnen generierte Token fest.

Sensor-APIs

Keine Version

Version 1

Version 2

Überprüfen von Benutzeranmeldeinformationen: /api/external/authentication/validation

Mit dieser API können Sie einen Namen und das Kennwort eines Benutzers von Defender für IoT überprüfen. Alle Defender für IoT-Benutzerrollen können mit der API arbeiten.

Zum Verwenden dieser API benötigen Sie kein Defender für IoT-Zugriffstoken.

Methode

  • POST

Anforderungstyp

  • JSON

Abfrageparameter

Name Typ Nullwerte zulässig
username String Nein
password String Nein

Anforderungsbeispiel

request:

{

    "username": "test",
    
    "password": "Test12345\!"

}

Antworttyp

  • JSON

Antwortinhalt

Meldungszeichenfolge mit Details zum Vorgangsstatus:

  • Success – Meldung: Authentifizierung erfolgreich

  • Failure – Fehler: Fehler beim Überprüfen der Anmeldeinformationen

Antwortbeispiel

response:

{

    "msg": "Authentication succeeded."

}

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/external/authentication/validation curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/external/authentication/validation

Ändern des Kennworts: /external/authentication/set_password

Mit dieser API können Sie Benutzern ermöglichen, ihre eigenen Kennwörter zu ändern. Alle Defender für IoT-Benutzerrollen können mit der API arbeiten. Zum Verwenden dieser API benötigen Sie kein Defender für IoT-Zugriffstoken.

Methode

  • POST

Anforderungstyp

  • JSON

Anforderungsbeispiel

request:

{

    "username": "test",
    
    "password": "Test12345\!",
    
    "new_password": "Test54321\!"

}

Antworttyp

  • JSON

Antwortinhalt

Meldungszeichenfolge mit Details zum Vorgangsstatus:

  • Success – Meldung: Das Kennwort wurde ersetzt

  • Failure – Fehler: Fehler bei der Benutzerauthentifizierung

  • Failure – Fehler: Das Kennwort entspricht nicht der Sicherheitsrichtlinie

Antwortbeispiel

response:

{

    "error": {
    
        "userDisplayErrorMessage": "User authentication failure"
    
    }

}

Gerätefelder

Name Typ Nullwerte zulässig
username String Nein
password String Nein
new_password String Nein

Curl-Befehl

type APIs Beispiel
POST curl -k -d '{"username": "<USER_NAME>","password": "<CURRENT_PASSWORD>","new_password": "<NEW_PASSWORD>"}' -H 'Content-Type: application/json' https://<IP_ADDRESS>/api/external/authentication/set_password curl -k -d '{"username": "myUser","password": "1234@abcd","new_password": "abcd@1234"}' -H 'Content-Type: application/json' https://127.0.0.1/api/external/authentication/set_password

Aktualisieren von Benutzerkennwörtern durch den Systemadministrator: /external/authentication/set_password_by_admin

Mit dieser API können Sie Systemadministratoren ermöglichen, die Kennwörter für bestimmte Benutzer zu ändern. Defender für IoT-Administratorrollen können mit der API arbeiten. Zum Verwenden dieser API benötigen Sie kein Defender für IoT-Zugriffstoken.

Methode

  • POST

Anforderungstyp

  • JSON

Anforderungsbeispiel

request:

{

    "username": "test",
    
    "password": "Test12345\!",
    
    "new_password": "Test54321\!"

}

Antworttyp

  • JSON

Antwortinhalt

Meldungszeichenfolge mit Details zum Vorgangsstatus:

  • Success – Meldung: Das Kennwort wurde ersetzt

  • Failure – Fehler: Fehler bei der Benutzerauthentifizierung

  • Failure – Fehler: Benutzer ist nicht vorhanden

  • Failure – Fehler: Das Kennwort entspricht nicht der Sicherheitsrichtlinie

  • Failure – Fehler: Der Benutzer hat keine Berechtigung zum Ändern des Kennworts

Antwortbeispiel

response:

{

    "error": {
    
        "userDisplayErrorMessage": "The user 'test_user' doesn't exist",
        
        "internalSystemErrorMessage": "The user 'yoavfe' doesn't exist"
    
    }

}

Gerätefelder

Name Typ Nullwerte zulässig
admin_username String Nein
admin_password String Nein
username String Nein
new_password String Nein

Curl-Befehl

type APIs Beispiel
POST curl -k -d '{"admin_username":"<ADMIN_USERNAME>","admin_password":"<ADMIN_PASSWORD>","username": "<USER_NAME>","new_password": "<NEW_PASSWORD>"}' -H 'Content-Type: application/json' https://<IP_ADDRESS>/api/external/authentication/set_password_by_admin curl -k -d '{"admin_user":"adminUser","admin_password": "1234@abcd","username": "myUser","new_password": "abcd@1234"}' -H 'Content-Type: application/json' https://127.0.0.1/api/external/authentication/set_password_by_admin

Abrufen von Geräteverbindungsinformationen: /api/v1/devices/connections

Verwenden Sie diese API, um eine Liste aller Verbindungen pro Gerät anzufordern.

Methode

  • GET

Abfrageparameter

Wenn Sie keine Abfrageparameter festlegen, werden alle Geräteverbindungen zurückgegeben.

Beispiel:

/api/v1/devices/connections

  • deviceId: Zum Filtern nach einer bestimmten Geräte-ID, um die zugehörigen Verbindungen anzuzeigen.

    Beispiel:

    /api/v1/devices/<deviceId>/connections

  • lastActiveInMinutes: Der Zeitrahmen in Minuten (von jetzt an rückwärts), in dem die Verbindungen aktiv waren.

    Beispiel:

    /api/v1/devices/2/connections?lastActiveInMinutes=20

  • discoveredBefore: Filtert nur Verbindungen, die vor einem bestimmten Zeitpunkt erkannt wurden (in Millisekunden, UTC).

    Beispiel:

    /api/v1/devices/2/connections?discoveredBefore=<epoch>

  • discoveredAfter: Filtert nur Verbindungen, die nach einem bestimmten Zeitpunkt erkannt wurden (in Millisekunden, UTC).

    Beispiel:

    /api/v1/devices/2/connections?discoveredAfter=<epoch>

Antworttyp

  • JSON

Antwortinhalt

Array von JSON-Objekten, die Geräteverbindungen darstellen.

Felder

Name Typ Nullwerte zulässig Liste der Werte
firstDeviceId Numeric Nein -
secondDeviceId Numeric Nein -
lastSeen Numeric Nein Epoche (UTC)
discovered Numeric Nein Epoche (UTC)
ports Zahlenarray Nein -
protocols JSON-Array Nein Protokollfeld

Protokollfeld

Name Typ Nullwerte zulässig Liste der Werte
name String Nein -
commands Zeichenfolgenarray Nein -

Antwortbeispiel

[

    {
    
        "firstDeviceId": 171,
        
        "secondDeviceId": 22,
        
        "lastSeen": 1511281457933,
        
        "discovered": 1511872830000,
        
        "ports": [
        
            502
        
        ],
    
        "protocols": [
        
        {
        
            name: "modbus",
            
            commands: [
            
                "Read Coils"
        
            ]
        
        },
    
        {
        
            name: "ams",
            
            commands: [
            
                "AMS Write"
        
            ]
        
        },
    
        {
        
            name: "http",
            
            commands: [
        
            ]
        
        }
    
    ]
    
    },
    
    {
    
        "firstDeviceId": 171,
        
        "secondDeviceId": 23,
        
        "lastSeen": 1511281457933,
        
        "discovered": 1511872830000,
        
        "ports": [
        
            502
        
        ],
        
        "protocols": [
        
            {
            
                name: "s7comm",
                
                commands: [
                
                    "Download block",
                    
                    "Upload"
            
                ]
            
            }
        
        ]
    
    }

]

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/connections curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/connections
GET curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/devices/<deviceId>/connections?lastActiveInMinutes=&discoveredBefore=&discoveredAfter=' curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/devices/2/connections?lastActiveInMinutes=20&discoveredBefore=1594550986000&discoveredAfter=1594550986000'

Abrufen von Informationen zu CVEs: /api/v1/devices/cves

Mit dieser API können Sie eine Liste aller bekannten CVEs anfordern, die auf Geräten im Netzwerk erkannt werden.

Methode

  • GET

Abfrageparameter

Standardmäßig stellt diese API eine Liste mit allen IP-Adressen von Geräten mit CVEs und für jede IP-Adresse bis zu 100 CVEs mit den höchsten Bewertungskennzahlen bereit.

Beispiel:

/api/v1/devices/cves

  • deviceId: Zum Filtern nach einer bestimmten Geräte-IP-Adresse, um bis zu 100 CVEs mit den höchsten Bewertungskennzahlen auf dem jeweiligen Gerät zu ermitteln.

    Beispiel:

    /api/v1/devices/<ipAddress>/cves

  • top: Gibt an, wie viele CVEs mit den höchsten Bewertungskennzahlen für jede Geräte-IP-Adresse abgerufen werden.

    Beispiel:

    /api/v1/devices/cves?top=50

    /api/v1/devices/<ipAddress>/cves?top=50

Antworttyp

  • JSON

Antwortinhalt

Array von JSON-Objekten, welche die unter den IP-Adressen identifizierten CVEs darstellen.

Felder

Name Typ Nullwerte zulässig Liste der Werte
cveId String Nein -
ipAddress String Nein IP-Adresse
score String Nein 0,0-10,0
attackVector String Nein Network, Adjacent Network, Local oder Physical (Netzwerk, angrenzendes Netzwerk, lokal oder physisch)
description String Nein -

Antwortbeispiel

[

    {
    
        "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 in Internet Explorer 6 and other
        
        applications, allows remote attackers to execute arbitrary
        
        code or cause a denial of service (application crash) via many
        
        nested tags in an XML document in an IFRAME, when synchronous
        
        document rendering is frequently disrupted with asynchronous
        
        events, as demonstrated using a JavaScript timer, which can
        
        trigger NULL pointer dereferences or memory corruption, aka
        
        \"MSXML Memory Corruption Vulnerability.\""
    
    },
    
    {
    
        "cveId": "CVE-2009-1547",
        
        "score": "9.3",
        
        "ipAddress": "10.35.1.51",
        
        "attackVector": "NETWORK",
        
        "description": "Unspecified vulnerability in Microsoft Internet Explorer 5.01
        
        SP4, 6, 6 SP1, and 7 allows remote attackers to execute
        
        arbitrary code via a crafted data stream header that triggers
        
        memory corruption, aka \"Data Stream Header Corruption
        
        Vulnerability.\""
    
    }

]

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/cves curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/cves
GET curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/<deviceIpAddress>/cves?top= curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/10.10.10.15/cves?top=50

Abrufen von Informationen zu Warnungen: /api/v1/alerts

Mit dieser API können Sie eine Liste aller Warnungen anfordern, die vom Defender für IoT-Sensor erkannt wurden.

Methode

  • GET

Abfrageparameter

  • state: Filtert nur nach bearbeiteten und unbearbeiteten Warnungen.

    Beispiel:

    /api/v1/alerts?state=handled

  • fromTime: Zum Filtern von Warnungen, die zu einem bestimmten Zeitpunkt erstellt wurden (in Millisekunden, UTC).

    Beispiel:

    /api/v1/alerts?fromTime=<epoch>

  • toTime: Zum Filtern von Warnungen, die vor einem bestimmten Zeitpunkt erstellt wurden (in Millisekunden, UTC).

    Beispiel:

    /api/v1/alerts?toTime=<epoch>

  • type: Zum Filtern von Warnungen nach einem bestimmten Typ. Vorhandene zum Filtern verfügbare Typen: unerwartete neue Geräte, Verbindungstrennungen.

    Beispiel:

    /api/v1/alerts?type=disconnections

Antworttyp

  • JSON

Antwortinhalt

Array von JSON-Objekten, die Warnungen darstellen.

Warnungsfelder

Name Typ Nullwerte zulässig Liste der Werte
ID Numeric Nein -
time Numeric Nein Epoche (UTC)
title String Nein -
Nachricht String Nein -
severity String Nein Warning, Minor, Major oder Critical (Warnung, gering, wichtig oder kritisch)
engine String Nein Protocol Violation, Policy Violation, Malware, Anomaly oder Operational (Protokollverletzung, Richtlinienverletzung, Malware, Anomalie oder Betrieb)
sourceDevice Numeric Ja Geräte-ID
destinationDevice Numeric Ja Geräte-ID
sourceDeviceAddress Numeric Ja IP, MAC
destinationDeviceAddress Numeric Ja IP, MAC
remediationSteps String Ja In der Warnung beschriebene Schritte zur Korrektur
additionalInformation Zusätzliches Informationsobjekt Ja -

Beachten Sie, dass für die folgenden Informationen „/api/v2/“ erforderlich ist:

  • sourceDeviceAddress
  • destinationDeviceAddress
  • remediationSteps

Zusätzliche Informationsfelder

Name Typ Nullwerte zulässig Liste der Werte
description String Nein -
information JSON-Array Nein String

Antwortbeispiel

[

    {
    
        "engine": "Policy Violation",
        
        "severity": "Major",
        
        "title": "Internet Access Detected",
        
        "additionalinformation": {
        
            "information": [
            
                "170.60.50.201 over port BACnet (47808)"
            
            ],
            
            "description": "External Addresses"
        
        },
    
        "sourceDevice": null,
        
        "destinationDevice": null,
        
        "time": 1509881077000,
        
        "message": "Device 192.168.0.13 tried to access an external IP address which is an address in the Internet and is not allowed by policy. It is recommended to notify the security officer of the incident.",
        
        "id": 1
    
    },
    
    {
    
        "engine": "Protocol Violation",
        
        "severity": "Major",
        
        "title": "Illegal MODBUS Operation (Exception Raised by Master)",
        
        "sourceDevice": 3,
        
        "destinationDevice": 4,
        
        "time": 1505651605000,
        
        "message": "A MODBUS master 192.168.110.131 attempted to initiate an illegal operation.\nThe operation is considered to be illegal since it incorporated function code \#129 which should not be used by a master.\nIt is recommended to notify the security officer of the incident.",
        
        "id": 2,
        
        "additionalInformation": null,
    
    }

]

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/alerts?state=&fromTime=&toTime=&type=' curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/alerts?state=unhandled&fromTime=1594550986000&toTime=1594550986001&type=disconnections'

Abrufen von Zeitachsenereignissen: /api/v1/events

Mit dieser API können Sie eine Liste der Ereignisse anfordern, die an die Ereigniszeitachse gemeldet wurden.

Methode

  • GET

Abfrageparameter

  • minutesTimeFrame: Der Zeitrahmen in Minuten (von jetzt an rückwärts), in dem die Ereignisse gemeldet wurden.

    Beispiel:

    /api/v1/events?minutesTimeFrame=20

  • type: Zum Filtern der Ereignisliste nach einem bestimmten Typ.

    Beispiele:

    /api/v1/events?type=DEVICE_CONNECTION_CREATED

    /api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame

Antworttyp

  • JSON

Antwortinhalt

Array von JSON-Objekten, die Warnungen darstellen.

Ereignisfelder

Name Typ Nullwerte zulässig Liste der Werte
timestamp Numeric Nein Epoche (UTC)
title String Nein -
severity String Nein INFO, NOTICE oder ALERT (Information, Hinweis oder Warnung)
owner String Ja Wenn das Ereignis manuell erstellt wurde, enthält dieses Feld den Namen des Benutzers, der das Ereignis erstellt hat
content String Nein -

Antwortbeispiel

[

    {
    
        "severity": "INFO",
        
        "title": "Back to Normal",
        
        "timestamp": 1504097077000,
        
        "content": "Device 10.2.1.15 was found responsive, after being suspected as disconnected",
        
        "owner": null,
        
        "type": "BACK_TO_NORMAL"
    
    },
    
    {
    
        "severity": "ALERT",
        
        "title": "Alert Detected",
        
        "timestamp": 1504096909000,
        
        "content": "Device 10.2.1.15 is suspected to be disconnected (unresponsive).",
        
        "owner": null,
        
        "type": "ALERT_REPORTED"
    
    },
    
    {
    
        "severity": "ALERT",
        
        "title": "Alert Detected",
        
        "timestamp": 1504094446000,
        
        "content": "A DNP3 Master 10.2.1.14 attempted to initiate a request which is not allowed by policy.\nThe policy indicates the allowed function codes, address ranges, point indexes and time intervals.\nIt is recommended to notify the security officer of the incident.",
        
        "owner": null,
        
        "type": "ALERT_REPORTED"
    
    },
    
    {
    
        "severity": "NOTICE",
        
        "title": "PLC Program Update",
        
        "timestamp": 1504094344000,
        
        "content": "Program update detected, sent from 10.2.1.25 to 10.2.1.14",
        
        "owner": null,
        
        "type": "PROGRAM_DEVICE"
    
    }

]

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/events?minutesTimeFrame=&type=' curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/events?minutesTimeFrame=20&type=DEVICE_CONNECTION_CREATED'

Abrufen von Informationen zu Sicherheitsrisiken: /api/v1/reports/vulnerabilities/devices

Mit dieser API können Sie die Ergebnisse der Sicherheitsrisikobewertung für jedes Gerät anfordern.

Methode

  • GET

Antworttyp

  • JSON

Antwortinhalt

Array von JSON-Objekten, welche die Geräte darstellen, auf die zugegriffen wurde.

Das Geräteobjekt hat folgenden Inhalt:

  • Allgemeine Daten

  • Bewertungskennzahl

  • Sicherheitsrisiken

Gerätefelder

Name Typ Nullwerte zulässig Liste der Werte
name String Nein -
ipAddresses JSON-Array Nein -
securityScore Numeric Nein -
vendor String Ja
firmwareVersion String Ja -
model String Ja -
isWirelessAccessPoint Boolesch Nein „true“ oder „false“
operatingSystem Betriebssystemobjekt Ja -
vulnerabilities Sicherheitsrisikoobjekt Ja -

Betriebssystemfelder

Name Typ Nullwerte zulässig Liste der Werte
Name String Ja -
Type String Ja -
Version String Ja -
latestVersion String Ja -

Sicherheitsrisikofelder

Name Typ Nullwerte zulässig Liste der Werte
antiViruses JSON-Array Ja Namen der Virenschutzprogramme
plainTextPasswords JSON-Array Ja Kennwortobjekte
remoteAccess JSON-Array Ja Remotezugriffobjekte
isBackupServer Boolesch Nein „true“ oder „false“
openedPorts JSON-Array Ja „Geöffneter Port“-Objekte
isEngineeringStation Boolesch Nein „true“ oder „false“
isKnownScanner Boolesch Nein „true“ oder „false“
cves JSON-Array Ja CVE-Objekte
isUnauthorized Boolesch Nein „true“ oder „false“
malwareIndicationsDetected Boolesch Nein „true“ oder „false“
weakAuthentication JSON-Array Ja Erkannte Anwendungen, die eine schwache Authentifizierung verwenden

Kennwortfelder

Name Typ Nullwerte zulässig Liste der Werte
password String Nein -
protocol String Nein -
strength String Nein Very weak, Weak, Medium oder Strong (sehr schwach, schwach, mittel, sicher)

Felder für den Remotezugriff

Name Typ Nullwerte zulässig Liste der Werte
port Numeric Nein -
transport String Nein TCP oder UDP
client String Nein IP-Adresse
clientSoftware String Nein SSH, VNC, Remotedesktop oder Teamviewer

„Geöffneter Port“-Felder

Name Typ Nullwerte zulässig Liste der Werte
port Numeric Nein -
transport String Nein TCP oder UDP
protocol String Ja -
isConflictingWithFirewall Boolesch Nein „true“ oder „false“

CVE-Felder

Name Typ Nullwerte zulässig Liste der Werte
ID String Nein -
score Numeric Nein Double
description String Nein -

Antwortbeispiel

[

    {
    
        "name": "IED \#10",
        
        "ipAddresses": ["10.2.1.10"],
        
        "securityScore": 100,
        
        "vendor": "ABB Switzerland Ltd, Power Systems",
        
        "firmwareVersion": null,
        
        "model": null,
        
        "operatingSystem": {
        
            "name": "ABB Switzerland Ltd, Power Systems",
            
            "type": "abb",
            
            "version": null,
            
            "latestVersion": null
        
        },
        
        "vulnerabilities": {
            
        "antiViruses": [
            
        "McAfee"
            
        ],
            
        "plainTextPasswords": [
            
            {
            
                "password": "123456",
                
                "protocol": "HTTP",
                
                "lastSeen": 1462726930471,
                
                "strength": "Very Weak"
            
            }
            
        ],
            
        "remoteAccess": [
            
            {
            
                "port": 5900,
                
                "transport": "TCP",
                
                "clientSoftware": "VNC",
                
                "client": "10.2.1.20"
            
            }
            
        ],
            
        "isBackupServer": true,
            
        "openedPorts": [
            
            {
            
                "port": 445,
                
                "transport": "TCP",
                
                "protocol": "SMP Over IP",
                
                "isConflictingWithFirewall": false
            
            },
            
            {
            
                "port": 80,
                
                "transport": "TCP",
                
                "protocol": "HTTP",
                
                "isConflictingWithFirewall": false
            
            }
            
        ],
            
        "isEngineeringStation": false,
            
        "isKnownScanner": false,
            
        "cves": [
            
            {
            
                "id": "CVE-2015-6490",
                
                "score": 10,
                
                "description": "Frosty URL - Stack-based buffer overflow on Allen-Bradley MicroLogix 1100 devices before B FRN 15.000 and 1400 devices through B FRN 15.003 allows remote attackers to execute arbitrary code via unspecified vectors"
            
            },
            
            {
            
                "id": "CVE-2012-6437",
                
                "score": 10,
                
                "description": "MicroLogix 1100 and 1400 do not properly perform authentication for Ethernet firmware updates, which allows remote attackers to execute arbitrary code via a Trojan horse update image"
            
            },
            
            {
            
                "id": "CVE-2012-6440",
                
                "score": 9.3,
                
                "description": "MicroLogix 1100 and 1400 allows man-in-the-middle attackers to conduct replay attacks via HTTP traffic."
        
            }
        
        ],
        
        "isUnauthorized": false,
        
        "malwareIndicationsDetected": true
        
        }
    
    }

]

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/devices curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/devices

Abrufen von Sicherheitsrisiken: /api/v1/reports/vulnerabilities/security

Mit dieser API können Sie die Ergebnisse einer allgemeinen Sicherheitsrisikobewertung anfordern. Mit dieser Bewertung werden Erkenntnisse zur Sicherheitsstufe Ihres Systems bereitgestellt.

Diese Bewertung basiert auf allgemeinen Netzwerk- und Systeminformationen und nicht auf der Auswertung eines bestimmten Geräts.

Methode

  • GET

Antworttyp

  • JSON

Antwortinhalt

JSON-Objekt, das bewertete Ergebnisse darstellt. Jeder Schlüssel kann Nullwerte zulassen. Andernfalls enthält er ein JSON-Objekt mit Schlüsseln, die keine Nullwerte zulassen.

Ergebnisfelder

  • Schlüssel

    unauthorizedDevices

    Feldname Typ Liste der Werte
    address String IP-Adresse
    name String -
    firstDetectionTime Numeric Epoche (UTC)
    lastSeen Numeric Epoche (UTC)

    illegalTrafficByFirewallRules

    Feldname Typ Liste der Werte
    server String IP-Adresse
    client String IP-Adresse
    port Numeric -
    transport String TCP, UDP oder ICMP

    weakFirewallRules

    Feldname Typ Liste der Werte
    sources JSON-Array der Quellen. Jede Quelle kann in einem von vier Formaten vorliegen: „Any“ (Beliebig), „IP-Adresse (Host)“, „Von IP-Adresse bis IP-Adresse (BEREICH)“, „IP-Adresse, Subnetzmaske (NETZWERK)“
    destinations JSON-Array der Ziele. Jedes Ziel kann in einem von vier Formaten vorliegen: „Any“ (Beliebig), „IP-Adresse (Host)“, „Von IP-Adresse bis IP-Adresse (BEREICH)“, „IP-Adresse, Subnetzmaske (NETZWERK)“
    ports JSON-Array der Ports in einem von drei Formaten: „Any“ (Beliebig), „Port (Protokoll, falls erkannt)“, „Von Port bis Port (Protokoll, falls erkannt)“

    accessPoints

    Feldname Typ Liste der Werte
    macAddress String MAC-Adresse
    vendor String Herstellername
    ipAddress String IP-Adresse oder N/V
    name String Gerätename oder N/V
    wireless String No, Suspected oder Yes (Nein, Vermutet oder Ja)

    connectionsBetweenSubnets

    Feldname Typ Liste der Werte
    server String IP-Adresse
    client String IP-Adresse

    industrialMalwareIndicators

    Feldname Typ Liste der Werte
    detectionTime Numeric Epoche (UTC)
    alertMessage String -
    description String -
    devices JSON-Array Gerätenamen

    internetConnections

    Feldname Typ Liste der Werte
    internalAddress String IP-Adresse
    authorized Boolean Ja oder Nein
    externalAddresses JSON-Array IP-Adresse

Antwortbeispiel

{

    "unauthorizedDevices": [
    
        {
        
            "address": "10.2.1.14",
            
            "name": "PLC \#14",
            
            "firstDetectionTime": 1462645483000,
            
            "lastSeen": 1462645495000,
        
        }
    
    ],
    
    "redundantFirewallRules": [
    
        {
        
            "sources": "170.39.3.0/255.255.255.0",
            
            "destinations": "Any",
            
            "ports": "102"
        
        }
    
    ],
    
    "connectionsBetweenSubnets": [
    
        {
        
            "server": "10.2.1.22",
            
            "client": "170.39.2.0"
        
        }
    
    ],
    
    "industrialMalwareIndications": [
    
        {
        
            "detectionTime": 1462645483000,
            
            "alertMessage": "Suspicion of Malicious Activity (Regin)",
            
            "description": "Suspicious network activity was detected. Such behavior might be attributed to the Regin malware.",
            
            "addresses": [
            
                "10.2.1.4",
                
                "10.2.1.5"
            
            ]
        
        }
    
    ],
    
    "illegalTrafficByFirewallRules": [
    
        {
        
            "server": "10.2.1.7",
            
            "port": "20000",
            
            "client": "10.2.1.4",
            
            "transport": "TCP"
        
        },
    
        {
        
            "server": "10.2.1.8",
            
            "port": "20000",
            
            "client": "10.2.1.4",
            
            "transport": "TCP"
        
        },
    
        {
        
            "server": "10.2.1.9",
            
            "port": "20000",
            
            "client": "10.2.1.4",
            
            "transport": "TCP"
        
        }
    
    ],
    
    "internetConnections": [
    
        {
        
            "internalAddress": "10.2.1.1",
            
            "authorized": "Yes",
            
            "externalAddresses": ["10.2.1.2",”10.2.1.3”]
        
        }
    
    ],
    
    "accessPoints": [
    
        {
        
            "macAddress": "ec:08:6b:0f:1e:22",
            
            "vendor": "TP-LINK TECHNOLOGIES",
            
            "ipAddress": "173.194.112.22",
            
            "name": "Enterprise AP",
            
            "wireless": "Yes"
        
        }
    
    ],
    
    "weakFirewallRules": [
    
        {
        
            "sources": "170.39.3.0/255.255.255.0",
            
            "destinations": "Any",
            
            "ports": "102"
        
        }
    
    ]

}

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/security curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/security

Abrufen von betrieblichen Sicherheitsrisiken: /api/v1/reports/vulnerabilities/operational

Mit dieser API können Sie die Ergebnisse einer allgemeinen Sicherheitsrisikobewertung anfordern. Mit dieser Bewertung werden Erkenntnisse zum Betriebsstatus Ihres Netzwerks bereitgestellt. Diese Bewertung basiert auf allgemeinen Netzwerk- und Systeminformationen und nicht auf der Auswertung eines bestimmten Geräts.

Methode

  • GET

Antworttyp

  • JSON

Antwortinhalt

JSON-Objekt, das bewertete Ergebnisse darstellt. Jeder Schlüssel enthält ein JSON-Array der Ergebnisse.

Ergebnisfelder

  • Keys

    backupServer

    Feldname Typ Liste der Werte
    Quelle String IP-Adresse
    destination String IP-Adresse
    port Numeric -
    transport String TCP oder UDP
    backupMaximalInterval String -
    lastSeenBackup Numeric Epoche (UTC)

    ipNetworks

    Feldname Typ Liste der Werte
    addresses Numeric -
    network String IP-Adresse
    mask String Subnetzmaske

    protocolProblems

    Feldname Typ Liste der Werte
    protocol String -
    addresses JSON-Array IP-Adressen
    alert String -
    reportTime Numeric Epoche (UTC)

    protocolDataVolumes

    Feldname Typ Liste der Werte
    Protokoll String -
    Volume String „Volumenummer, MB“

    disconnections

    Feldname Typ Liste der Werte
    assetAddress String IP-Adresse
    assetName String -
    lastDetectionTime Numeric Epoche (UTC)
    backToNormalTime Numeric Epoche (UTC)

Antwortbeispiel

{

    "backupServer": [
    
        {
        
            "backupMaximalInterval": "1 Hour, 29 Minutes",
            
            "source": "10.2.1.22",
            
            "destination": "170.39.2.14",
            
            "port": 10000,
            
            "transport": "TCP",
            
            "lastSeenBackup": 1462645483000
        
        }
    
    ],

    "ipNetworks": [
    
        {
        
            "addresses": "21",
            
            "network": "10.2.1.0",
            
            "mask": "255.255.255.0"
        
        },
        
        {
        
            "addresses": "3",
            
            "network": "170.39.2.0",
            
            "mask": "255.255.255.0"
        
        }
    
    ],

    "protocolProblems": [
    
        {
        
            "protocol": "DNP3",
            
            "addresses": [
            
                "10.2.1.7",
                
                "10.2.1.8"
            
            ],
            
            "alert": "Illegal DNP3 Operation",
            
            "reportTime": 1462645483000
        
        },
        
        {
        
            "protocol": "DNP3",
            
            "addresses": [
            
                "10.2.1.15"
            
            ],
            
            "alert": "Master Requested an Application Layer Confirmation",
            
            "reportTime": 1462645483000
        
        }
        
    ],

    "protocolDataVolumes": [
    
        {
        
            "protocol": "MODBUS (502)",
            
            "volume": "21.07 MB"
        
        },
        
        {
        
            "protocol": "SSH (22)",
            
            "volumn": "0.001 MB"
        
        }
    
    ],
    
    "disconnections": [
    
        {
        
            "assetAddress": "10.2.1.3",
            
            "assetName": "PLC \#3",
            
            "lastDetectionTime": 1462645483000,
            
            "backToNormalTime": 1462645484000
        
        }
    
    ]

}

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/operational curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/operational

Abrufen von Warnungs-PCAP: /api/v2/alerts/pcap

Verwenden Sie diese API, um eine PCAP-Datei im Zusammenhang mit einer Warnung abzurufen.

Dieser Endpunkt verwendet kein reguläres Zugriffstoken für die Autorisierung. Stattdessen ist ein spezielles Token erforderlich, das vom /external/v2/alerts/pcap-API-Endpunkt in der CM erstellt wird.

Methode

  • GET

Abfrageparameter

  • id: Xsense-Warnungs-ID
    Beispiel:
    /api/v2/alerts/pcap/<id>

Antworttyp

  • JSON

Antwortinhalt

  • Erfolgreich: Binärdatei mit PCAP-Daten
  • Fehler: JSON-Objekt, das eine Fehlermeldung enthält

Antwortbeispiel

Fehler

{
  "error": "PCAP file is not available"
}

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v2/alerts/pcap/<ID>' curl -k -H "Authorization: d2791f58-2a88-34fd-ae5c-2651fe30a63c" 'https://10.1.0.2/api/v2/alerts/pcap/1'

API der Verwaltungskonsole

In diesem Abschnitt werden die APIs der lokalen Verwaltungskonsole für Folgendes beschrieben:

Keine Version

Version 1

Version 2

Version 3

Warnungsausschlüsse

Legen Sie Bedingungen fest, bei denen keine Warnungen gesendet werden. Definieren und aktualisieren Sie beispielsweise die End- und Startzeiten, Geräte oder Subnetze, die beim Auslösen von Warnungen ausgeschlossen werden sollen, oder Defender für IoT-Engines, die nicht einbezogen werden sollen. Während eines Wartungsfensters können Sie beispielsweise die Übermittlung aller Warnungen mit Ausnahme von Malwarewarnungen auf wichtigen Geräten unterbrechen. Die hier definierten Elemente werden in der lokalen Verwaltungskonsole im Fenster „Warnungsausschlüsse“ als schreibgeschützte Ausschlussregeln angezeigt.

/external/v1/maintenanceWindow

  • /external/authentication/validation

  • Antwortbeispiel

  • Antwort:

{
    "msg": "Authentication succeeded."
}

Ändern des Kennworts: /external/authentication/set_password

Mit dieser API können Sie Benutzern ermöglichen, ihre eigenen Kennwörter zu ändern. Alle Defender für IoT-Benutzerrollen können mit der API arbeiten. Zum Verwenden dieser API benötigen Sie kein Defender für IoT-Zugriffstoken.

Methode

POST

Anforderungstyp

  • JSON

Anforderungsbeispiel

request:

{

    "username": "test",
    
    "password": "Test12345\!",
    
    "new_password": "Test54321\!"

}

Antworttyp

  • JSON

Antwortinhalt

Meldungszeichenfolge mit Details zum Vorgangsstatus:

  • Success – Meldung: Das Kennwort wurde ersetzt

  • Failure – Fehler: Fehler bei der Benutzerauthentifizierung

  • Failure – Fehler: Das Kennwort entspricht nicht der Sicherheitsrichtlinie

Antwortbeispiel

response:

{

    "error": {
    
        "userDisplayErrorMessage": "User authentication failure"
    
    }

}

Gerätefelder

Name Typ Nullwerte zulässig
username String Nein
password String Nein
new_password String Nein

Curl-Befehl

type APIs Beispiel
POST curl -k -d '{"username": "<USER_NAME>","password": "<CURRENT_PASSWORD>","new_password": "<NEW_PASSWORD>"}' -H 'Content-Type: application/json' https://<IP_ADDRESS>/external/authentication/set_password curl -k -d '{"username": "myUser","password": "1234@abcd","new_password": "abcd@1234"}' -H 'Content-Type: application/json' https://127.0.0.1/external/authentication/set_password

Aktualisieren von Benutzerkennwörtern durch den Systemadministrator: /external/authentication/set_password_by_admin

Mit dieser API können Sie Systemadministratoren ermöglichen, die Kennwörter für bestimmte Benutzer zu ändern. Defender für IoT-Administratorrollen können mit der API arbeiten. Zum Verwenden dieser API benötigen Sie kein Defender für IoT-Zugriffstoken.

Methode

  • POST

Anforderungstyp

  • JSON

Anforderungsbeispiel

request:

{

    "username": "test",
    
    "password": "Test12345\!",
    
    "new_password": "Test54321\!"

}

Antworttyp

  • JSON

Antwortinhalt

Meldungszeichenfolge mit Details zum Vorgangsstatus:

  • Success – Meldung: Das Kennwort wurde ersetzt

  • Failure – Fehler: Fehler bei der Benutzerauthentifizierung

  • Failure – Fehler: Benutzer ist nicht vorhanden

  • Failure – Fehler: Das Kennwort entspricht nicht der Sicherheitsrichtlinie

  • Failure – Fehler: Der Benutzer hat keine Berechtigung zum Ändern des Kennworts

Antwortbeispiel

response:

{

    "error": {
    
        "userDisplayErrorMessage": "The user 'test_user' doesn't exist",
        
        "internalSystemErrorMessage": "The user 'yoavfe' doesn't exist"
    
    }

}

Gerätefelder

Name Typ Nullwerte zulässig
admin_username String Nein
admin_password String Nein
username String Nein
new_password String Nein

Curl-Befehl

type APIs Beispiel
POST curl -k -d '{"admin_username":"<ADMIN_USERNAME>","admin_password":"<ADMIN_PASSWORD>","username": "<USER_NAME>","new_password": "<NEW_PASSWORD>"}' -H 'Content-Type: application/json' https://<IP_ADDRESS>/external/authentication/set_password_by_admin curl -k -d '{"admin_user":"adminUser","admin_password": "1234@abcd","username": "myUser","new_password": "abcd@1234"}' -H 'Content-Type: application/json' https://127.0.0.1/external/authentication/set_password_by_admin

QRadar-Warnungen

Die QRadar-Integration unterstützt Sie beim Identifizieren der von Defender für IoT generierten Aktionswarnungen. QRadar empfängt die Daten von Defender für IoT und kontaktiert dann die öffentliche API der lokalen Verwaltungskonsole.

Um die von Defender für IoT ermittelten Daten an QRadar zu senden, definieren Sie im Defender für IoT-System eine Weiterleitungsregel, und wählen Sie die Option Remoteunterstützung für Warnungsbearbeitung aus. Wenn diese Option ausgewählt ist, werden die folgenden zusätzlichen Felder in QRadar angezeigt:

  • UUID: Eindeutiger Warnungsbezeichner, z. B. 1-1555245116250.

  • Site: Der Standort, an dem die Warnung ermittelt wurde.

  • Zone: Die Zone, in der die Warnung ermittelt wurde.

Beispiel für die an QRadar gesendete Payload:

<9>May 5 12:29:23 sensor_Agent LEEF:1.0|CyberX|CyberX platform|2.5.0|CyberX platform Alert|devTime=May 05 2019 15:28:54 devTimeFormat=MMM dd yyyy HH:mm:ss sev=2 cat=XSense Alerts title=Device is Suspected to be Disconnected (Unresponsive) score=81 reporter=192.168.219.50 rta=0 alertId=6 engine=Operational senderName=sensor Agent UUID=5-1557059334000 site=Site zone=Zone actions=handle dst=192.168.2.2 dstName=192.168.2.2 msg=Device 192.168.2.2 is suspected to be disconnected (unresponsive).

Abrufen von Geräteinformationen: /api/v1/devices

Mit dieser API können Sie eine Liste aller Geräte anfordern, die von einem Defender für IoT-Sensor erkannt wurden.

Methode

  • GET

Fordert eine Liste aller Geräte an, die vom Defender für IoT-Sensor erkannt wurden.

Abfrageparameter

  • authorized: Filtert nur autorisierte und nicht autorisierte Geräte.

    Beispiele:

    /api/v1/devices?authorized=true

    /api/v1/devices?authorized=false

Antworttyp

  • JSON

Antwortinhalt

Array von JSON-Objekten, die Geräte darstellen.

Gerätefelder

Name Typ Nullwerte zulässig Liste der Werte
id Numeric Nein -
ipAddresses JSON-Array Ja IP-Adressen (können bei Internetadressen oder einem Gerät mit dualen Netzwerkkarten mehrere Adressen sein)
name String Nein -
type String Nein Unknown, Engineering Station, PLC, HMI, Historian, Domain Controller, DB Server, Wireless Access Point, Router, Switch, Server, Workstation, IP Camera, Printer, Firewall, Terminal station, VPN Gateway, Internet oder Multicast und Broadcast
macAddresses JSON-Array Ja MAC-Adressen (können bei einem Gerät mit dualen Netzwerkkarten mehrere Adressen sein)
operatingSystem String Ja -
engineeringStation Boolesch Nein „true“ oder „false“
scanner Boolesch Nein „true“ oder „false“
authorized Boolesch Nein „true“ oder „false“
vendor String Ja -
protocols JSON-Array Ja Protokollobjekt
firmware JSON-Array Ja Firmwareobjekt

Protokollfelder

Name Typ Nullwerte zulässig Liste der Werte
Name String Nein
Adresses JSON-Array Ja Master oder numerische Werte

Firmwarefelder

Name Typ Nullwerte zulässig Liste der Werte
serial String Nein N/V oder der tatsächliche Wert
model String Nein N/V oder der tatsächliche Wert
firmwareVersion Double Nein N/V oder der tatsächliche Wert
additionalData String Nein N/V oder der tatsächliche Wert
moduleAddress String Nein N/V oder der tatsächliche Wert
rack String Nein N/V oder der tatsächliche Wert
slot String Nein N/V oder der tatsächliche Wert
address String Nein N/V oder der tatsächliche Wert

Antwortbeispiel

[

    {
    
    "vendor": null,
    
    "name": "10.4.14.102",
    
    "firmware": [
    
        {
        
            "slot": "N/A",
            
            "additionalData": "N/A",
            
            "moduleAddress": "Network: Local network (0), Node: 0, Unit: CPU (0x0)",
            
            "rack": "N/A",
            
            "address": "10.4.14.102",
            
            "model": "AAAAAAAAAA",
            
            "serial": "N/A",
            
            "firmwareVersion": "20.55"
        
        },
    
        {
        
            "slot": "N/A",
            
            "additionalData": "N/A",
            
            "moduleAddress": "Network: Local network (0), Node: 0, Unit: Unknown (0x3)",
            
            "rack": "N/A",
            
            "address": "10.4.14.102",
            
            "model": "AAAAAAAAAAAAAAAAAAAA",
            
            "serial": "N/A",
            
            "firmwareVersion": "20.55"
        
        },
    
        {
        
            "slot": "N/A",
            
            "additionalData": "N/A",
            
            "moduleAddress": "Network: Local network (0), Node: 3, Unit: CPU (0x0)",
            
            "rack": "N/A",
            
            "address": "10.4.14.102",
            
            "model": "AAAAAAAAAAAAAAAAAAAA",
            
            "serial": "N/A",
            
            "firmwareVersion": "20.55"
        
        },
    
        {
        
            "slot": "N/A",
            
            "additionalData": "N/A",
            
            "moduleAddress": "Network: 3, Node: 0, Unit: CPU (0x0)",
            
            "rack": "N/A",
            
            "address": "10.4.14.102",
            
            "model": "AAAAAAAAAAAAAAAAAAAA",
            
            "serial": "N/A",
            
            "firmwareVersion": "20.55"
        
        }
    
    ],
    
    "id": 79,
    
    "macAddresses": null,
    
    "authorized": true,
    
    "ipAddresses": [
    
        "10.4.14.102"
    
    ],
    
    "engineeringStation": false,
    
    "type": "PLC",
    
    "operatingSystem": null,
    
    "protocols": [
    
        {
        
            "addresses": [],
            
            "id": 62,
            
            "name": "Omron FINS"
        
        }
    
    ],
    
    "scanner": false
    
}

]

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices?authorized=true

Authentifizieren von Benutzeranmeldeinformationen: /external/authentication/validation

Mit dieser API können Sie Benutzeranmeldeinformationen überprüfen. Alle Defender für IoT-Benutzerrollen können mit der API arbeiten. Zum Verwenden dieser API benötigen Sie kein Defender für IoT-Zugriffstoken.

Methode

POST

Anforderungstyp

  • JSON

Anforderungsbeispiel

request:

{

    "username": "test",

    "password": "Test12345\!"

}

Antworttyp

  • JSON

Antwortinhalt

Meldungszeichenfolge mit Details zum Vorgangsstatus:

  • Success – Meldung: Authentifizierung erfolgreich

  • Failure – Fehler: Fehler beim Überprüfen der Anmeldeinformationen

Gerätefelder

Name Typ Nullwerte zulässig
username String Nein
password String Nein

Antwortbeispiel

response:

{

    "msg": "Authentication succeeded."

}

Curl-Befehl

type APIs Beispiel
POST curl -k -d '{"username":"<USER_NAME>","password":"PASSWORD"}' 'https://<IP_ADDRESS>/external/authentication/validation' curl -k -d '{"username":"myUser","password":"1234@abcd"}' 'https://127.0.0.1/external/authentication/validation'

Abrufen von Geräteinformationen: /external/v1/devices

Diese API fordert eine Liste aller Geräte an, die von Defender für IoT-Sensoren, die mit einer lokalen Verwaltungskonsole verbunden sind, erkannt wurden.

Methode

  • GET

Antworttyp

  • JSON

Antwortinhalt

Array von JSON-Objekten, die Geräte darstellen.

Abfrageparameter

  • authorized: Filtert nur nach autorisierten und nicht autorisierten Geräten.

  • siteId: Filtert nur Geräte, die mit bestimmten Standorten verknüpft sind.

  • zoneId: Filtert nur Geräte, die mit bestimmten Zonen verknüpft sind. 1

  • sensorId: Filtert nur Geräte, die von bestimmten Sensoren erkannt wurden. 1

1Die Standort- und Zonen-IDs sind Ihnen möglicherweise nicht bekannt. Fragen Sie in diesem Fall alle Geräte ab, um die Standort- und Zonen-IDs abzurufen.

Beispiel für Abfrageparameter

/external/v1/devices?authorized=true

/external/v1/devices?authorized=false

/external/v1/devices?siteId=1,2

/external/v1/devices?zoneId=5,6

/external/v1/devices?sensorId=8

Gerätefelder

Name Typ Nullwerte zulässig Liste der Werte
sensorId Numeric Nein -
zoneId Numeric Ja -
siteId Numeric Ja -
ipAddresses JSON-Array Ja IP-Adressen (können bei Internetadressen oder einem Gerät mit dualen Netzwerkkarten mehrere Adressen sein)
name String Nein -
type String Nein Unknown, Engineering Station, PLC, HMI, Historian, Domain Controller, DB Server, Wireless Access Point, Router, Switch, Server, Workstation, IP Camera, Printer, Firewall, Terminal station, VPN Gateway, Internet oder Multicast und Broadcast
macAddresses JSON-Array Ja MAC-Adressen (können bei einem Gerät mit dualen Netzwerkkarten mehrere Adressen sein)
operatingSystem String Ja -
engineeringStation Boolesch Nein „true“ oder „false“
scanner Boolesch Nein „true“ oder „false“
authorized Boolesch Nein „true“ oder „false“
vendor String Ja -
Protokolle JSON-Array Ja Protokollobjekt
firmware JSON-Array Ja Firmwareobjekt

Protokollfelder

Name Typ Nullwerte zulässig Liste der Werte
Name String Nein -
Adressen JSON-Array Ja Master oder numerische Werte

Firmwarefelder

Name Typ Nullwerte zulässig Liste der Werte
serial String Nein N/V oder der tatsächliche Wert
model String Nein N/V oder der tatsächliche Wert
firmwareVersion Double Nein N/V oder der tatsächliche Wert
additionalData String Nein N/V oder der tatsächliche Wert
moduleAddress String Nein N/V oder der tatsächliche Wert
rack String Nein N/V oder der tatsächliche Wert
slot String Nein N/V oder der tatsächliche Wert
address String Nein N/V oder der tatsächliche Wert

Antwortbeispiel

[

    {
    
    "sensorId": 7,
    
    "zoneId": 1,
    
    "siteId": 1,
    
    "vendor": null,
    
    "name": "10.4.14.102",
    
    "firmware": [
    
    {
    
        "slot": "N/A",
        
        "additionalData": "N/A",
        
        "moduleAddress": "Network: Local network (0), Node: 0, Unit: CPU (0x0)",
        
        "rack": "N/A",
        
        "address": "10.4.14.102",
        
        "model": "AAAAAAAAAA",
        
        "serial": "N/A",
        
        "firmwareVersion": "20.55"
    
    },
    
    {
    
        "slot": "N/A",
        
        "additionalData": "N/A",
        
        "moduleAddress": "Network: Local network (0), Node: 0, Unit: Unknown (0x3)",
        
        "rack": "N/A",
        
        "address": "10.4.14.102",
        
        "model": "AAAAAAAAAAAAAAAAAAAA",
        
        "serial": "N/A",
        
        "firmwareVersion": "20.55"
    
    },
    
    {
    
        "slot": "N/A",
        
        "additionalData": "N/A",
        
        "moduleAddress": "Network: Local network (0), Node: 3, Unit: CPU (0x0)",
        
        "rack": "N/A",
        
        "address": "10.4.14.102",
        
        "model": "AAAAAAAAAAAAAAAAAAAA",
        
        "serial": "N/A",
        
        "firmwareVersion": "20.55"
    
    },
    
    {
    
        "slot": "N/A",
        
        "additionalData": "N/A",
        
        "moduleAddress": "Network: 3, Node: 0, Unit: CPU (0x0)",
        
        "rack": "N/A",
        
        "address": "10.4.14.102",
        
        "model": "AAAAAAAAAAAAAAAAAAAA",
        
        "serial": "N/A",
        
        "firmwareVersion": "20.55"
    
    }

],

"id": 79,

"macAddresses": null,

"authorized": true,

"ipAddresses": [

    "10.4.14.102"

],

"engineeringStation": false,

"type": "PLC",

"operatingSystem": null,

"protocols": [

    {
    
        "addresses": [],
        
        "id": 62,
        
        "name": "Omron FINS"
    
    }

],

"scanner": false

}

]

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/devices?siteId=&zoneId=&sensorId=&authorized=' curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/devices?siteId=1&zoneId=2&sensorId=5&authorized=true'

Abrufen von Informationen zu Warnungen: /external/v1/alerts

Mit dieser API können Sie alle oder gefilterte Warnungen von einer lokalen Verwaltungskonsole abrufen.

Methode

  • GET

Abfrageparameter

  • state: Filtert nur nach bearbeiteten und unbearbeiteten Warnungen.

    Beispiel:

    /api/v1/alerts?state=handled

  • fromTime: Zum Filtern von Warnungen, die zu einem bestimmten Zeitpunkt erstellt wurden (in Millisekunden, UTC).

    Beispiel:

    /api/v1/alerts?fromTime=<epoch>

  • toTime: Zum Filtern von Warnungen, die vor einem bestimmten Zeitpunkt erstellt wurden (in Millisekunden, UTC).

    Beispiel:

    /api/v1/alerts?toTime=<epoch>

  • siteId: Der Standort, an dem die Warnung erkannt wurde.

  • zoneId: Die Zone, in der die Warnung erkannt wurde.

  • sensor: Der Sensor, auf dem die Warnung erkannt wurde.

Die Standort- und Zonen-IDs sind Ihnen möglicherweise nicht bekannt. Fragen Sie in diesem Fall alle Geräte ab, um die Standort- und Zonen-IDs abzurufen.

Warnungsfelder

Name Typ Nullwerte zulässig Liste der Werte
ID Numeric Nein -
time Numeric Nein Epoche (UTC)
title String Nein -
Nachricht String Nein -
severity String Nein Warning, Minor, Major oder Critical (Warnung, gering, wichtig oder kritisch)
engine String Nein Protocol Violation, Policy Violation, Malware, Anomaly oder Operational (Protokollverletzung, Richtlinienverletzung, Malware, Anomalie oder Betrieb)
sourceDevice Numeric Ja Geräte-ID
destinationDevice Numeric Ja Geräte-ID
sourceDeviceAddress Numeric Ja IP, MAC
destinationDeviceAddress Numeric Ja IP, MAC
remediationSteps String Ja In der Warnung angezeigte Schritte zur Korrektur
sensorName String Ja Vom Benutzer definierter Name des Sensors
zoneName String Ja Name der Zone, die dem Sensor zugeordnet ist
siteName String Ja Name des Standorts, der dem Sensor zugeordnet ist
additionalInformation Zusätzliches Informationsobjekt Ja -

Beachten Sie, dass für die folgenden Informationen „/api/v2/“ erforderlich ist:

  • sourceDeviceAddress
  • destinationDeviceAddress
  • remediationSteps
  • sensorName
  • zoneName
  • siteName

Zusätzliche Informationsfelder

Name Typ Nullwerte zulässig Liste der Werte
description String Nein -
information JSON-Array Nein String

Antwortbeispiel

[
    {
        "engine": "Operational",
        "handled": false,
        "title": "Traffic Detected on sensor Interface",
        "additionalInformation": null,
        "sourceDevice": 0,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808245000,
        "sensorId": 1,
        "message": "The sensor resumed detecting network traffic on ens224.",
        "destinationDevice": 0,
        "id": 1,
        "severity": "Warning"
    },
    {
        "engine": "Anomaly",
        "handled": false,
        "title": "Address Scan Detected",
        "additionalInformation": null,
        "sourceDevice": 4,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808260000,
        "sensorId": 1,
        "message": "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident.",
        "destinationDevice": 0,
        "id": 2,
        "severity": "Critical"
    },
    {
        "engine": "Operational",
        "handled": false,
        "title": "Suspicion of Unresponsive MODBUS Device",
        "additionalInformation": null,
        "sourceDevice": 194,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808285000,
        "sensorId": 1,
        "message": "Outstation device 10.13.10.1 (Protocol Address 53) seems to be unresponsive to MODBUS requests.",
        "destinationDevice": 0,
        "id": 3,
        "severity": "Minor"
    }
]

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/alerts?state=&zoneId=&fromTime=&toTime=&siteId=&sensor=' curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/alerts?state=unhandled&zoneId=1&fromTime=0&toTime=1594551777000&siteId=1&sensor=1'

/external/v1/alerts/<UUID>

Methode

PUT

Anforderungstyp

  • JSON

Inhalt anfordern

JSON-Objekt, das die Aktion darstellt, die für die Warnung mit der UUID ausgeführt werden soll.

Aktionsfelder

Name Typ Nullwerte zulässig Liste der Werte
action String Nein „handle“ oder „handleAndLearn“

Anforderungsbeispiel

{
    "action": "handle"
}

Antworttyp

  • JSON

Antwortinhalt

Array von JSON-Objekten, die Geräte darstellen.

Antwortfelder

Name Typ Nullwerte zulässig BESCHREIBUNG
content/error String Nein Wenn die Anforderung erfolgreich ist, wird die Eigenschaft „content“ angezeigt. Andernfalls wird die Eigenschaft „error“ angezeigt.

Mögliche Werte für die Eigenschaft „content“

Statuscode Wert für „content“ BESCHREIBUNG
200 Die Aktualisierungsanforderung der Warnung wurde erfolgreich abgeschlossen. Die Aktualisierungsanforderung wurde erfolgreich abgeschlossen. Keine Kommentare.
200 Die Warnung wurde bereits bearbeitet (handle). Die Warnung wurde bereits bearbeitet, als eine „handle“-Anforderung für die Warnung empfangen wurde.
Die Warnung bleibt im Status handled.
200 Für die Warnung wurde bereits ein Bearbeitungs- und Lernvorgang durchgeführt (handleAndLearn). Für die Warnung wurde bereits ein Bearbeitungs- und Lernvorgang durchgeführt, als eine handleAndLearn-Anforderung empfangen wurde.
Die Warnung bleibt im Status handledAndLearn.
200 Die Warnung wurde bereits bearbeitet (handled).
Für die Warnung wurde bereits ein Bearbeitungs- und Lernvorgang (handleAndLearn) ausgeführt.
Die Warnung wurde bereits bearbeitet, als eine handleAndLearn-Anforderung empfangen wurde.
Die Warnung erhält den Status handleAndLearn.
200 Für die Warnung wurde bereits ein Bearbeitungs- und Lernvorgang durchgeführt (handleAndLearn). Die Bearbeitungsanforderung wurde ignoriert. Die Warnung befand sich bereits im Status handleAndLearn, als eine Anforderung zum Bearbeiten der Warnung empfangen wurde. Die Warnung bleibt im Status handleAndLearn.
500 Ungültige Aktion. Die gesendete Aktion ist keine gültige Aktion, die für die Warnung ausgeführt werden kann.
500 Unerwarteter Fehler. Ein unerwarteter Fehler ist aufgetreten. Wenden Sie sich an den technischen Support, um das Problem zu beheben.
500 Die Anforderung konnte nicht ausgeführt werden, da für diese UUID keine Warnung gefunden wurde. Die angegebene Warnungs-UUID wurde im System nicht gefunden.

Antwortbeispiel

Erfolgreich

{
    "content": "Alert update request finished successfully"
}

Nicht erfolgreich

{
    "error": "Invalid action"
}

o

Curl-Befehl

type APIs Beispiel
PUT curl -k -X PUT -d '{"action": "<ACTION>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/external/v1/alerts/<UUID> curl -k -X PUT -d '{"action": "handle"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/alerts/1-1594550943000

Warnungsausschlüsse (Wartungsfenster): /external/v1/maintenanceWindow

Legen Sie Bedingungen fest, bei denen keine Warnungen gesendet werden. Definieren und aktualisieren Sie beispielsweise die End- und Startzeiten, Geräte oder Subnetze, die beim Auslösen von Warnungen ausgeschlossen werden sollen, oder Defender für IoT-Engines, die nicht einbezogen werden sollen. Während eines Wartungsfensters können Sie beispielsweise die Übermittlung aller Warnungen mit Ausnahme von Malwarewarnungen auf wichtigen Geräten unterbrechen.

Die hier definierten APIs werden in der lokalen Verwaltungskonsole im Fenster Warnungsausschlüsse als schreibgeschützte Ausschlussregel angezeigt.

Methode: POST

Abfrageparameter

  • ticketId: Definiert die ID des Wartungstickets in den Systemen des Benutzers.

  • ttl: Definiert die Gültigkeitsdauer (Time to Live, TTL), welche die Dauer des Wartungsfensters in Minuten angibt. Nach dem Zeitraum, den dieser Parameter definiert, beginnt das System automatisch mit dem Senden von Warnungen.

  • engines: Definiert die Sicherheitsengine, deren Warnungen während des Wartungsvorgangs unterdrückt werden sollen:

    • ANOMALY

    • MALWARE

    • OPERATIONAL

    • POLICY_VIOLATION

    • PROTOCOL_VIOLATION

  • sensorIds: Definiert den Defender für IoT-Sensor, dessen Warnungen während des Wartungsvorgangs unterdrückt werden sollen. Dabei handelt es sich um dieselbe ID, die unter „/api/v1/appliances (GET)“ abgerufen wurde.

  • subnets: Definiert das Subnetz, aus dem Warnungen während des Wartungsvorgangs unterdrückt werden sollen: Das Subnetz wird in folgendem Format gesendet: 192.168.0.0/16.

Fehlercodes

  • 201 (Created) : Die Aktion wurde erfolgreich abgeschlossen.

  • 400 (Bad Request) : Wird in folgenden Fällen angezeigt:

    • Der Parameter ttl ist nicht numerisch oder nicht positiv.
    • Der Parameter subnets wurde in einem falschen Format definiert.
    • Der Parameter ticketId fehlt.
    • Der unter engine angegebene Parameter stimmt nicht mit den vorhandenen Sicherheitsengines überein.
  • 404 (Not Found) : Einer der Sensoren ist nicht vorhanden.

  • 409 (Conflict) : Die Ticket-ID ist mit einem anderen geöffneten Wartungsfenster verknüpft.

  • 500 (Internal Server Error) : Sonstiger unerwarteter Fehler.

Hinweis

Stellen Sie sicher, dass die Ticket-ID nicht mit einem vorhandenen geöffneten Wartungsfenster verknüpft ist. Die folgende Ausschlussregel wird generiert: Maintenance-{Tokenname}-{Ticket-ID}.

Methode: PUT

Durch Ändern des Parameters ttl können Sie die Dauer des Wartungsfensters aktualisieren, nachdem Sie den Wartungsvorgang gestartet haben. Die neue Definition der Dauer überschreibt die vorherige Definition.

Diese Methode ist hilfreich, wenn Sie anstelle der aktuell konfigurierten Dauer eine längere Zeitspanne festlegen möchten.

Abfrageparameter

  • ticketId: Definiert die ID des Wartungstickets in den Systemen des Benutzers.

  • ttl: Definiert die Dauer des Fensters in Minuten.

Fehlercode

  • 200 (OK) : Die Aktion wurde erfolgreich abgeschlossen.

  • 400 (Bad Request) : Wird in folgenden Fällen angezeigt:

    • Der Parameter ttl ist nicht numerisch oder nicht positiv.
    • Der Parameter ticketId fehlt.
    • Der Parameter ttl fehlt.
  • 404 (Not Found) : Die Ticket-ID ist nicht mit einem geöffneten Wartungsfenster verknüpft.

  • 500 (Internal Server Error) : Sonstiger unerwarteter Fehler.

Hinweis

Stellen Sie sicher, dass die Ticket-ID mit einem vorhandenen geöffneten Wartungsfenster verknüpft ist.

Methode: DELETE

Schließt ein vorhandenes Wartungsfenster.

Abfrageparameter

  • ticketId: Protokolliert die ID des Wartungstickets in den Systemen des Benutzers.

Fehlercode

  • 200 (OK) : Die Aktion wurde erfolgreich abgeschlossen.

  • 400 (Bad Request) : Der Parameter ticketId fehlt.

  • 404 (Not Found) : Die Ticket-ID ist nicht mit einem geöffneten Wartungsfenster verknüpft.

  • 500 (Internal Server Error) : Sonstiger unerwarteter Fehler.

Hinweis

Stellen Sie sicher, dass die Ticket-ID mit einem vorhandenen geöffneten Wartungsfenster verknüpft ist.

Methode: GET

Ruft ein Protokoll aller Aktionen zum Öffnen, Schließen und Aktualisieren ab, die im System während der Wartung ausgeführt wurden. Sie können ein Protokoll nur für Wartungsfenster abrufen, die in der Vergangenheit aktiv waren und geschlossen wurden.

Abfrageparameter

  • fromDate: Filtert die Protokolle aufsteigend ab dem vordefinierten Datum. Das Format lautet 2019-12-30.

  • toDate: Filtert die Protokolle bis zum vordefinierten Datum. Das Format lautet 2019-12-30.

  • ticketId: Filtert die Protokolle, die mit einer bestimmten Ticket-ID verknüpft sind.

  • tokenName: Filtert die Protokolle, die mit einem bestimmten Tokennamen verknüpft sind.

Fehlercode

  • 200 (OK) : Die Aktion wurde erfolgreich abgeschlossen.

  • 400 (Bad Request) : Das Datumsformat ist falsch.

  • 204 (No Content) : Es sind keine anzuzeigenden Daten vorhanden.

  • 500 (Internal Server Error) : Sonstiger unerwarteter Fehler.

Antworttyp

  • JSON

Antwortinhalt

Array von JSON-Objekten, die Vorgänge im Wartungsfenster darstellen.

Antwortstruktur

Name Typ Kommentar Nullwerte zulässig
dateTime String Beispiel: „2012-04-23T18:25:43.511Z“ nein
ticketId String Beispiel: „9a5fe99c-d914-4bda-9332-307384fe40bf“ nein
tokenName Zeichenfolge - nein
engines Zeichenfolgenarray - ja
sensorIds Zeichenfolgenarray - ja
Subnetze Zeichenfolgenarray - ja
ttl Numeric - ja
operationType String Werte sind „OPEN“, „UPDATE“ und „CLOSE“ nein

Curl-Befehl

type APIs Beispiel
POST curl -k -X POST -d '{"ticketId": "<TICKET_ID>",ttl": <TIME_TO_LIVE>,"engines": [<ENGINE1, ENGINE2...ENGINEn>],"sensorIds": [<SENSOR_ID1, SENSOR_ID2...SENSOR_IDn>],"subnets": [<SUBNET1, SUBNET2....SUBNETn>]}' -H "Authorization: <AUTH_TOKEN>" https://127.0.0.1/external/v1/maintenanceWindow curl -k -X POST -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20","engines": ["ANOMALY"],"sensorIds": ["5","3"],"subnets": ["10.0.0.3"]}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow
PUT curl -k -X PUT -d '{"ticketId": "<TICKET_ID>",ttl": "<TIME_TO_LIVE>"}' -H "Authorization: <AUTH_TOKEN>" https://127.0.0.1/external/v1/maintenanceWindow curl -k -X PUT -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow
DELETE curl -k -X DELETE -d '{"ticketId": "<TICKET_ID>"}' -H "Authorization: <AUTH_TOKEN>" https://127.0.0.1/external/v1/maintenanceWindow curl -k -X DELETE -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow
GET curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/maintenanceWindow?fromDate=&toDate=&ticketId=&tokenName=' curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/maintenanceWindow?fromDate=2020-01-01&toDate=2020-07-14&ticketId=a5fe99c-d914-4bda-9332-307384fe40bf&tokenName=a'

Anfordern von Warnungs-PCAP: /external/v2/alerts/pcap

Verwenden Sie diese API, um eine PCAP-Datei im Zusammenhang mit einer Warnung anzufordern.

Methode

  • GET

Abfrageparameter

  • id: CM-Warnungs-ID
    Beispiel:
    /external/v2/alerts/pcap/<id>

Antworttyp

  • JSON

Antwortinhalt

  • Erfolgreich: JSON-Objekt, das Daten zur angeforderten PCAP-Datei enthält
  • Fehler: JSON-Objekt, das eine Fehlermeldung enthält

Datenfelder

Name Typ Nullwerte zulässig
id Numeric Nein
xsenseId Numeric Nein
xsenseAlertId Numeric Nein
downloadUrl String Nein
token String Nein

Antwortbeispiel

Erfolg

{
  "downloadUrl": "https://10.1.0.2/api/v2/alerts/pcap/1",
  "xsenseId": 1,
  "token": "d2791f58-2a88-34fd-ae5c-2651fe30a63c",
  "id": 1,
  "xsenseAlertId": 1
}

Fehler

{
  "error": "alert not found"
}

Curl-Befehl

type APIs Beispiel
GET curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v2/alerts/pcap/<ID>' curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://10.1.0.1/external/v2/alerts/pcap/1'

ServiceNow Integration API - “/external/v3/integration/ (Vorschau)

Die unten aufgeführten APIs können mit der ServiceNow-Integration über den Service Graph Connector von ServiceNow für Defender für IoT verwendet werden.

Erstellen und Aktualisieren von Geräten

Anforderung

  • Pfad: "/devices/{timestamp}"

  • Methodentyp: GET

  • Pfadparameter:

    • Zeitstempel“ – Die Zeit, ab der Updates erforderlich sind. Es werden nur spätere Updates zurückgegeben.
  • Abfrageparameter:

    • Sensor-ID“ – Verwenden Sie diesen Parameter, um nur Geräte abzurufen, die von einem bestimmten Sensor angezeigt werden. Die ID sollte den Ergebnissen der Sensor-API entnommen werden.
    • notificationType” – sollte eine Nummer von dem folgenden Mapping sein:
      • 0 – sowohl aktualisierte als auch neue Geräte (Standard).
      • 1 – nur neue Geräte.
      • 2 – nur aktualisierte Geräte.
    • page“ – die Seitenzahl aus dem Resultset (erste Seite ist 0, Standardwert ist 0)
    • size” – die Seitengröße (Standardwert ist 50)

Antwort

  • Typ: JSON
  • Struktur:
    • u_count“ – Die Objektmenge in den vollständigen Resultsets, einschließlich aller Seiten.
    • u_devices“ – Array von Geräteobjekten (wie in der spezifischen Geräte-API definiert).

Verbindungen

Anforderung

  • Pfad: „/connections/{timestamp}“
  • Methodentyp: GET
  • Pfadparameter:
    • Zeitstempel“ – Die Zeit, ab der Updates erforderlich sind. Es werden nur spätere Updates zurückgegeben.
  • Abfrageparameter:
    • page“ – die Seitenzahl aus dem Resultset ( Standardwert ist 1)
    • size” – die Seitengröße (Standardwert ist 50)

Antwort

  • Typ: JSON
  • Struktur:
    • u_count“ – Die Objektmenge in den vollständigen Resultsets, einschließlich aller Seiten.
    • u_connections“ – Array von
      • u_src_device_id – ID des Quellgeräts
      • u_dest_device_id – ID des Zielgeräts
      • u_connection_type“ – eines der folgenden:
        • Unidirektional
        • Bidirektional
        • Multicast

Bestimmtes Gerät

Anforderung

  • Pfad: „/device/{deviceId}“
  • Methodentyp: GET
  • Pfadparameter:
    • deviceId – ID des angeforderten Geräts

Antwort

  • Typ: JSON
  • Struktur:
    • u_id“ – die interne ID des Geräts.
    • u_vendor“ – der Name des Herstellers.
    • u_mac_address_objects“ – Array von
      • u_mac_address“ – die MAC-Adresse des Geräts.
    • u_ip_address_objects“ – Array von
      • u_ip_address“ – die IP-Adresse des Geräts.
      • u_guessed_mac_addresses” – Array von
        • u_mac_address“ – die angenommene MAC-Adresse.
    • u_name“ – der Name des Geräts.
    • u_last_activity” – der Zeitstempel der letzten Aktivität des Geräts.
    • u_first_discovered“ – der Zeitstempel der Ermittlungszeit des Geräts.
    • u_last_update“ – der Zeitstempel der letzten Updatezeit des Geräts.
    • u_vlans“ – Array von
      • u_vlan“ – VLAN des Geräts.
    • u_device_type” -
      • u_name“ – der Gerätetyp
      • u_purdue_layer“ – die Standardebene für diesen Gerätetyp.
      • u_category“ – ist eines der folgenden Elemente:
        • IT
        • ICS
        • IoT
        • Netzwerk
    • u_operating_system“ – das Betriebssystem des Geräts.
    • u_protocol_objects“ – Array von
      • u_protocol“ – Das vom Gerät verwendete Protokoll.
    • u_purdue_layer“ – die Purdue-Ebene, die vom Benutzer manuell festgelegt wurde.
    • u_sensor_ids“ – Array von
      • u_sensor_id“ – die ID des Sensors, der das Gerät erkannt hat.
    • u_device_urls“ – Array von
      • u_device_url“ – die URL, um das Gerät in dem Sensor anzuzeigen.
    • u_firmwares“ – Array von
      • u_address
      • u_module_address
      • u_serial
      • u_model
      • u_version
      • u_additional_data

Gelöschte Geräte

Anforderung

  • Pfad: „/deleteddevices/{timestamp}“
  • Methodentyp: GET
  • Pfadparameter:
    • Zeitstempel“ – Die Zeit, ab der Updates erforderlich sind. Es werden nur spätere Updates zurückgegeben.

Antwort

  • Typ: JSON
  • Struktur:
    • Array von
      • u_id“ – die ID des gelöschten Geräts.

Sensoren

Anforderung

  • Pfad: „/sensors“
  • Methodentyp: GET

Antwort

  • Typ: JSON
  • Struktur:
    • Array von
      • u_id“ – interner Sensor für die Verwendung in der API der Geräte.
      • u_name“ – Der Name der Appliance.
      • u_connection_state“ – Konnektivität mit dem CM-Zustand. Einer der folgenden:
        • SYNCED“ – Verbindung ist erfolgreich.
        • OUT_OF_SYNC“– Die Verwaltungskonsole kann die vom Sensor empfangenen Daten nicht verarbeiten.
        • TIME_DIFF_OFFSET“ – Zeitdrift erkannt. Die Verwaltungskonsole wurde vom Sensor getrennt.
        • DISCONNECTED“ – Der Sensor kommuniziert nicht mit der Verwaltungskonsole. Überprüfen Sie die Netzwerkverbindung.
      • u_interface_address“ – die Netzwerkadresse der Appliance.
      • u_version“ – Die Zeichenfolgenrepräsentation der Sensor-Version.
      • u_alert_count“ – Nummer von Warnungen, die von dem Sensor gefunden wurden.
      • u_device_count“ – Nummer von Geräten, die von dem Sensor entdeckt wurden.
      • u_unhandled_alert_count“ – Anzahl der nicht behandelten Warnungen im Sensor.
      • u_is_activated“ – Aktivierte Warnung.
      • u_data_intelligence_version“ – Zeichenfolgendarstellung der im Sensor installierten Datenintelligenz.
      • u_remote_upgrade_stage“ – Status des Remote-Upgrades. Einer der folgenden:
        • 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
      • u_uid“ – Der global eindeutige Bezeichner für den Sensor

Geräte-CVEs

Anforderung

  • Pfad: „/devicecves/{timestamp}“
  • Methodentyp: GET
  • Pfadparameter:
    • Zeitstempel“ – Die Zeit, ab der Updates erforderlich sind. Es werden nur spätere Updates zurückgegeben.
  • Abfrageparameter:
    • page“ – die Seitenzahl aus dem Resultset (erste Seite ist 0, Standardwert ist 0)
    • size” – die Seitengröße (Standardwert ist 50)

Antwort

  • Typ: JSON
  • Struktur:
    • u_count“ – Die Objektmenge in den vollständigen Resultsets, einschließlich aller Seiten.
    • u_id“ – identisch mit der spezifischen Geräte-API.
    • u_name“ – identisch mit der spezifischen Geräte-API.
    • u_ip_address_objects“ – identisch mit der spezifischen Geräte-API.
    • u_mac_address_objects“ – identisch mit der spezifischen Geräte-API.
    • u_last_activity“ – identisch mit der spezifischen Geräte-API.
    • u_last_update“ – identisch mit der spezifischen Geräte-API.
    • u_cves“ – ein Array von CVEs:
      • u_ip_address“ – die IP-Adresse der spezifischen Schnittstelle mit der spezifischen Firmware, für die das CVE erkannt wurde.
      • u_cve_id“ – die ID der CVE
      • u_score“ – die Risikobewertung der CVE
      • u_attack_vector“ – eines der folgenden:
        • ADJACENT_NETWORK
        • LOCAL
        • NETWORK
      • u_description“ – die Beschreibung der CVE.

Nächste Schritte