Verweis auf die API für Uploadindikatoren (Vorschau) zum Importieren von Threat Intelligence in Microsoft Sentinel
Mit der Microsoft Sentinel-API für Uploadindikatoren können Threat Intelligence-Plattformen oder benutzerdefinierte Anwendungen Kompromittierungsindikatoren im STIX-Format in einen Microsoft Sentinel-Arbeitsbereich importieren. Unabhängig davon, ob Sie die API mit dem Microsoft Sentinel-API-Datenconnector für Uploadindikatoren oder als Teil einer benutzerdefinierten Lösung verwenden, dient dieses Dokument als Referenz.
Wichtig
Diese API befindet sich derzeit in der VORSCHAU. In den zusätzlichen Nutzungsbestimmungen für Microsoft Azure-Vorschauen finden Sie weitere rechtliche Bedingungen, die für Azure-Features gelten, die sich in der Beta- oder Vorschauversion befinden oder anderweitig noch nicht zur allgemeinen Verfügbarkeit freigegeben sind.
Ein API-Aufruf für Uploadindikatoren umfasst fünf Komponenten:
- Der Anforderungs-URI
- Nachrichtenheader der HTTP-Anforderung
- Nachrichtentext der HTTP-Anforderung
- Optional verarbeiten Sie den Nachrichtenheader der HTTP-Antwort
- Optional verarbeiten Sie den Text der HTTP-Antwort
Registrieren Ihrer Clientanwendung mit Microsoft Entra ID
Um sich bei Microsoft Sentinel zu authentifizieren, erfordert die Anforderung an die API für Uploadindikatoren ein gültiges Microsoft Entra-Zugriffstoken. Weitere Informationen zur Anwendungsregistrierung finden Sie unter Registrieren einer Anwendung mit dem Microsoft Identity Platform oder in den grundlegenden Schritten im Rahmen des Setups des API-Datenconnectors für Uploadindikatoren.
Berechtigungen
Diese API setzt voraus, dass der Microsoft Entra-Anwendung die Rolle „Microsoft Sentinel-Mitwirkender“ auf Arbeitsbereichsebene gewährt wird.
Erstellen der Anforderung
In diesem Abschnitt werden die ersten drei der fünf zuvor erläuterten Komponenten behandelt. Zuerst müssen Sie das Zugriffstoken von Microsoft Entra ID abrufen, das Sie zum Zusammenstellen des Anforderungsnachrichtenheaders verwenden.
Abrufen eines Zugriffstokens
Abrufen eines Microsoft Entra-Zugriffstokens mit OAuth 2.0-Authentifizierung. V1.0 und V2.0 sind gültige Token, die von der API akzeptiert werden.
Die Version des Tokens (v1.0 oder v2.0), das Ihre Anwendung empfängt, wird durch die accessTokenAcceptedVersion-Eigenschaft im App-Manifest der API bestimmt, die Ihre Anwendung aufruft. Wenn accessTokenAcceptedVersion auf 1 festgelegt ist, erhält Ihre Anwendung ein v1.0-Token.
Verwenden Sie die Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL) für das Abrufen eines Zugriffstokens vom Typ v1.0 oder v2.0. Senden Sie alternativ Anforderungen im folgenden Format an die REST-API:
- POST
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - Kopfzeilen für die Verwendung der Microsoft Entra-App:
- grant_type: "client_credentials"
- client_id: {Client-ID der Microsoft Entra-App}
- client_secret: {Geheimnis der Microsoft Entra-App}
- Bereich:
"https://management.azure.com/.default"
Wenn accessTokenAcceptedVersion im App-Manifest auf 1 festgelegt ist, erhält Ihre Anwendung ein v1.0-Zugriffstoken, obwohl sie den v2-Tokenendpunkt aufruft.
Der Ressourcen-/Bereichswert ist die Zielgruppe des Tokens. Diese API akzeptiert nur die folgenden Zielgruppen:
https://management.core.windows.net/https://management.core.windows.nethttps://management.azure.com/https://management.azure.com
Zusammenstellen der Anforderungsnachricht
Es gibt zwei Versionen der Uploadindikatoren-API. Je nach Endpunkt ist im Anforderungstext ein anderer Arrayname erforderlich. Dies wird auch durch zwei Versionen der Logik-App-Connectoraktion dargestellt.
Name der Connectoraktion: Bedrohungserkennung – Uploadindikatoren für Kompromittierung (veraltet)
- Endpunkt:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - Array von Indikatorenname:
value{ "sourcesystem":"TIsource-example", "value":[] }
- Endpunkt:
Name der Connectoraktion: Bedrohungserkennung – Uploadindikatoren für Kompromittierung (V2) (Vorschau)
- Endpunkt:
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - Array von Indikatorenname:
indicators{ "sourcesystem":"TIsource-example", "indicators":[] }
- Endpunkt:
Anforderungs-URI
API-Versionsverwaltung: api-version=2022-07-01
Endpunkt: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
Methode: POST
Anforderungsheader
Authorization: Enthält das OAuth2-Bearertoken
Content-Type: application/json
Anforderungstext
Das JSON-Objekt für den Text enthält die folgenden Felder:
| Feldname | Datentyp | BESCHREIBUNG |
|---|---|---|
| SourceSystem (erforderlich) | Zeichenfolge | Identifizieren Sie den Namen Ihres Quellsystems. Der Wert Microsoft Sentinel ist eingeschränkt. |
| Indikatoren (erforderlich) | array | Ein Array von Indikatoren im STIX 2.0- oder 2.1-Format |
Erstellen Sie das Array von Indikatoren mithilfe der STIX 2.1-Indikatorformatspezifikation, die hier mit Links zu wichtigen Abschnitten zusammengefasst wurde. Beachten Sie auch, dass einige Eigenschaften, obwohl sie für STIX 2.1 gültig sind, nicht über entsprechende Indikatoreigenschaften in Microsoft Sentinel verfügen.
| Eigenschaftenname | Type | BESCHREIBUNG |
|---|---|---|
id (erforderlich) |
Zeichenfolge | Eine ID, die zum Identifizieren des Indikators verwendet wird. In Abschnitt 2.9 finden Sie Spezifikationen zum Erstellen eines id. Die Ausgabe sieht in etwa wie indicator--<UUID> aus |
spec_version (optional) |
Zeichenfolge | STIX-Indikatorversion. Dieser Wert ist in der STIX-Spezifikation erforderlich. Da diese API jedoch nur STIX 2.0 und 2.1 unterstützt, wird die API standardmäßig auf 2.1 gesetzt |
type (erforderlich) |
Zeichenfolge | Der Wert dieser Eigenschaft mussindicator sein. |
created (erforderlich) |
Zeitstempel | Spezifikationen dieser gängigen Eigenschaft finden Sie im Abschnitt 3.2. |
modified (erforderlich) |
Zeitstempel | Spezifikationen dieser gängigen Eigenschaft finden Sie im Abschnitt 3.2. |
name (optional) |
Zeichenfolge | Ein Name, der zum Identifizieren des Indikators verwendet wird. Hersteller sollten diese Eigenschaft bereitstellen, um Produkten und Analysten zu helfen, zu verstehen, was dieser Indikator tatsächlich tut. |
description (optional) |
Zeichenfolge | Eine Beschreibung, die weitere Details und Kontext zum Indikator enthält, einschließlich seines Zwecks und seiner wichtigsten Merkmale. Hersteller sollten diese Eigenschaft bereitstellen, um Produkten und Analysten zu helfen, zu verstehen, was dieser Indikator tatsächlich tut. |
indicator_types (optional) |
Eine Liste von Zeichenfolgen | Eine Reihe von Kategorisierungen für diesen Indikator. Die Werte für diese Eigenschaft sollten aus indicator-type-ov stammen |
pattern (erforderlich) |
Zeichenfolge | Das Erkennungsmuster für diesen Indikator kann als STIX-Muster oder eine andere geeignete Sprache wie SNORT, YARA usw. ausgedrückt werden. |
pattern_type (erforderlich) |
Zeichenfolge | Die Mustersprache, die in diesem Indikator verwendet wird. Der Wert für diese Eigenschaft sollte aus pattern types stammen. Der Wert dieser Eigenschaft muss mit dem Typ der Musterdaten übereinstimmen, die in der pattern-Eigenschaft enthalten sind. |
pattern_version (optional) |
Zeichenfolge | Die Version der Mustersprache, die für die Daten in der pattern-Eigenschaft verwendet wird und die mit dem Typ der in der pattern-Eigenschaft enthaltenen Musterdaten übereinstimmen muss. Für Muster, die keine formale Spezifikation haben, sollte die Build- oder Code-Version verwendet werden, von der bekannt ist, dass sie mit dem Muster funktioniert. Für die STIX-Mustersprache bestimmt die Spezifikationsversion des Objekts den Standardwert. Für andere Sprachen sollte der Standardwert die neueste Version der Mustersprache zum Zeitpunkt der Erstellung dieses Objekts sein. |
valid_from (erforderlich) |
timestamp | Die Zeit, ab der dieser Indikator als gültiger Indikator für das Verhalten betrachtet wird, mit dem er in Beziehung steht oder darstellt. |
valid_until (optional) |
timestamp | Der Zeitpunkt, zu dem dieser Indikator nicht mehr als gültiger Indikator für das Verhalten betrachtet werden sollte, mit dem er im Zusammenhang steht oder darstellt. Wenn die valid_until-Eigenschaft nicht angegeben wird, gibt es keine Einschränkung für die letzte Zeit, für die der Indikator gültig ist. Dieser Zeitstempel muss größer als der valid_from-Zeitstempel sein. |
kill_chain_phases (optional) |
Liste von Zeichenfolgen | Die Kill Chain-Phasen, denen dieser Indikator entspricht. Der Wert für diese Eigenschaft sollte aus der Kill Chain-Phase stammen. |
created_by_ref (optional) |
Zeichenfolge | Die created_by_ref-Eigenschaft gibt die ID-Eigenschaft der Entität an, die dieses Objekt erstellt hat. Wenn dieses Attribut nicht angegeben wird, ist die Quelle dieser Informationen undefiniert. Für Objektersteller, die anonym bleiben möchten, sollte dieser Wert nicht definiert werden. |
revoked (optional) |
boolean | Widerrufene Objekte werden vom Objektersteller als nicht mehr gültig betrachtet. Das Widerrufen eines Objekts ist dauerhaft; Zukünftige Versionen des Objekts mit diesem id Objekt dürfen nicht erstellt werden.Der Standardwert dieser Eigenschaft ist false. |
labels (optional) |
Eine Liste von Zeichenfolgen | Die labels-Eigenschaft gibt einen Satz von Begriffen an, die zum Beschreiben dieses Objekts verwendet werden. Die Begriffe sind benutzerdefiniert oder vertrauensgruppendefiniert. Diese Bezeichnungen werden in Microsoft Sentinel als Tags angezeigt. |
confidence (optional) |
integer | Die confidence-Eigenschaft gibt an, wie viel Vertrauen der Ersteller in die Richtigkeit seiner Daten hat. Der Konfidenzwert muss eine Zahl im Bereich von 0 bis 100 sein.Anhang A enthält eine Tabelle mit normativen Zuordnungen zu anderen Konfidenzskalen, die bei der Darstellung des Konfidenzwerts in einer dieser Skalierungen verwendet werden müssen. Wenn die confidence-Eigenschaft nicht vorhanden ist, ist die Konfidenz des Inhalts nicht angegeben. |
lang (optional) |
Zeichenfolge | Die lang-Eigenschaft gibt die Sprache des Textinhalts in diesem Objekt an. Wenn vorhanden, muss es ein Sprachcode sein, der RFC5646 entspricht. Wenn die Eigenschaft nicht vorhanden ist, ist en (Englisch) die Sprache des Inhalts.Diese Eigenschaft sollte vorhanden sein, wenn der Objekttyp übersetzbare Texteigenschaften (z. B. Name, Beschreibung) enthält. Die Sprache einzelner Felder in diesem Objekt kann die lang-Eigenschaft in granularen Markierungen überschreiben (siehe Abschnitt 7.2.3). |
object_marking_refs (optional, einschließlich TLP) |
Eine Liste von Zeichenfolgen | Die object_marking_refs-Eigenschaft gibt eine Liste der ID-Eigenschaften von Markierungsdefinitionsobjekten an, die für dieses Objekt gelten. Verwenden Sie beispielsweise die Definitions-ID der Markierungs-ID des Traffic Light Protocol (TLP), um die Vertraulichkeit der Indikatorquelle anzugeben. Ausführliche Informationen dazu, welche Markierungsdefinitions-IDs für TLP-Inhalte verwendet werden sollen, finden Sie in Abschnitt 7.2.1.4.In einigen, wenn auch seltenen Fällen können Markierungsdefinitionen selbst mithilfe von Freigabe- oder Behandlungsanleitungen gekennzeichnet sein. In diesem Fall darf diese Eigenschaft keine Verweise auf dasselbe Marking Definition-Objekt enthalten (das heißt, es darf keine Zirkelbezüge enthalten). Weitere Definitionen von Datenmarkierungen finden Sie in Abschnitt 7.2.2 . |
external_references (optional) |
Objektliste | Die external_references-Eigenschaft gibt eine Liste externer Verweise an, die auf Nicht-STIX-Informationen verweist. Diese Eigenschaft wird verwendet, um eine oder mehrere URLs, Beschreibungen oder IDs für Datensätze in anderen Systemen. |
granular_markings (optional) |
Liste der granularen Markierungen | Die granular_markings-Eigenschaft hilft dabei, Teile des Indikators unterschiedlich zu definieren. Die Indikatorsprache ist beispielsweise Englisch, en, aber die Beschreibung ist Deutsch, de.In einigen, wenn auch seltenen Fällen können Markierungsdefinitionen selbst mithilfe von Freigabe- oder Behandlungsanleitungen gekennzeichnet sein. In diesem Fall darf diese Eigenschaft keine Verweise auf dasselbe Marking Definition-Objekt enthalten (d. h. es darf keine Zirkelbezüge enthalten). Weitere Definitionen von Datenmarkierungen finden Sie in Abschnitt 7.2.3. |
Verarbeiten der Antwortnachricht
Der Antwortheader enthält einen HTTP-Statuscode. Weitere Informationen zum Interpretieren des API-Aufrufergebnisses finden Sie in dieser Tabelle.
| Statuscode | BESCHREIBUNG |
|---|---|
| 200 | Erfolg. Die API gibt 200 zurück, wenn mindestens ein Indikator erfolgreich überprüft und veröffentlicht wurde. |
| 400 | Fehlerhaftes Format. Etwas in der Anforderung ist nicht ordnungsgemäß formatiert. |
| 401 | Nicht autorisiert. |
| 404 | Die Datei wurde nicht gefunden. Normalerweise tritt dieser Fehler auf, wenn die Arbeitsbereichs-ID nicht gefunden wird. |
| 429 | Die Anzahl der Anforderungen in einer Minute wurde überschritten. |
| 500 | Serverfehler. In der Regel ein Fehler in der API oder in Microsoft Sentinel-Diensten. |
Der Antworttext ist ein Array von Fehlermeldungen im JSON-Format:
| Feldname | Datentyp | BESCHREIBUNG |
|---|---|---|
| errors | Array von Fehlerobjekten | Liste der Überprüfungsfehler |
Error-Objekt
| Feldname | Datentyp | BESCHREIBUNG |
|---|---|---|
| recordIndex | INT | Index der Indikatoren in der Anforderung |
| errorMessages | Array von Zeichenfolgen | Fehlermeldungen |
Drosselungsgrenzwerte für die API
Alle Grenzwerte werden pro Benutzer angewendet:
- 100 Indikatoren pro Anforderung.
- 100 Anforderungen pro Minute.
Wenn mehr Anforderungen als der Grenzwert vorhanden sind, wird ein 429-HTTP-Statuscode im Antwortheader mit dem folgenden Antworttext zurückgegeben:
{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}
Ungefähr 10.000 Indikatoren pro Minute ist der maximale Durchsatz, bevor ein Drosselungsfehler empfangen wird.
Beispielanforderungstext
{
"sourcesystem": "test",
"indicators":[
{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--10000003-71a2-445c-ab86-927291df48f8",
"name": "Test Indicator 1",
"created": "2010-02-26T18:29:07.778Z",
"modified": "2011-02-26T18:29:07.778Z",
"pattern": "[ipv4-addr:value = '172.29.6.7']",
"pattern_type": "stix",
"valid_from": "2015-02-26T18:29:07.778Z"
},
{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--67e62408-e3de-4783-9480-f595d4fdae52",
"created": "2023-01-01T18:29:07.778Z",
"modified": "2025-02-26T18:29:07.778Z",
"created_by_ref": "identity--19f33886-d196-468e-a14d-f37ff0658ba7",
"revoked": false,
"labels": [
"label 1",
"label 2"
],
"confidence": 55,
"lang": "en",
"external_references": [
{
"source_name": "External Test Source",
"description": "Test Report",
"external_id": "e8085f3f-f2b8-4156-a86d-0918c98c498f",
"url": "https://fabrikam.com//testreport.json",
"hashes": {
"SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
}
}
],
"object_marking_refs": [
"marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"
],
"granular_markings": [
{
"marking_ref": "marking-definition--beb3ec79-03aa-4594-ad24-09982d399b80",
"selectors": [ "description", "labels" ],
"lang": "en"
}
],
"name": "Test Indicator 2",
"description": "This is a test indicator to demo valid fields",
"indicator_types": [
"threatstream-severity-low", "threatstream-confidence-80"
],
"pattern": "[ipv4-addr:value = '192.168.1.1']",
"pattern_type": "stix",
"pattern_version": "2.1",
"valid_from": "2023-01-01T18:29:07.778Z",
"valid_until": "2025-02-26T18:29:07.778Z",
"kill_chain_phases": [
{
"kill_chain_name": "lockheed-martin-cyber-kill-chain",
"phase_name": "reconnaissance"
}
]
}
]
}
Beispielantworttext mit Überprüfungsfehler
Wenn alle Indikatoren erfolgreich überprüft wurden, wird ein HTTP 200-Status mit einem leeren Antworttext zurückgegeben.
Wenn die Überprüfung für einen oder mehrere Indikatoren fehlschlägt, wird der Antworttext mit weiteren Informationen zurückgegeben. Wenn Sie beispielsweise ein Array mit vier Indikatoren senden, und die ersten drei sind gut, aber das vierte kein id (ein erforderliches Feld) hat, wird eine HTTP-Statuscode-200-Antwort zusammen mit dem folgenden Text generiert:
{
"errors": [
{
"recordIndex":3,
"errorMessages": [
"Error for Property=id: Required property is missing. Actual value: NULL."
]
}
]
}
Die Indikatoren werden als Array gesendet, sodass recordIndex bei 0 beginnt.
Nächste Schritte
Weitere Informationen zum Arbeiten mit Threat Intelligence in Microsoft Sentinel finden Sie in den folgenden Artikeln:
- Grundlegendes zu Threat Intelligence
- Verwenden von Bedrohungsindikatoren
- Verwenden von Abgleichanalysen zum Erkennen von Bedrohungen
- Verwenden des Intelligence-Feeds von Microsoft und Aktivieren des MDTI-Datenconnectors