Skapa aviserings-API

Gäller för:

Anteckning

Om du är myndighetskund i USA kan du använda de URI:er som visas i Microsoft Defender för Slutpunkt för kunder inom myndigheter i USA.

Tips

För bättre prestanda kan du använda servern närmare din geografiska plats:

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com

API-beskrivning

Skapar ny avisering ovanpå händelse.

  • Microsoft Defender för Endpoint-händelse krävs för att aviseringen ska kunna skapas.
  • Du måste ange 3 parametrar från händelsen i begäran: Händelsetid, Maskin-ID och Rapport-ID. Se exemplet nedan.
  • Du kan använda en händelse i Advanced Hunting API eller Portal.
  • Om det finns en öppen avisering på samma enhet med samma rubrik, slås den nya skapade aviseringen ihop med den.
  • En automatisk undersökning startar automatiskt för aviseringar som skapas via API:t.

Begränsningar

  1. Prisbegränsningar för detta API är 15 samtal per minut.

Behörigheter

En av följande behörigheter krävs för att anropa detta API. Mer information, inklusive hur du väljer behörigheter, finns i Använda Microsoft Defender för slutpunkts-API:er

Behörighetstyp Behörighet Visningsnamn för behörighet
Program Alert.ReadWrite.All "Läs och skriv alla aviseringar"
Delegerat (arbets- eller skolkonto) Alert.ReadWrite "Aviseringar om läsning och skrivning"

Anteckning

När du skaffar en token med hjälp av användarautentiseringsuppgifter:

  • Användaren måste ha minst följande rollbehörighet: "Undersökning av aviseringar" (mer information finns i Skapa och hantera roller)
  • Användaren måste ha åtkomst till den enhet som är kopplad till aviseringen, baserat på enhetsgruppinställningar (mer information finns i Skapa och hantera enhetsgrupper)

HTTP-begäran

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

Frågerubriker

Namn Typ Beskrivning
Auktorisering Sträng Bearer {token}. Obligatoriskt.
Content-Type Sträng application/json. Obligatoriskt.

Frågebrödtext

Ange följande värden i brödtexten för begäran (alla är obligatoriska):

Egenskap Typ Beskrivning
eventTime DateTime(UTC) Den exakta tiden för händelsen som sträng, från avancerad sökning. t.ex. 2018-08-03T16:45:21.7115183Z Obligatoriskt.
reportId Sträng ReportId för händelsen, från avancerad sökning. Obligatoriskt.
machineId Sträng ID för enheten där händelsen identifierades. Obligatoriskt.
allvarlighetsgrad Sträng Aviseringens allvarlighetsgrad. Egenskapsvärdena är: "Låg", "Medel" och "Hög". Obligatoriskt.
rubrik Sträng Rubrik för aviseringen. Obligatoriskt.
beskrivning Sträng Beskrivning av aviseringen. Obligatoriskt.
recommendedAction Sträng En åtgärd som rekommenderas att vidtas av säkerhetsofficer när du analyserar aviseringen. Obligatoriskt.
kategori Sträng Kategorin för aviseringen. Egenskapsvärdena är: "General", "CommandAndControl", "Collection", "CredentialAccess", "DefenseEvasion", "Discovery", "Exfiltration", "Exploit", "Execution", "InitialAccess", "Malware", "Malware", "Per persist", "PrivilegeEscalation", "Ransomware", "SuspiciousActivity" Required.

Svar

Om det lyckas returnerar den här metoden 200 OK och ett nytt aviseringsobjekt i svarstexten. Om en händelse med de angivna egenskaperna (reportId, eventTime och machineId) inte hittades – 404 Hittades inte.

Exempel

Begäran

Här är ett exempel på begäran.

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"
}