Opprett varsel-API

Artikkel
07/04/2024

Gjelder for:

Vil du oppleve Microsoft Defender for endepunkt? Registrer deg for en gratis prøveperiode.

Obs!

Hvis du er us Government-kunde, kan du bruke URI-ene som er oppført i Microsoft Defender for Endpoint for US Government-kunder.

Tips

Hvis du vil ha bedre ytelse, kan du bruke serveren nærmere geografisk plassering:

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com
ina.api.security.microsoft.com

API-beskrivelse

Oppretter nytt varsel øverst i hendelsen.

Microsoft Defender for Endpoint-hendelse kreves for at varselet skal opprettes.
Du må angi tre parametere fra hendelsen i forespørselen: Hendelsestid, maskin-ID og rapport-ID. Se eksemplet nedenfor.
Du kan bruke en hendelse funnet i API for avansert jakt eller portal.
Hvis det finnes et åpent varsel på samme enhet med samme tittel, slås det nye varselet sammen med det.
En automatisk undersøkelse starter automatisk på varsler som opprettes via API-en.

Begrensninger

Satsbegrensninger for denne API-en er 15 oppkall per minutt.

Tillatelser

Én av følgende tillatelser er nødvendig for å kalle opp denne API-en. Hvis du vil ha mer informasjon, inkludert hvordan du velger tillatelser, kan du se Bruke Microsoft Defender for endepunkt-API-er.

Tillatelsestype	Tillatelse	Visningsnavn for tillatelse
Program	Alert.ReadWrite.All	«Les og skriv alle varsler»
Delegert (jobb- eller skolekonto)	Alert.ReadWrite	«Lese- og skrivevarsler»

Obs!

Når du skaffer et token ved hjelp av brukerlegitimasjon:

Brukeren må minst ha følgende rolletillatelse: Varsler undersøkelse. Hvis du vil ha mer informasjon, kan du se Opprette og administrere roller.
Brukeren må ha tilgang til enheten som er knyttet til varselet, basert på innstillingene for enhetsgruppen. Hvis du vil ha mer informasjon, kan du se Opprette og administrere enhetsgrupper.

Oppretting av enhetsgruppe støttes i både Defender for Endpoint Plan 1 og Plan 2

HTTP-forespørsel

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

Forespørselshoder

Navn	Type:	Beskrivelse
Autorisasjon	Streng	Bærer {token}. Obligatorisk.
Innholdstype	Streng	program/json. Obligatorisk.

Forespørselstekst

Angi følgende verdier i forespørselsteksten (alle er nødvendige):

Eiendom	Type:	Beskrivelse
eventTime	DateTime(UTC)	Den nøyaktige tidspunktet for hendelsen som streng, som hentet fra avansert jakt. For eksempel `2018-08-03T16:45:21.7115183Z`Obligatorisk.
reportId	Streng	ReportId av hendelsen, som hentet fra avansert jakt. Obligatorisk.
machineId	Streng	ID-en til enheten som hendelsen ble identifisert på. Obligatorisk.
Alvorlighetsgraden	Streng	Alvorsgraden for varselet. Egenskapsverdiene er: Lav, Middels og Høy. Obligatorisk.
tittel	Streng	Tittel for varselet. Obligatorisk.
beskrivelse	Streng	Beskrivelse av varselet. Obligatorisk.
recommendedAction	Streng	Sikkerhetsansvarlig må utføre denne handlingen når du analyserer varselet. Obligatorisk.
kategori	Streng	Kategori for varselet. Egenskapsverdiene er: «Generelt», «CommandAndControl», «Samling», «CredentialAccess», «DefenseEvasion», «Discovery», «Exfiltration», «Exploit», «Execution», «InitialAccess», «LateralMovement», «Malware», «Persistence», «PrivilegeEscalation», «Ransomware», «SuspiciousActivity» Obligatorisk.

Svar

Hvis vellykket, returnerer denne metoden 200 OK, og et nytt varselobjekt i svarteksten. Hvis hendelsen med de angitte egenskapene (reportId, eventTime og machineId) ikke ble funnet – finner du ikke 404.

Eksempel

Anmodning

Her er et eksempel på forespørselen.

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

{
    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
    "severity": "Low",
    "title": "example",
    "description": "example alert",
    "recommendedAction": "nothing",
    "eventTime": "2018-08-03T16:45:21.7115183Z",
    "reportId": "20776",
    "category": "Exploit"
}