Naslaginformatie over waarschuwingsbeheer-API voor OT-bewakingssensoren

Dit artikel bevat de REST API's voor waarschuwingsbeheer die worden ondersteund voor Microsoft Defender voor IoT OT-bewakingssensoren.

waarschuwingen (waarschuwingsgegevens ophalen)

Gebruik deze API om een lijst aan te vragen met alle waarschuwingen die de Defender for IoT-sensor heeft gedetecteerd.

URI: /api/v1/alerts

GET

Aanvraag

Queryparameters

Naam	Beschrijving	Voorbeeld	Vereist/optioneel
Staat	Alleen verwerkte of onverwerkte waarschuwingen ophalen. Ondersteunde waarden: - handled - unhandled	/api/v1/alerts?state=handled	Optioneel
fromTime	Ontvang waarschuwingen die zijn gemaakt vanaf een bepaald tijdstip, in milliseconden vanaf Epoch-tijd en in UTC-tijdzone.	/api/v1/alerts?fromTime=<epoch>	Optioneel
toTime	Ontvang waarschuwingen die alleen eerder op een bepaald tijdstip zijn gemaakt, in milliseconden vanaf Epoch-tijd en in UTC-tijdzone.	/api/v1/alerts?toTime=<epoch>	Optioneel
type	Alleen waarschuwingen van een specifiek type ontvangen. Ondersteunde waarden: - unexpected new devices - disconnections Alle andere waarden worden genegeerd.	/api/v1/alerts?type=disconnections	Optioneel

Response

Type: JSON

Een lijst met waarschuwingen met de volgende velden:

Naam	Type	Nullable /Not nullable	Lijst met waarden
Id	Numeriek	Niet nullable	-
time	Numeriek	Niet nullable	Milliseconden van epoch-tijd, in UTC-tijdzone
title	Tekenreeks	Niet nullable	-
bericht	Tekenreeks	Niet nullable	-
Ernst	Tekenreeks	Niet nullable	Warning, Minor, Majorof Critical
Engine	Tekenreeks	Niet nullable	Protocol Violation, Policy Violation, Malware, Anomalyof Operational
sourceDevice	Numeriek	Null-waarde toegestaan	Apparaat-ID
destinationDevice	Numeriek	Null-waarde toegestaan	Apparaat-ID
additionalInformation	Aanvullende informatieobject	Null-waarde toegestaan	-

Aanvullende informatievelden

Naam	Type	Nullable /Not nullable	Lijst met waarden
beschrijving	Tekenreeks	Niet nullable	-
Informatie	JSON-matrix	Niet nullable	Tekenreeks

Toegevoegd voor V2:

Naam	Type	Nullable /Not nullable	Lijst met waarden
sourceDeviceAddress	Tekenreeks	Null-waarde toegestaan	IP- of MAC-adres
destinationDeviceAddress	Tekenreeks	Null-waarde toegestaan	IP- of MAC-adres
remediationSteps	JSON-matrix	Niet nullable	Tekenreeksen, herstelstappen die worden beschreven in de waarschuwing

Zie Naslaginformatie over sensor-API-versies voor meer informatie.

Voorbeeld van antwoord

