Api zum Aktualisieren von Incidents

  • Artikel

Gilt für:

Hinweis

Testen Sie unsere neuen APIs mithilfe der MS Graph-Sicherheits-API. Weitere Informationen finden Sie unter : Verwenden der Microsoft Graph-Sicherheits-API – Microsoft Graph | Microsoft Learn. Informationen zur neuen Updatevorfall-API mithilfe der MS Graph-Sicherheits-API finden Sie unter Update incident.

Wichtig

Einige Informationen beziehen sich auf Vorabversionen von Produkten, die vor der kommerziellen Veröffentlichung noch erheblich geändert werden können. Microsoft übernimmt mit diesen Informationen keinerlei Gewährleistung, sei sie ausdrücklich oder konkludent.

API-Beschreibung

Updates Eigenschaften eines vorhandenen Incidents. Aktualisierbare Eigenschaften sind: status, determination, classification, assignedTo, tagsund comments.

Kontingente, Ressourcenzuordnung und andere Einschränkungen

  1. Sie können bis zu 50 Anrufe pro Minute oder 1.500 Anrufe pro Stunde tätigen, bevor Sie den Drosselungsschwellenwert erreichen.
  2. Sie können die determination Eigenschaft nur festlegen, wenn classification auf TruePositive festgelegt ist.

Wenn Ihre Anforderung gedrosselt ist, wird ein 429 Antwortcode zurückgegeben. Der Antworttext gibt den Zeitpunkt an, zu dem Sie mit dem Tätigen neuer Aufrufe beginnen können.

Berechtigungen

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, einschließlich der Auswahl von Berechtigungen, finden Sie unter Zugreifen auf die Microsoft Defender XDR-APIs.

Berechtigungstyp Berechtigung Anzeigename der Berechtigung
App Incident.ReadWrite.All Lesen und Schreiben aller Incidents
Delegiert (Geschäfts-, Schul- oder Unikonto) Incident.ReadWrite Lese- und Schreibvorfälle

Hinweis

Beim Abrufen eines Tokens mithilfe von Benutzeranmeldeinformationen muss der Benutzer über die Berechtigung zum Aktualisieren des Incidents im Portal verfügen.

HTTP-Anforderung

PATCH /api/incidents/{id}

Anforderungsheader

Name Typ Beschreibung
Authorization String Bearer {token}. Erforderlich.
Content-Type Zeichenfolge application/json. Erforderlich.

Anforderungstext

Geben Sie im Anforderungstext die Werte für die Felder an, die aktualisiert werden sollen. Vorhandene Eigenschaften, die nicht im Anforderungstext enthalten sind, behalten ihre Werte bei, es sei denn, sie müssen aufgrund von Änderungen an verwandten Werten neu berechnet werden. Um eine optimale Leistung zu erzielen, sollten Sie vorhandene Werte weglassen, die sich nicht geändert haben.

Eigenschaft Typ Beschreibung
status Enum Gibt die aktuelle status des Incidents an. Mögliche Werte sind: Active, Resolved, InProgress, und Redirected.
assignedTo string Besitzer des Incidents.
classification Enum Spezifikation des Incidents. Mögliche Werte sind: TruePositive (Wahr positiv), InformationalExpectedActivity (Information, erwartete Aktivität) und FalsePositive (Falsch positiv).
Bestimmung Enum Gibt die Ermittlung des Incidents an.

Mögliche Bestimmungswerte für jede Klassifizierung sind:

  • Richtig positiv: MultiStagedAttack (mehrstufiger Angriff), MaliciousUserActivity (Böswillige Benutzeraktivität), CompromisedAccount (Kompromittiertes Konto) – erwägen Sie, den Enumerationsnamen in der öffentlichen API entsprechend (Malware), Phishing (Phishing), UnwantedSoftware (Unerwünschte Software) und Other (Sonstige) zu Malware ändern.
  • Information, erwartete Aktivität:SecurityTesting (Sicherheitstest), LineOfBusinessApplication (Branchenanwendung), ConfirmedActivity (Bestätigte Aktivität): Erwägen Sie, den Enumerationsnamen in der öffentlichen API entsprechend und Other (Sonstige) zu ändern.
  • Falsch positiv:Clean (Nicht böswillig) – Erwägen Sie, den Enumerationsnamen in der öffentlichen API entsprechend zu ändern, NoEnoughDataToValidate (Nicht genügend Daten zum Überprüfen) und Other (Sonstige).
    		•
    tags Zeichenfolgenliste Liste der Incidenttags.
    Kommentar string Kommentar, der dem Incident hinzugefügt werden soll.

    Hinweis

    Ab dem 29. August 2022 sind die zuvor unterstützten Warnungsermittlungswerte ("Apt" und "SecurityPersonnel") veraltet und nicht mehr über die API verfügbar.

    Antwort

    Bei erfolgreicher Ausführung gibt die Methode zurück 200 OK. Der Antworttext enthält die Incidententität mit aktualisierten Eigenschaften. Wenn kein Incident mit der angegebenen ID gefunden wurde, gibt die Methode zurück 404 Not Found.

    Beispiel

    Anforderungsbeispiel

    Hier sehen Sie ein Beispiel für die Anforderung.

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

    Beispiel für Anforderungsdaten

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

    Tipp

    Möchten Sie mehr erfahren? Engage mit der Microsoft-Sicherheitscommunity in unserer Tech Community: Microsoft Defender XDR Tech Community.