Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Die Microsoft Sentinel-API zum Hochladen von Indikatoren ermöglicht es Threat Intelligence-Plattformen oder benutzerdefinierten Anwendungen, Gefährdungsindikatoren im STIX-Format in einen Microsoft Sentinel-Arbeitsbereich zu importieren. Dieses Dokument dient als Verweis auf die Legacy-API.
Wichtig
Diese API befindet sich in der VORSCHAU, wird aber nicht mehr empfohlen. Verwenden Sie die neue STIX-Objekt-API in der Vorschau, um Threat Intelligence hochzuladen. Weitere Informationen finden Sie unter STIX-Objekt-API. Die zusätzlichen Azure-Vorschaubedingungen enthalten zusätzliche rechtliche Bestimmungen, die für Azure Features gelten, die sich in der Betaversion, Vorschauversion oder anderweitig noch nicht in der allgemeinen Verfügbarkeit befinden.
Ein API-Aufruf von Uploadindikatoren umfasst fünf Komponenten:
- Der Anforderungs-URI
- HTTP-Anforderungsnachrichtenheader
- Text der HTTP-Anforderungsnachricht
- Optionales Verarbeiten des HTTP-Antwortnachrichtenheaders
- Optionales Verarbeiten des HTTP-Antwortnachrichtentexts
Registrieren Ihrer Clientanwendung bei 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 der Einrichtung des API-Datenconnectors zum Hochladen von Indikatoren.
Berechtigungen
Für diese API muss der aufrufenden Microsoft Entra Anwendung die rolle Microsoft Sentinel Mitwirkender auf Arbeitsbereichsebene zugewiesen werden.
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, mit dem Sie ihren Anforderungsnachrichtenheader zusammenstellen.
Abrufen eines Zugriffstokens
Rufen Sie ein Microsoft Entra-Zugriffstoken mit OAuth 2.0-Authentifizierung ab. 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 MSAL , um ein v1.0- oder v2.0-Zugriffstoken abzurufen. Oder senden Sie Anforderungen im folgenden Format an die REST-API:
- POST
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - Header für die Verwendung von Microsoft Entra App:
- grant_type: "client_credentials"
- client_id: {Client-ID der Microsoft Entra-App}
- client_secret: {secret of Microsoft Entra App}
- Umfang:
"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 gab zwei Versionen der Legacy-API. Je nach Endpunkt war im Anforderungstext ein anderer Arrayname erforderlich. Dies wurde auch durch zwei Versionen der Logik-App-Connectoraktion dargestellt.
- Name der Connectoraktion: Threat Intelligence – Upload indicators of Compromise (Veraltet)
- Endpunkt:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - Name des Arrays von Indikatoren:
value
- Endpunkt:
- Name der Connectoraktion: Threat Intelligence – Upload indicators of Compromise (V2) (Vorschau)
- Endpunkt:
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - Name des Arrays von Indikatoren:
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) | string | 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 außerdem, dass einige Eigenschaften zwar für STIX 2.1 gültig sind, aber keine entsprechenden Indikatoreigenschaften in Microsoft Sentinel haben.
| Eigenschaftenname | Typ | Beschreibung |
|---|---|---|
id (erforderlich) |
string | Eine ID, die zum Identifizieren des Indikators verwendet wird. In Abschnitt 2.9 finden Sie Spezifikationen zum Erstellen eines id. Das Format sieht in etwa wie folgt aus: indicator--<UUID> |
spec_version (optional) |
string | STIX-Indikatorversion. Dieser Wert ist in der STIX-Spezifikation erforderlich, aber da diese API nur STIX 2.0 und 2.1 unterstützt, wird die API standardmäßig auf 2.1 |
type (erforderlich) |
string | Der Wert dieser Eigenschaft muss sein indicator. |
created (erforderlich) |
Timestamp | In Abschnitt 3.2 finden Sie Spezifikationen dieser gemeinsamen Eigenschaft. |
modified (erforderlich) |
Timestamp | In Abschnitt 3.2 finden Sie Spezifikationen dieser gemeinsamen Eigenschaft. |
name (optional) |
string | Ein Name, der zum Identifizieren des Indikators verwendet wird. Produzenten sollten diese Eigenschaft bereitstellen, um Produkten und Analysten zu helfen, zu verstehen, was dieser Indikator tatsächlich bewirkt. |
description (optional) |
string | Eine Beschreibung, die weitere Details und Kontext zum Indikator enthält, einschließlich seines Zwecks und seiner wichtigsten Merkmale. Produzenten sollten diese Eigenschaft bereitstellen, um Produkten und Analysten zu helfen, zu verstehen, was dieser Indikator tatsächlich bewirkt. |
indicator_types (optional) |
Liste der Zeichenfolgen | Ein Satz von Kategorisierungen für diesen Indikator. Die Werte für diese Eigenschaft sollten von indikator-type-ov stammen. |
pattern (erforderlich) |
string | 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) |
string | Die in diesem Indikator verwendete Mustersprache. Der Wert für diese Eigenschaft sollte von Mustertypen stammen. Der Wert dieser Eigenschaft muss mit dem Typ der Musterdaten übereinstimmen, die in der Mustereigenschaft enthalten sind. |
pattern_version (optional) |
string | Die Version der Mustersprache, die für die Daten in der Mustereigenschaft verwendet wird, die mit dem Typ der Musterdaten übereinstimmen muss , die in der Mustereigenschaft enthalten sind. Für Muster, die keine formale Spezifikation aufweisen, sollte die Build- oder Codeversion verwendet werden, mit der das Muster bekannt ist. 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 angesehen werden sollte, mit dem er in Beziehung 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 der 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) |
string | 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 nicht definiert. Für Objektersteller, die anonym bleiben möchten, behalten Sie diesen Wert undefiniert bei. |
revoked (optional) |
Boolescher Wert | Widerrufene Objekte werden vom Objektersteller nicht mehr als gültig betrachtet. Das Widerrufen eines Objekts ist dauerhaft; zukünftige Versionen des Objekts mit diesem iddürfen nicht erstellt werden.Der Standardwert dieser Eigenschaft ist false. |
labels (optional) |
Liste der Zeichenfolgen | Die labels -Eigenschaft gibt einen Satz von Begriffen an, die zum Beschreiben dieses Objekts verwendet werden. Die Begriffe sind benutzerdefinierte oder vertrauensgruppendefiniert. Diese Bezeichnungen werden in Microsoft Sentinel als Tags angezeigt. |
confidence (optional) |
ganze Zahl | Die confidence -Eigenschaft identifiziert die Zuverlässigkeit, die 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 Konfidenzeigenschaft nicht vorhanden ist, ist die Konfidenz des Inhalts nicht angegeben. |
lang (optional) |
string | Die lang -Eigenschaft identifiziert die Sprache des Textinhalts in diesem Objekt. Wenn vorhanden, muss es sich um einen Sprachcode sein, der RFC5646 entspricht. Wenn die Eigenschaft nicht vorhanden ist, ist en die Sprache des Inhalts (Englisch).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 präzisen Markierungen überschreiben (siehe Abschnitt 7.2.3). |
object_marking_refs (optional, einschließlich TLP) |
Liste der 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 Markierungs-ID des Traffic Light Protocol (TLP), um die Empfindlichkeit der Indikatorquelle anzugeben. Ausführliche Informationen dazu, welche Kennzeichnungsdefinitions-IDs für TLP-Inhalte verwendet werden sollen, finden Sie in Abschnitt 7.2.1.4.In einigen Fällen, obwohl ungewöhnlich, können Markierungsdefinitionen selbst mit Freigabe- oder Behandlungsanleitungen gekennzeichnet werden. In diesem Fall darf diese Eigenschaft keine Verweise auf dasselbe Marking Definition-Objekt enthalten (d.a. es darf keine Zirkelverweise 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 bereitzustellen. |
granular_markings (optional) |
Liste der granularen Markierungen | Die granular_markings -Eigenschaft hilft dabei, Teile des Indikators unterschiedlich zu definieren. Die Indikatorsprache ist z. B. Englisch, en aber die Beschreibung ist Deutsch, de.In einigen Fällen, obwohl ungewöhnlich, können Markierungsdefinitionen selbst mit Freigabe- oder Behandlungsanleitungen gekennzeichnet werden. In diesem Fall darf diese Eigenschaft keine Verweise auf dasselbe Marking Definition-Objekt enthalten (d. h., es darf keine Zirkelverweise enthalten). Weitere Definitionen von Datenmarkierungen finden Sie in Abschnitt 7.2.3 . |
Verarbeiten der Antwortnachricht
Der Antwortheader enthält einen HTTP-status Code. Weitere Informationen zum Interpretieren des API-Aufrufergebnisses finden Sie in dieser Tabelle.
| Statuscode | Beschreibung |
|---|---|
| 200 | Erfolg. Die API gibt 200 zurück, wenn ein oder mehrere Indikatoren erfolgreich überprüft und veröffentlicht wurden. |
| 400 | Ungültiges Format. Etwas in der Anforderung ist nicht ordnungsgemäß formatiert. |
| 401 | Unbefugt. |
| 404 | Die Datei wurde nicht gefunden. In der Regel 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 Microsoft Sentinel Diensten. |
Der Antworttext ist ein Array von Fehlermeldungen im JSON-Format:
| Feldname | Datentyp | Beschreibung |
|---|---|---|
| errors | Array von Fehlerobjekten | Liste der Validierungsfehler |
Error-Objekt
| Feldname | Datentyp | Beschreibung |
|---|---|---|
| recordIndex | int | Index der Indikatoren in der Anforderung |
| errorMessages | Array aus 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-status-Code 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 sind 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 z. B. ein Array mit vier Indikatoren senden und die ersten drei gut sind, aber das vierte nicht id (ein erforderliches Feld) enthält, wird eine HTTP-status Code 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 bei recordIndex beginnt 0.
Nächster Schritt
Diese API ist legacy. Migrieren Sie, um die STIX-Objekt-API zum Hochladen von Threat Intelligence zu verwenden. Weitere Informationen finden Sie unter STIX-Objekt-API.