Condividi tramite

Aggiornare l'API eventi imprevisti

  • Articolo

Si applica a:

Nota

Provare le nuove API usando l'API di sicurezza di MS Graph. Per altre informazioni, vedere: Usare l'API di sicurezza di Microsoft Graph - Microsoft Graph | Microsoft Learn. Per informazioni sulla nuova API degli eventi imprevisti di aggiornamento tramite l'API di sicurezza di MS Graph, vedere Aggiornamento dell'evento imprevisto.

Importante

Alcune informazioni fanno riferimento alle caratteristiche del prodotto prima del rilascio, e possono essere modificate sostanzialmente prima della distribuzione al pubblico. Microsoft non fornisce alcuna garanzia, esplicita o implicita, in relazione alle informazioni contenute in questo documento.

Descrizione DELL'API

Aggiornamenti proprietà dell'evento imprevisto esistente. Le proprietà aggiornabili sono: status, determination, classification, assignedTo, tagse comments.

Quote, allocazione delle risorse e altri vincoli

  1. È possibile effettuare fino a 50 chiamate al minuto o 1.500 chiamate all'ora prima di raggiungere la soglia di limitazione.
  2. È possibile impostare la determination proprietà solo se classification è impostata su TruePositive.

Se la richiesta è limitata, restituisce un codice di 429 risposta. Il corpo della risposta indica l'ora in cui è possibile iniziare a effettuare nuove chiamate.

Autorizzazioni

Per chiamare questa API è necessaria una delle autorizzazioni seguenti. Per altre informazioni, inclusa la scelta delle autorizzazioni, vedere Accedere alle API Microsoft Defender XDR.

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

Nota

Quando si ottiene un token usando le credenziali utente, l'utente deve disporre dell'autorizzazione per aggiornare l'evento imprevisto nel portale.

Richiesta HTTP

PATCH /api/incidents/{id}

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 per i campi che devono essere aggiornati. Le proprietà esistenti che non sono incluse nel corpo della richiesta mantengono i valori, a meno che non sia necessario ricalcolarli a causa di modifiche ai valori correlati. Per ottenere prestazioni ottimali, è consigliabile omettere i valori esistenti che non sono cambiati.

Proprietà Tipo Descrizione
stato Enum Specifica lo stato corrente dell'evento imprevisto. I valori possibili sono: Active, Resolved, InProgresse Redirected.
assignedTo stringa Proprietario dell'evento imprevisto.
Classificazione Enum Specifica dell'evento imprevisto. I valori possibili sono: TruePositive (Vero positivo), InformationalExpectedActivity (Attività informativa, prevista) e FalsePositive (Falso positivo).
Determinazione Enum Specifica la determinazione dell'evento imprevisto.

I possibili valori di determinazione per ogni classificazione sono:

  • Vero positivo: MultiStagedAttack (attacco a più fasi), MaliciousUserActivity (attività utente dannosa), CompromisedAccount (account compromesso) : valutare la possibilità di modificare di conseguenza il nome dell'enumerazione nell'api pubblica ( Malware Malware), Phishing (Phishing), UnwantedSoftware (software indesiderato) e Other (Altro).
  • Attività informativa prevista:SecurityTesting (Test di sicurezza), LineOfBusinessApplication (applicazione line-of-business), ConfirmedActivity (attività confermata) - valutare la possibilità di modificare di conseguenza il nome dell'enumerazione nell'API pubblica e Other (Altro).
  • Falso positivo:Clean (Non dannoso): valutare la possibilità di modificare di conseguenza il nome dell'enumerazione nell'API pubblica ( NoEnoughDataToValidate dati non sufficienti per la convalida) e Other (Altro).
    		•
    tag elenco di stringhe Elenco di tag evento imprevisto.
    Commento stringa Commento da aggiungere all'evento imprevisto.

    Nota

    Intorno al 29 agosto 2022, i valori di determinazione degli avvisi supportati in precedenza ('Apt' e 'SecurityPersonnel') verranno deprecati e non più disponibili tramite l'API.

    Risposta

    In caso di esito positivo, questo metodo restituisce 200 OK. Il corpo della risposta contiene l'entità evento imprevisto con proprietà aggiornate. Se non è stato trovato un evento imprevisto con l'ID specificato, il metodo restituisce 404 Not Found.

    Esempio

    Esempio di richiesta

    Ecco un esempio della richiesta.

     PATCH https://api.security.microsoft.com/api/incidents/{id}

    Esempio di richiesta di dati

    {
    "status": "Resolved",
    "assignedTo": "secop2@contoso.com",
    "classification": "TruePositive",
    "determination": "Malware",
    "tags": ["Yossi's playground", "Don't mess with the Zohan"],
    "comments": [
          {
              "comment": "pen testing",
              "createdBy": "secop2@contoso.com",
              "createdTime": "2021-05-02T09:34:21.5519738Z"
          },
          {
              "comment": "valid incident",
              "createdBy": "secop2@contoso.comt",
              "createdTime": "2021-05-02T09:36:27.6652581Z"
          }
      ]
}

    Consiglio

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