API-referens för aviseringshantering för OT-övervakningssensorer

Artikel
06/01/2023

Den här artikeln innehåller rest-API:er för aviseringshantering som stöds för Microsoft Defender för IoT OT-övervakningssensorer.

aviseringar (Hämta aviseringsinformation)

Använd det här API:et för att begära en lista över alla aviseringar som Defender för IoT-sensorn har identifierat.

URI: /api/v1/alerts

GET

Frågeparametrar

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
Statligt	Få endast hanterade eller ohanterade aviseringar. Värden som stöds: - `handled` - `unhandled`	`/api/v1/alerts?state=handled`	Valfritt
fromTime	Hämta aviseringar som skapats med början vid en viss tidpunkt, i millisekunder från Epoch-tid och i UTC-tidszon.	`/api/v1/alerts?fromTime=<epoch>`	Valfritt
toTime	Hämta aviseringar som skapats endast före vid en viss tidpunkt, i millisekunder från Epoch-tid och i UTC-tidszon.	`/api/v1/alerts?toTime=<epoch>`	Valfritt
typ	Hämta endast aviseringar av en viss typ. Värden som stöds: - `unexpected new devices` - `disconnections` Alla andra värden ignoreras.	`/api/v1/alerts?type=disconnections`	Valfritt

Typ: JSON

En lista över aviseringar med följande fält:

Namn	Typ	Nullable/Not nullable	Lista över värden
ID	Numerisk	Inte nullbar	-
Tid	Numerisk	Inte nullbar	Millisekunder från epoktid, i UTC-tidszon
title	Sträng	Inte nullbar	-
meddelande	Sträng	Inte nullbar	-
Svårighetsgrad	Sträng	Inte nullbar	`Warning`, `Minor`, `Major`eller `Critical`
Motor	Sträng	Inte nullbar	`Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`eller `Operational`
sourceDevice	Numerisk	Kan ha värdet null	Enhets-ID
destinationEnhet	Numerisk	Kan ha värdet null	Enhets-ID
additionalInformation	Ytterligare informationsobjekt	Kan ha värdet null	-

Ytterligare informationsfält

Namn	Typ	Nullable/Not nullable	Lista över värden
beskrivning	Sträng	Inte nullbar	-
Information	JSON-matris	Inte nullbar	Sträng

Har lagts till för V2:

Namn	Typ	Nullable/Not nullable	Lista över värden
sourceDeviceAddress	Sträng	Kan ha värdet null	IP- eller MAC-adress
destinationDeviceAddress	Sträng	Kan ha värdet null	IP- eller MAC-adress
remediationSteps	JSON-matris	Inte nullbar	Strängar, reparationssteg som beskrivs i aviseringen

Mer information finns i Referens för sensor-API-version.

Exempel på svar

[
    {
        "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,
    }
]

Typ: GET

API:

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

Exempel:

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

händelser (Hämta tidslinjehändelser)

Använd det här API:et för att begära en lista över händelser som rapporteras till händelsetidslinjen.

Anteckning

Om du kör det identiska API:et inom samma timme, med exakt samma parametervärden, returneras ett cachelagrat värde. Om du kör det här API:et två gånger på en timme rekommenderar vi att du ändrar frågeparametrarna för att få ett uppdaterat svar.

URI: /api/v1/events

GET

Frågeparametrar

Name	Beskrivning	Exempel	Obligatoriskt/valfritt
minutesTimeFrame	Filtrera resultat efter en viss tidsram under vilken händelser rapporterades. Definieras bakåt från den aktuella tiden. Maximalt = `4320` (3 dagar). Större värden behandlas som 4320, utan fel	`/api/v1/events?minutesTimeFrame=20`	Valfritt
typ	Filtrera endast resultat för en viss typ. Andra värden än typer som stöds ignoreras. Mer information finns i Händelse `type` och `title` referens.	`/api/v1/events?type=DEVICE_CONNECTION_CREATED` `/api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame`	Valfritt