[
    {
        "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-opdracht

Type: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/alerts?state=<STATE>&fromTime=<FROM_TIME>&toTime=<TO_TIME>&type=<TYPE>'

Voorbeeld:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/alerts?state=unhandled&fromTime=1594550986000&toTime=1594550986001&type=disconnections'

gebeurtenissen (tijdlijnen ophalen)

Gebruik deze API om een lijst met gebeurtenissen aan te vragen die zijn gerapporteerd aan de tijdlijn van de gebeurtenis.

Notitie

Als u de identieke API binnen hetzelfde uur uitvoert, met exact dezelfde parameterwaarden, wordt een waarde in de cache geretourneerd. Als u deze API twee keer in een uur uitvoert, raden we u aan de queryparameters te wijzigen om een bijgewerkt antwoord te krijgen.

URI: /api/v1/events

GET

Aanvraag

Queryparameters

Naam	Beschrijving	Voorbeeld	Vereist/optioneel
minutesTimeFrame	Resultaten filteren op een bepaald tijdsbestek waarin gebeurtenissen zijn gerapporteerd. Achterwaarts gedefinieerd vanaf de huidige tijd. Maximum = 4320 (3 dagen). Een grotere waarde wordt behandeld als 4320, zonder fout	/api/v1/events?minutesTimeFrame=20	Optioneel
type	Resultaten alleen filteren op een specifiek type. Andere waarden dan ondersteunde typen worden genegeerd. Zie Gebeurtenis type en title verwijzing voor meer informatie.	/api/v1/events?type=DEVICE_CONNECTION_CREATED /api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame	Optioneel

Response

Type: JSON

Matrix van JSON-objecten die de meest recente 100 gebeurtenissen vertegenwoordigen, gesorteerd op tijdstempel van gebeurtenissen, met de meest recente gebeurtenis eerst.

Gebeurtenisvelden zijn onder andere:

Naam	Type	Nullable /Not nullable	Lijst met waarden
Tijdstempel	Numeriek	Niet nullable	Milliseconden van epoch-tijd, in UTC-tijdzone
type	Tekenreeks	Niet nullable	Een van de ondersteunde typen
title	Tekenreeks	Niet nullable	Een van de ondersteunde titels
Ernst	Tekenreeks	Niet nullable	INFO, NOTICE of ALERT
Eigenaar	Tekenreeks	Null-waarde toegestaan	Tekenreeks. Als de gebeurtenis handmatig is gemaakt, bevat dit veld de gebruikersnaam waarmee de gebeurtenis is gemaakt.
Inhoud	Tekenreeks	Niet nullable	Tekenreeks die de gebeurtenis beschrijft.

Voorbeeld van antwoord

[
    {
        "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-opdracht

Type: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/events?minutesTimeFrame=<TIME_FRAEM>&type=<TYPE>'

Voorbeeld:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/events?minutesTimeFrame=20&type=DEVICE_CONNECTION_CREATED'`

Gebeurtenis type en title verwijzing

In deze sectie worden de waarden vermeld die worden ondersteund als gebeurtenistype en titelwaarden voor de gebeurtenissen-API .

Gebeurtenistype	Titel van gebeurtenis
DEVICE_CREATE	Apparaat gedetecteerd
DEVICE_UPDATE	Apparaat bijgewerkt
ALERT_REPORTED	Waarschuwing gedetecteerd
ALERT_UPDATED	Waarschuwing bijgewerkt
SCAN	Scanapparaat gedetecteerd
PROGRAM_DEVICE	PLC Programmeren
MMS_PROGRAM_DEVICE	PLC-programma-update
SCL_UPLOADED	SCL geüpload
EXCLUSION_RULE_CREATED	Uitsluitingsregel gemaakt
EXCLUSION_RULE_REMOVED	Uitsluitingsregel verwijderd
EXCLUSION_RULE_UPDATED	Uitsluitingsregel bijgewerkt
DEVICE_CONNECTION_CREATED	Apparaatverbinding gedetecteerd
USER_LOGIN	Gebruikersaanmeldingspoging
FILE_TRANSFER	Bestandsoverdracht gedetecteerd
CUSTOM_EVENT	Door de gebruiker gedefinieerde gebeurtenis
REMOTE_ACCESS	Verbinding met externe toegang tot stand gebracht
BACK_TO_NORMAL	Terug naar normaal
MMS_MEMORY_BLOCK_OPERATION	MMS-geheugenblokbewerking
MMS_PROGRAM_OPERATION	MMS-programmabewerking
HTTP_BASIC_AUTHENTICATION	HTTP-basisverificatie
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Siemens S7 Memory Block Operation
SIEMENS_S_7_AUTHENTICATION	Siemens S7-verificatie
REPORT_CREATED	Rapport gemaakt
SNMP_TRAP	SNMP-trap gedetecteerd
DATABASE_ACTION	Manipulatie van databasestructuur
PLC_MODULE_CHANGE	PLC-module wijzigen
FIRMWARE_UPDATE	Firmware-update
PLC_START	PLC-start
SRTP_PLC_RESET	PLC opnieuw instellen
SRTP_PLC_COPY_FIRMWARE	Firmware-update
SRTP_LOGIN_PROGRAMMING	PLC-programmeermodusset
SRTP_PLC_CHANGE_PASSWORD	PLC-wachtwoord wijzigen
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	Beheerbewerking voor OPC-gegevenstoegangsgroepen
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	Beheerbewerking voor OPC-gegevenstoegangsitems
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	OPC Data Access IO-abonnementsbeheerbewerking
OPC_AE_EVENT_SUBSCRIPTION	OPC AE-gebeurtenisabonnement
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	Beheerbewerking van OPC AE-gebeurtenisvoorwaarde
OPC_AE_EVENT	OPC AE-gebeurtenis
SRTP_CHANGE_PRIVILEGE	PLC Toegangsniveau wijzigen
SRTP_CHANGE_LEVEL_FAILED	PLC-toegangsniveau wijzigen is mislukt
SUITELINK_INIT_CONNECTION	Wonderware-sessie geïnitialiseerd
USER_OPERATION	Gebruikersbewerking
DIP_UPLOADED	Data Intelligence-pakket geüpload
FTP_AUTHENTICATION_FAILURE	FTP-verificatiefout
PROFINET_DPC_VALUE_SET	Profinet SET-bewerking
S7PLUS_PLC_MODE_CHANGE	PLC-modus wijzigen
S7_PLC_MODE_CHANGE	PLC-modus wijzigen
DELETE_DEVICE	Apparaat is verwijderd
S7PLUS_PROGRAMMING	PLC Programmeren
FIRMWARE_CHANGED	PLC-firmware gewijzigd
DELTAV_PROGRAMMING	DeltaV-installatiescript
USER_DEFINED_RULE_CREATED	Door de gebruiker gedefinieerde regel gemaakt
USER_DEFINED_RULE_EDITED	Door de gebruiker gedefinieerde regel bewerkt
USER_DEFINED_RULE_DELETED	Door de gebruiker gedefinieerde regel verwijderd
USER_DEFINED_RULE_OPERATION	Door de gebruiker gedefinieerde regelbewerking
REMOTE_PROCESS_EXECUTION	Uitvoering van extern proces
DEVICE_UNIFICATION	Apparaat bijgewerkt
KENNISGEVING	Melding is handmatig opgelost
ENIP_CONTROLLER_PROGRAM_DELETE	Controllerprogramma verwijderen
ENIP_CONTROLLER_PROGRAM_RESET	Controllerprogramma opnieuw instellen
ENIP_CONTROLLER_GENERIC_RESET	Controller opnieuw instellen
ENIP_CONTROLLER_GENERIC_STOP	Controllerstop
ENIP_CONTROLLER_GENERIC_START	Controller starten
TELNET_AUTHENTICATION_FAILURE	Telnet-verificatiefout
CONFIGURATION_OF_CLEARTEXT_PASSWORD	Configuratie van wachtwoord voor tekst wissen
CLEARTEXT_AUTHENTICATION	Cleartext-verificatie
PROGRAM_UPLOAD_DEVICE	PLC-programma uploaden
CONFIGURATION_CHANGE	PLC-configuratie schrijven
CONFIGURATION_READ	PLC-configuratie lezen
SYSLOG_MSG	Syslog-bericht
INTERNET_ACCESS	Internettoegang
CAMP_MEMORY_WRITE_OPERATION	Common ASCII Message Protocol Memory Write Operation
MUTED_ALERT	Gebeurtenis gedetecteerd en gedempt
DHCP_UPDATE	Adresupdate
DIP_FAILURE	Fout bij het installeren van data intelligence-pakketten
DELETE_DEVICE_SCHEDULE	Inactieve apparaten die zijn gepland voor verwijdering
PLC_OPERATING_MODE_CHANGED	Wijziging in plc-bedrijfsmodus gedetecteerd
HARDWARE_UPDATE_BY_IDENTIFIER	Adresupdate

Volgende stappen

Zie het overzicht naslaginformatie over Defender for IoT API voor meer informatie.