Odkazování na rozhraní API indikátorů nahrávání (Preview) pro import analýzy hrozeb do Služby Microsoft Sentinel
Rozhraní API indikátorů nahrávání z Microsoft Sentinelu umožňuje platformám analýzy hrozeb nebo vlastním aplikacím importovat indikátory ohrožení ve formátu STIX do pracovního prostoru Služby Microsoft Sentinel. Bez ohledu na to, jestli používáte rozhraní API s datovým konektorem rozhraní API indikátorů pro nahrávání z Microsoft Sentinelu nebo jako součást vlastního řešení, slouží tento dokument jako odkaz.
Důležité
Toto rozhraní API je aktuálně ve verzi PREVIEW. Dodatkové podmínky Azure Preview zahrnují další právní podmínky, které se vztahují na funkce Azure, které jsou v beta verzi, preview nebo které ještě nejsou vydány v obecné dostupnosti.
Volání rozhraní API pro nahrání indikátorů má pět komponent:
- Identifikátor URI požadavku
- Hlavička zprávy požadavku HTTP
- Text zprávy požadavku HTTP
- Volitelně můžete zpracovat hlavičku zprávy odpovědi HTTP.
- Volitelně zpracovat text zprávy odpovědi HTTP
Registrace klientské aplikace pomocí Microsoft Entra ID
Aby bylo možné provést ověření v Microsoft Sentinelu, požadavek na rozhraní API pro indikátory nahrávání vyžaduje platný přístupový token Microsoft Entra. Další informace o registraci aplikace najdete v tématu Registrace aplikace na platformě Microsoft Identity Platform nebo se podívejte na základní kroky v rámci nastavení datového konektorurozhraní API pro nahrání indikátorů.
Oprávnění
Toto rozhraní API vyžaduje, aby volající aplikaci Microsoft Entra byla udělena role přispěvatele Microsoft Sentinelu na úrovni pracovního prostoru.
Vytvoření požadavku
Tato část popisuje první tři z pěti součástí, které jsme probírali dříve. Nejdřív musíte získat přístupový token z ID Microsoft Entra, které použijete k sestavení hlavičky zprávy požadavku.
Získání přístupového tokenu
Získejte přístupový token Microsoft Entra pomocí ověřování OAuth 2.0. Rozhraní API přijímá platné tokeny V1.0 a V2.0 .
Verze tokenu (v1.0 nebo v2.0), kterou vaše aplikace přijímá, je určena accessTokenAcceptedVersion vlastností v manifestu aplikace rozhraní API, které vaše aplikace volá. Pokud accessTokenAcceptedVersion je nastavená hodnota 1, aplikace obdrží token verze 1.0.
K získání přístupového tokenu v1.0 nebo v2.0 použijte knihovnu MSAL knihovny Microsoft Authentication Library. Nebo odešlete požadavky do rozhraní REST API v následujícím formátu:
- PŘÍSPĚVEK
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - Hlavičky pro používání aplikace Microsoft Entra:
- grant_type: "client_credentials"
- client_id: {ID klienta aplikace Microsoft Entra}
- client_secret: {secret of Microsoft Entra App}
- Rozsah:
"https://management.azure.com/.default"
Pokud accessTokenAcceptedVersion je v manifestu aplikace nastavená hodnota 1, aplikace obdrží přístupový token verze 1.0, i když volá koncový bod tokenu v2.
Hodnota prostředku nebo oboru je cílová skupina tokenu. Toto rozhraní API přijímá pouze následující cílové skupiny:
https://management.core.windows.net/https://management.core.windows.nethttps://management.azure.com/https://management.azure.com
Sestavení zprávy požadavku
Identifikátor URI žádosti
Správa verzí rozhraní API: api-version=2022-07-01
Koncový bod: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators?api-version=2022-07-01
Metoda: POST
Hlavička požadavku
Authorization: Obsahuje nosný token OAuth2.
Content-Type: application/json
Text požadavku
Objekt JSON pro tělo obsahuje následující pole:
| Název pole | Datový typ | Popis |
|---|---|---|
| SourceSystem (povinné) | řetězec | Identifikujte název zdrojového systému. Hodnota Microsoft Sentinel je omezená. |
| Hodnota (povinné) | pole | Pole ukazatelů ve formátu STIX 2.0 nebo 2.1 |
Vytvořte pole ukazatelů pomocí specifikace formátu ukazatele STIX 2.1, která byla zde zhuštěna pro usnadnění práce s odkazy na důležité části. Všimněte si také některých vlastností, zatímco platí pro STIX 2.1, nemají odpovídající vlastnosti indikátoru v Microsoft Sentinelu.
| Název vlastnosti | Typ | Popis |
|---|---|---|
id (povinné) |
řetězec | ID použité k identifikaci ukazatele. V části 2.9 naleznete specifikace, jak vytvořit id. Formát vypadá nějak takto: indicator--<UUID> |
spec_version (volitelné) |
řetězec | Verze indikátoru STIX. Tato hodnota je vyžadována ve specifikaci STIX, ale protože toto rozhraní API podporuje pouze STIX 2.0 a 2.1, pokud toto pole není nastavené, rozhraní API se ve výchozím nastavení nastaví na 2.1 |
type (povinné) |
řetězec | Hodnota této vlastnosti musí být indicator. |
created (povinné) |
časové razítko | Viz část 3.2 specifikace této společné vlastnosti. |
modified (povinné) |
časové razítko | Viz část 3.2 specifikace této společné vlastnosti. |
name (volitelné) |
řetězec | Název použitý k identifikaci ukazatele. Producenti by měli tuto vlastnost poskytnout, aby pomohli produktům a analytikům pochopit, co tento ukazatel skutečně dělá. |
description (volitelné) |
řetězec | Popis, který poskytuje další podrobnosti a kontext ukazatele, potenciálně včetně jeho účelu a klíčových charakteristik. Producenti by měli tuto vlastnost poskytnout, aby pomohli produktům a analytikům pochopit, co tento ukazatel skutečně dělá. |
indicator_types (volitelné) |
seznam řetězců | Sada kategorizací pro tento ukazatel. Hodnoty této vlastnosti by měly pocházet z ukazatele typu ov. |
pattern (povinné) |
řetězec | Vzor detekce pro tento indikátor může být vyjádřen jako vzorování STIX nebo jiný vhodný jazyk, jako je SNORT, YARA atd. |
pattern_type (povinné) |
řetězec | Jazyk vzoru použitý v tomto indikátoru. Hodnota této vlastnosti by měla pocházet z typů vzorů. Hodnota této vlastnosti se musí shodovat s typem vzorových dat zahrnutých ve vlastnosti vzoru. |
pattern_version (volitelné) |
řetězec | Verze jazyka vzoru používaného pro data ve vlastnosti vzoru, která se musí shodovat s typem vzorových dat zahrnutých ve vlastnosti vzoru. U vzorů, které nemají formální specifikaci, by se měl použít build nebo verze kódu, se kterou tento vzor pracuje. Pro jazyk vzoru STIX určuje verze specifikace objektu výchozí hodnotu. V jiných jazycích by výchozí hodnota měla být nejnovější verzí jazyka vzorování v době vytvoření tohoto objektu. |
valid_from (povinné) |
časové razítko | Čas, od kterého je tento indikátor považován za platný indikátor chování, se kterým souvisí nebo představuje. |
valid_until (volitelné) |
časové razítko | Čas, kdy by se tento indikátor již neměl považovat za platný indikátor chování, se kterým souvisí nebo představuje. Pokud je vlastnost valid_until vynechána, není k dispozici žádné omezení posledního času, pro který je indikátor platný. Toto časové razítko musí být větší než časové razítko valid_from. |
kill_chain_phases (volitelné) |
seznam řetězců | Fáze ukončení řetězu, ke kterým tento ukazatel odpovídá. Hodnota této vlastnosti by měla pocházet z fáze Kill Chain. |
created_by_ref (volitelné) |
řetězec | Vlastnost created_by_ref určuje vlastnost ID entity, která tento objekt vytvořila. Pokud tento atribut vynecháte, zdroj těchto informací není definován. Pro tvůrce objektů, kteří chtějí zůstat anonymní, ponechte tuto hodnotu nedefinovanou. |
revoked (volitelné) |
boolean | Odvolané objekty už tvůrce objektu nepovažuje za platné. Odvolání objektu je trvalé; budoucí verze objektu s tímto idobjektem nesmí být vytvořeny.Výchozí hodnota této vlastnosti je false. |
labels (volitelné) |
seznam řetězců | Vlastnost labels určuje sadu termínů použitých k popisu tohoto objektu. Termíny jsou definované uživatelem nebo skupina důvěryhodnosti. Tyto popisky se v Microsoft Sentinelu zobrazí jako značky . |
confidence (volitelné) |
integer | Vlastnost confidence identifikuje jistotu, že tvůrce má ve správnosti svých dat. Hodnota spolehlivosti musí být číslo v rozsahu od 0 do 100.Příloha A obsahuje tabulku normativních mapování na jiná měřítka spolehlivosti, která se musí použít při prezentování hodnoty spolehlivosti v jednom z těchto škál. Pokud vlastnost spolehlivosti není k dispozici, není zadána spolehlivost obsahu. |
lang (volitelné) |
řetězec | Vlastnost lang identifikuje jazyk textového obsahu v tomto objektu. Pokud je k dispozici, musí se jednat o kód jazyka, který odpovídá RFC5646. Pokud vlastnost není k dispozici, jazyk obsahu je en (angličtina).Tato vlastnost by měla být k dispozici, pokud typ objektu obsahuje přeložitelné textové vlastnosti (například název, popis). Jazyk jednotlivých polí v tomto objektu může vlastnost přepsat lang v podrobných označeních (viz bod 7.2.3). |
object_marking_refs (volitelné, včetně TLP) |
seznam řetězců | Vlastnost object_marking_refs určuje seznam vlastností ID objektů definice označení, které se vztahují na tento objekt. K určení citlivosti zdroje indikátoru použijte například ID definice označení TLP (Traffic Light Protocol). Podrobnosti o tom, jaká ID definic označení se mají použít pro obsah TLP, najdete v části 7.2.1.4.V některých případech, i když neobvyklé, označení definic samotných může být označeno pokyny ke sdílení nebo zpracování. V tomto případě nesmí tato vlastnost obsahovat žádné odkazy na stejný objekt definice označení (to znamená, že nemůže obsahovat žádné cyklický odkazy). Další definice označení dat najdete v oddílu 7.2.2 . |
external_references (volitelné) |
seznam objektů | Vlastnost external_references určuje seznam externích odkazů, které odkazují na informace jiné než STIX. Tato vlastnost slouží k poskytnutí jedné nebo více adres URL, popisů nebo ID záznamů v jiných systémech. |
granular_markings (volitelné) |
seznam podrobného označení | Vlastnost granular_markings pomáhá definovat části ukazatele odlišně. Například jazyk ukazatele je angličtina, en ale popis je němčina, de.V některých případech, i když neobvyklé, označení definic samotných může být označeno pokyny ke sdílení nebo zpracování. V tomto případě nesmí tato vlastnost obsahovat žádné odkazy na stejný objekt definice označení (tj. nesmí obsahovat žádné cyklický odkazy). Další definice označení dat najdete v části 7.2.3 . |
Zpracování zprávy odpovědi
Hlavička odpovědi obsahuje stavový kód HTTP. Další informace o interpretaci výsledku volání rozhraní API najdete v této tabulce.
| Stavový kód | Popis |
|---|---|
| 200 | Úspěch Rozhraní API vrátí hodnotu 200, když se jeden nebo více indikátorů úspěšně ověří a publikuje. |
| 400 | Chybný formát. Něco v požadavku není správně naformátované. |
| 401 | Neautorizováno |
| 404 | Soubor nebyl nalezen. K této chybě obvykle dochází, když se ID pracovního prostoru nenajde. |
| 429 | Počet požadavků za minutu překročil. |
| 500 | Chyba serveru. Obvykle došlo k chybě v rozhraní API nebo službách Microsoft Sentinel. |
Text odpovědi je pole chybových zpráv ve formátu JSON:
| Název pole | Datový typ | Popis |
|---|---|---|
| chyby | Pole chybových objektů | Seznam chyb ověření |
Objekt chyby
| Název pole | Datový typ | Popis |
|---|---|---|
| recordIndex | int | Index indikátorů v požadavku |
| errorMessages | Pole řetězců | Chybové zprávy |
Omezení omezení pro rozhraní API
Na uživatele se použijí všechna omezení:
- 100 indikátorů na žádost.
- 100 požadavků za minutu.
Pokud existuje více požadavků, než je limit, vrátí se stavový 429 kód HTTP v hlavičce odpovědi s následujícím textem odpovědi:
{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}
Přibližně 10 000 indikátorů za minutu je maximální propustnost před přijetí chyby omezování.
Ukázkový text požadavku
{
"sourcesystem": "test",
"value":[
{
"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"
}
]
}
]
}
Ukázkový text odpovědi s chybou ověření
Pokud jsou všechny indikátory úspěšně ověřeny, vrátí se stav HTTP 200 s prázdným textem odpovědi.
Pokud ověření selže u jednoho nebo více indikátorů, text odpovědi se vrátí s dalšími informacemi. Pokud například odešlete pole se čtyřmi indikátory a první tři jsou dobré, ale čtvrtý pole nemá id (povinné pole), vygeneruje se spolu s následujícím textem odpověď stavového kódu HTTP 200:
{
"errors": [
{
"recordIndex":3,
"errorMessages": [
"Error for Property=id: Required property is missing. Actual value: NULL."
]
}
]
}
Indikátory jsou odeslány jako pole, takže recordIndex začíná na 0.
Další kroky
Další informace o tom, jak pracovat s analýzou hrozeb v Microsoft Sentinelu, najdete v následujících článcích:
- Vysvětlení analýzy hrozeb
- Práce s indikátory hrozeb
- Použití odpovídající analýzy k detekci hrozeb
- Využití informačního kanálu inteligentních funkcí od Microsoftu a povolení datového konektoru MDTI