Typ: JSON

Matris med JSON-objekt som representerar de senaste 100 händelserna, sorterade efter händelsetidsstämpel, med den senaste händelsen först.

Exempel på händelsefält:

Namn	Typ	Nullable/Not nullable	Lista över värden
Tidsstämpel	Numerisk	Inte nullbar	Millisekunder från epoktid, i UTC-tidszon
typ	Sträng	Inte nullbar	En av de typer som stöds
title	Sträng	Inte nullbar	En av de titlar som stöds
Svårighetsgrad	Sträng	Inte nullbar	`INFO`, `NOTICE`eller `ALERT`
Ägare	Sträng	Kan ha värdet null	Sträng. Om händelsen skapades manuellt innehåller det här fältet det användarnamn som skapade händelsen.
Innehåll	Sträng	Inte nullbar	Sträng som beskriver händelsen.

Exempel på svar

[
    {
        "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"
    }
]

Typ: GET

API:

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

Exempel:

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

Händelse `type` och `title` referens

I det här avsnittet visas de värden som stöds som händelsetyp och rubrikvärden för händelse-API :et.

Händelsetyp	Händelserubrik
DEVICE_CREATE	Enheten har identifierats
DEVICE_UPDATE	Enheten har uppdaterats
ALERT_REPORTED	Avisering identifierad
ALERT_UPDATED	Aviseringen har uppdaterats
SCAN	Genomsökningsenhet har identifierats
PROGRAM_DEVICE	PLC-programmering
MMS_PROGRAM_DEVICE	PLC-programuppdatering
SCL_UPLOADED	SCL har laddats upp
EXCLUSION_RULE_CREATED	Undantagsregel har skapats
EXCLUSION_RULE_REMOVED	Undantagsregeln har tagits bort
EXCLUSION_RULE_UPDATED	Undantagsregeln har uppdaterats
DEVICE_CONNECTION_CREATED	Enhetsanslutning identifierad
USER_LOGIN	Användarinloggningsförsök
FILE_TRANSFER	Filöverföring har identifierats
CUSTOM_EVENT	Användardefinierad händelse
REMOTE_ACCESS	Fjärråtkomstanslutning upprättad
BACK_TO_NORMAL	Tillbaka till normal
MMS_MEMORY_BLOCK_OPERATION	MMS-minnesblocksåtgärd
MMS_PROGRAM_OPERATION	ÅTGÄRD FÖR MMS-program
HTTP_BASIC_AUTHENTICATION	Grundläggande HTTP-autentisering
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Siemens S7 Memory Block Operation
SIEMENS_S_7_AUTHENTICATION	Siemens S7-autentisering
REPORT_CREATED	Rapporten har skapats
SNMP_TRAP	SNMP-trap har identifierats
DATABASE_ACTION	Manipulering av databasstruktur
PLC_MODULE_CHANGE	PLC-moduländring
FIRMWARE_UPDATE	Uppdatering av inbyggd programvara
PLC_START	PLC-start
SRTP_PLC_RESET	PLC-återställning
SRTP_PLC_COPY_FIRMWARE	Uppdatering av inbyggd programvara
SRTP_LOGIN_PROGRAMMING	PLC-programmeringslägesuppsättning
SRTP_PLC_CHANGE_PASSWORD	PLC-lösenordsändring
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	Hanteringsåtgärd för OPC-dataåtkomstgrupp
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	Hanteringsåtgärd för OPC-dataåtkomstobjekt
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	Hanteringsåtgärd för OPC-dataåtkomst-I/O-prenumeration
OPC_AE_EVENT_SUBSCRIPTION	OPC AE-händelseprenumeration
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	Hanteringsåtgärd för OPC AE-händelsevillkor
OPC_AE_EVENT	OPC AE-händelse
SRTP_CHANGE_PRIVILEGE	PLC Ändra åtkomstnivå
SRTP_CHANGE_LEVEL_FAILED	PLC Ändring av åtkomstnivå misslyckades
SUITELINK_INIT_CONNECTION	Wonderware-sessionen har initierats
USER_OPERATION	Användaråtgärd
DIP_UPLOADED	Data intelligence-paketet har laddats upp
FTP_AUTHENTICATION_FAILURE	FTP-autentiseringsfel
PROFINET_DPC_VALUE_SET	Profinet SET-åtgärd
S7PLUS_PLC_MODE_CHANGE	ÄNDRA PLC-läge
S7_PLC_MODE_CHANGE	ÄNDRA PLC-läge
DELETE_DEVICE	Enheten har tagits bort
S7PLUS_PROGRAMMING	PLC-programmering
FIRMWARE_CHANGED	INBYGGD PLC-programvara har ändrats
DELTAV_PROGRAMMING	DeltaV-installationsskript
USER_DEFINED_RULE_CREATED	Användardefinierad regel har skapats
USER_DEFINED_RULE_EDITED	Användardefinierad regel redigerad
USER_DEFINED_RULE_DELETED	Användardefinierad regel borttagen
USER_DEFINED_RULE_OPERATION	Användardefinierad regelåtgärd
REMOTE_PROCESS_EXECUTION	Fjärrprocesskörning
DEVICE_UNIFICATION	Enheten har uppdaterats
ANMÄLAN	Meddelandet har lösts manuellt
ENIP_CONTROLLER_PROGRAM_DELETE	Borttagning av kontrollantprogram
ENIP_CONTROLLER_PROGRAM_RESET	Programåterställning av styrenhet
ENIP_CONTROLLER_GENERIC_RESET	Återställning av styrenhet
ENIP_CONTROLLER_GENERIC_STOP	Kontrollantstopp
ENIP_CONTROLLER_GENERIC_START	Start av kontrollant
TELNET_AUTHENTICATION_FAILURE	Telnet-autentiseringsfel
CONFIGURATION_OF_CLEARTEXT_PASSWORD	Konfiguration av lösenord i klartext
CLEARTEXT_AUTHENTICATION	Cleartext-autentisering
PROGRAM_UPLOAD_DEVICE	PLC-programuppladdning
CONFIGURATION_CHANGE	PLC-konfigurationsskrivning
CONFIGURATION_READ	PLC-konfigurationsläsning
SYSLOG_MSG	Syslog-meddelande
INTERNET_ACCESS	Internet
CAMP_MEMORY_WRITE_OPERATION	Vanlig minnesskrivningsåtgärd för ASCII-meddelandeprotokoll
MUTED_ALERT	Händelsen har identifierats och stängts av
DHCP_UPDATE	Adressuppdatering
DIP_FAILURE	Fel vid installation av datainformationspaket
DELETE_DEVICE_SCHEDULE	Inaktiva enheter som är schemalagda för borttagning
PLC_OPERATING_MODE_CHANGED	Ändring i PLC-driftsläge har identifierats
HARDWARE_UPDATE_BY_IDENTIFIER	Adressuppdatering

Nästa steg

Mer information finns i referensöversikten för Defender för IoT API.

Dela via

API-referens för aviseringshantering för OT-övervakningssensorer

aviseringar (Hämta aviseringsinformation)

GET

Frågeparametrar

Ytterligare informationsfält

Exempel på svar

händelser (Hämta tidslinjehändelser)

GET

Frågeparametrar

Exempel på svar

Händelse `type` och `title` referens

Nästa steg

Feedback

Ytterligare resurser

Dela via

API-referens för aviseringshantering för OT-övervakningssensorer

aviseringar (Hämta aviseringsinformation)

GET

Frågeparametrar

händelser (Hämta tidslinjehändelser)

GET

Frågeparametrar

Händelse type och title referens

Nästa steg

Feedback

Ytterligare resurser

Händelse `type` och `title` referens