API för att uppdatera incidenter

  • Artikel

Gäller för:

Obs!

Prova våra nya API:er med ms Graph-säkerhets-API. Läs mer på: Använda Säkerhets-API:et för Microsoft Graph – Microsoft Graph | Microsoft Learn. Information om det nya API:et för uppdateringsincidenter med ms Graph-säkerhets-API finns i Uppdatera incident.

Viktigt

En del information gäller förinstallerad produkt som kan ha ändrats mycket innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som anges här.

API-beskrivning

Uppdateringar egenskaper för befintlig incident. Uppdateringsbara egenskaper är: status, determination, classification, assignedTo, tagsoch comments.

Kvoter, resursallokering och andra begränsningar

  1. Du kan göra upp till 50 anrop per minut eller 1 500 anrop per timme innan du når begränsningströskeln.
  2. Du kan bara ange determination egenskapen om classification den är inställd på TruePositive.

Om din begäran begränsas returneras en 429 svarskod. Svarstexten anger när du kan börja göra nya anrop.

Behörigheter

En av följande behörigheter krävs för att anropa det här API:et. Mer information, inklusive hur du väljer behörigheter, finns i Åtkomst till Microsoft Defender XDR-API:er.

Behörighetstyp Behörighet Visningsnamn för behörighet
Program Incident.ReadWrite.All Läsa och skriva alla incidenter
Delegerat (arbets- eller skolkonto) Incident.ReadWrite Läs- och skrivincidenter

Obs!

När du hämtar en token med användarautentiseringsuppgifter måste användaren ha behörighet att uppdatera incidenten i portalen.

HTTP-begäran

PATCH /api/incidents/{id}

Frågerubriker

Namn Typ Beskrivning
Tillstånd Sträng Ägaren {token}. Krävs.
Content-Type Sträng application/json. Krävs.

Frågebrödtext

I begärandetexten anger du värdena för de fält som ska uppdateras. Befintliga egenskaper som inte ingår i begärandetexten behåller sina värden, såvida de inte måste beräknas om på grund av ändringar i relaterade värden. För bästa prestanda bör du utelämna befintliga värden som inte har ändrats.

Egenskap Typ Beskrivning
Status Enum Anger incidentens aktuella status. Möjliga värden är: Active, Resolved, InProgressoch Redirected.
Tilldelat sträng Ägaren till incidenten.
Klassificering Enum Specifikation av incidenten. Möjliga värden är: TruePositive (True positive), InformationalExpectedActivity (Informational, expected activity) och FalsePositive (False Positive).
Bestämning Enum Anger fastställandet av incidenten.

Möjliga bestämningsvärden för varje klassificering är:

  • Sann positiv: MultiStagedAttack (Flera mellanlagrade attacker), MaliciousUserActivity (Skadlig användaraktivitet), CompromisedAccount (komprometterat konto) – överväg att ändra uppräkningsnamnet i det offentliga API:et i enlighet med detta, Malware (Skadlig kod), Phishing (Nätfiske), UnwantedSoftware (oönskad programvara) och Other (Övrigt).
  • Informationsaktivitet, förväntad aktivitet:SecurityTesting (Säkerhetstest), LineOfBusinessApplication (verksamhetsspecifikt program), ConfirmedActivity (bekräftad aktivitet) – överväg att ändra uppräkningsnamnet i det offentliga API:et i enlighet med detta och Other (Övrigt).
  • Falsk positiv identifiering:Clean (Inte skadligt) – överväg att ändra uppräkningsnamnet i det offentliga API:et i enlighet med detta, NoEnoughDataToValidate (Inte tillräckligt med data för att verifiera) och Other (Övrigt).
    		•
    Taggar stränglista Lista över incidenttaggar.
    Kommentar sträng Kommentar som ska läggas till i incidenten.

    Obs!

    Runt den 29 augusti 2022 kommer tidigare stödda aviseringsbestämningsvärden ("Apt" och "SecurityPersonnel") att bli inaktuella och inte längre tillgängliga via API:et.

    Svar

    Om det lyckas returnerar 200 OKden här metoden . Svarstexten innehåller incidententiteten med uppdaterade egenskaper. Om en incident med det angivna ID:t inte hittades returnerar 404 Not Foundmetoden .

    Exempel

    Exempel på begäran

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

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

    Exempel på begärandedata

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

    Tips

    Vill du veta mer? Engage med Microsofts säkerhetscommunity i vår Tech Community: Microsoft Defender XDR Tech Community.