Condividi tramite

API di avviso Create

  • Articolo

Si applica a:

Se si desidera provare Microsoft Defender per endpoint, iscriversi a una versione di valutazione gratuita.

Nota

Se si è un cliente del governo degli Stati Uniti, usare gli URI elencati in Microsoft Defender per endpoint per i clienti del governo degli Stati Uniti.

Consiglio

Per ottenere prestazioni migliori, è possibile usare il server più vicino alla posizione geografica:

  • 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

Descrizione DELL'API

Crea un nuovo avviso in cima all'evento.

  • Microsoft Defender per endpoint Evento è necessario per la creazione dell'avviso.
  • È necessario specificare tre parametri dall'evento nella richiesta: Ora evento, ID computer e ID report. Vedere l'esempio che segue.
  • È possibile usare un evento disponibile nell'API di ricerca avanzata o nel portale.
  • Se esiste un avviso aperto nello stesso dispositivo con lo stesso titolo, il nuovo avviso creato viene unito con esso.
  • Un'analisi automatica viene avviata automaticamente sugli avvisi creati tramite l'API.

Limitazioni

  1. Le limitazioni di frequenza per questa API sono di 15 chiamate al minuto.

Autorizzazioni

Per chiamare questa API è necessaria una delle autorizzazioni seguenti. Per altre informazioni, inclusa la scelta delle autorizzazioni, vedere Usare le API Microsoft Defender per endpoint.

Tipo di autorizzazione Autorizzazione Nome visualizzato autorizzazioni
Applicazione Alert.ReadWrite.All 'Leggere e scrivere tutti gli avvisi'
Delegato (account aziendale o dell'istituto di istruzione) Alert.ReadWrite 'Avvisi di lettura e scrittura'

Nota

Quando si ottiene un token usando le credenziali utente:

  • L'utente deve disporre almeno dell'autorizzazione del ruolo seguente: Analisi degli avvisi. Per altre informazioni, vedere Create e gestire i ruoli.
  • L'utente deve avere accesso al dispositivo associato all'avviso, in base alle impostazioni del gruppo di dispositivi. Per altre informazioni, vedere Create e gestire i gruppi di dispositivi.

La creazione del gruppo di dispositivi è supportata sia in Defender per endpoint piano 1 che in piano 2

Richiesta HTTP

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

Intestazioni di richiesta

Nome Tipo Descrizione
Autorizzazione Stringa Bearer {token}. Obbligatorio.
Content-Type Stringa application/json. Obbligatorio.

Corpo della richiesta

Nel corpo della richiesta specificare i valori seguenti (tutti sono obbligatori):

Proprietà Tipo Descrizione
eventTime DateTime(UTC) Tempo preciso dell'evento come stringa, ottenuto dalla ricerca avanzata. Ad esempio, 2018-08-03T16:45:21.7115183ZObbligatorio.
reportId Stringa ReportId dell'evento, ottenuto dalla ricerca avanzata. Obbligatorio.
machineId Stringa ID del dispositivo in cui è stato identificato l'evento. Obbligatorio.
Gravità Stringa Gravità dell'avviso. I valori delle proprietà sono: 'Low', 'Medium' e 'High'. Obbligatorio.
title Stringa Titolo per l'avviso. Obbligatorio.
descrizione Stringa Descrizione dell'avviso. Obbligatorio.
recommendedAction Stringa Il responsabile della sicurezza deve eseguire questa azione durante l'analisi dell'avviso. Obbligatorio.
Categoria Stringa Categoria dell'avviso. I valori della proprietà sono: "General", "CommandAndControl", "Collection", "CredentialAccess", "DefenseEvasion", "Discovery", "Exfiltration", "Exploit", "Execution", "InitialAccess", "LateralMovement", "Malware", "Persistence", "PrivilegeEscalation", "Ransomware", "SuspiciousActivity" Required.

Risposta

In caso di esito positivo, questo metodo restituisce 200 OK e un nuovo oggetto avviso nel corpo della risposta. Se l'evento con le proprietà specificate (reportId, eventTime e machineId) non è stato trovato- 404 Non trovato.

Esempio

Richiesta

Ecco un esempio della richiesta.

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

Consiglio

Per saperne di più, Engage con la community Microsoft Security nella community tech: Microsoft Defender per endpoint Tech Community.