Share via

Referera till API:et för uppladdningsindikatorer (förhandsversion) för att importera hotinformation till Microsoft Sentinel

  • Artikel

Med API:et för Microsoft Sentinel-uppladdningsindikatorer kan plattformar för hotinformation eller anpassade program importera indikatorer för kompromettering i STIX-format till en Microsoft Sentinel-arbetsyta. Oavsett om du använder API:et med Api-anslutningsappen för uppladdningsindikatorer för Microsoft Sentinel eller som en del av en anpassad lösning fungerar det här dokumentet som en referens.

Viktigt!

Det här API:et är för närvarande i förhandsversion. Tilläggsvillkoren för Azure Preview innehåller ytterligare juridiska villkor som gäller för Azure-funktioner som är i betaversion, förhandsversion eller på annat sätt ännu inte har släppts i allmän tillgänglighet.

Ett API-anrop för uppladdningsindikatorer har fem komponenter:

  1. Begärande-URI:n
  2. Meddelandehuvud för HTTP-begäran
  3. Meddelandetext för HTTP-begäran
  4. Du kan också bearbeta http-svarsmeddelanderubriken
  5. Du kan också bearbeta HTTP-svarsmeddelandetexten

Registrera ditt klientprogram med Microsoft Entra-ID

För att kunna autentisera till Microsoft Sentinel kräver begäran till API:et för uppladdningsindikatorer en giltig Microsoft Entra-åtkomsttoken. Mer information om programregistrering finns i Registrera ett program med Microsofts identitetsplattform eller se de grundläggande stegen som en del av konfigurationen av API-dataanslutningsappenför uppladdningsindikatorer.

Behörigheter

Det här API:et kräver att det anropande Microsoft Entra-programmet beviljas rollen Microsoft Sentinel-deltagare på arbetsytans nivå.

Skapa begäran

Det här avsnittet beskriver de tre första av de fem komponenter som beskrevs tidigare. Du måste först hämta åtkomsttoken från Microsoft Entra-ID:t, som du använder för att sammanställa meddelanderubriken för begäran.

Hämta en åtkomsttoken

Hämta en Microsoft Entra-åtkomsttoken med OAuth 2.0-autentisering. V1.0 och V2.0 är giltiga token som godkänts av API:et.

Den version av token (v1.0 eller v2.0) som ditt program tar emot bestäms av accessTokenAcceptedVersion egenskapen i appmanifestet för API:et som programmet anropar. Om accessTokenAcceptedVersion är inställt på 1 får ditt program en v1.0-token.

Använd Microsoft Authentication Library MSAL för att hämta antingen en v1.0- eller v2.0-åtkomsttoken. Eller skicka begäranden till REST-API:et i följande format:

  • INLÄGG https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
  • Rubriker för att använda Microsoft Entra-appen:
  • grant_type: "client_credentials"
  • client_id: {Klient-ID för Microsoft Entra App}
  • client_secret: {hemlighet för Microsoft Entra App}
  • Omfattning: "https://management.azure.com/.default"

Om accessTokenAcceptedVersion appmanifestet är inställt på 1 får programmet en v1.0-åtkomsttoken trots att den anropar v2-tokenslutpunkten.

Resurs-/omfångsvärdet är målgruppen för token. Det här API:et accepterar endast följande målgrupper:

  • https://management.core.windows.net/
  • https://management.core.windows.net
  • https://management.azure.com/
  • https://management.azure.com

Montera begärandemeddelandet

URI för förfrågan

API-versionshantering: api-version=2022-07-01
Slutpunkt: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators?api-version=2022-07-01
Metod: POST

Begärandehuvud

Authorization: Innehåller OAuth2-ägartoken
Content-Type: application/json

Begärandetext

JSON-objektet för brödtexten innehåller följande fält:

Fältnamn Datatyp Description
SourceSystem (krävs) sträng Identifiera källsystemets namn. Värdet Microsoft Sentinel är begränsat.
Värde (krävs) matris En matris med indikatorer i STIX 2.0- eller 2.1-format

Skapa matrisen med indikatorer med hjälp av STIX 2.1-indikatorformatspecifikationen, som har komprimerats här för att underlätta för dig med länkar till viktiga avsnitt. Observera även att vissa egenskaper, även om de är giltiga för STIX 2.1, inte har motsvarande indikatoregenskaper i Microsoft Sentinel.

Egenskapsnamn Type Description
id (krävs) sträng Ett ID som används för att identifiera indikatorn. Se avsnitt 2.9 för specifikationer om hur du skapar en id. Formatet ser ut ungefär som indicator--<UUID>
spec_version (valfritt) sträng STIX-indikatorversion. Det här värdet krävs i STIX-specifikationen, men eftersom det här API:et endast stöder STIX 2.0 och 2.1, när det här fältet inte har angetts, kommer API:et som standard att vara 2.1
type (krävs) sträng Värdet för den här egenskapen måste vara indicator.
created (krävs) timestamp Se avsnitt 3.2 för specifikationer för den här gemensamma egenskapen.
modified (krävs) timestamp Se avsnitt 3.2 för specifikationer för den här gemensamma egenskapen.
name (valfritt) sträng Ett namn som används för att identifiera indikatorn.

Producenter bör tillhandahålla denna egenskap för att hjälpa produkter och analytiker att förstå vad denna indikator faktiskt gör.
description (valfritt) sträng En beskrivning som ger mer information och sammanhang om indikatorn, eventuellt inklusive dess syfte och dess viktigaste egenskaper.

Producenter bör tillhandahålla denna egenskap för att hjälpa produkter och analytiker att förstå vad denna indikator faktiskt gör.
indicator_types (valfritt) lista över strängar En uppsättning kategoriseringar för den här indikatorn.

Värdena för den här egenskapen ska komma från indikatortyp-ov
pattern (krävs) sträng Identifieringsmönstret för den här indikatorn kan uttryckas som ett STIX-mönster eller ett annat lämpligt språk, till exempel SNORT, YARA osv.
pattern_type (krävs) sträng Det mönsterspråk som används i den här indikatorn.

Värdet för den här egenskapen ska komma från mönstertyper.

Värdet för den här egenskapen måste matcha typen av mönsterdata som ingår i mönsteregenskapen.
pattern_version (valfritt) sträng Den version av mönsterspråket som används för data i mönsteregenskapen, som måste matcha typen av mönsterdata som ingår i mönsteregenskapen.

För mönster som inte har någon formell specifikation bör den version eller kodversion som mönstret är känt för att fungera med användas.

För STIX-mönsterspråket avgör specifikationsversionen av objektet standardvärdet.

För andra språk bör standardvärdet vara den senaste versionen av mönsterspråket när objektet skapas.
valid_from (krävs) timestamp Den tid från vilken den här indikatorn anses vara en giltig indikator för de beteenden som den är relaterad till eller representerar.
valid_until (valfritt) timestamp Den tid då den här indikatorn inte längre ska betraktas som en giltig indikator för de beteenden som den är relaterad till eller representerar.

Om egenskapen valid_until utelämnas finns det ingen begränsning för den senaste tiden då indikatorn är giltig.

Tidsstämpeln måste vara större än tidsstämpeln för valid_from.
kill_chain_phases (valfritt) lista över sträng De avlivningskedjans faser som den här indikatorn motsvarar.

Värdet för den här egenskapen ska komma från kill chain-fasen.
created_by_ref (valfritt) sträng Egenskapen created_by_ref anger ID-egenskapen för den entitet som skapade objektet.

Om det här attributet utelämnas är källan till den här informationen odefinierad. För objektskapare som vill vara anonyma bör du behålla det här värdet odefinierat.
revoked (valfritt) boolean Återkallade objekt anses inte längre vara giltiga av objektskapare. Det är permanent att återkalla ett objekt. framtida versioner av objektet med detta idfår inte skapas.

Standardvärdet för den här egenskapen är falskt.
labels (valfritt) lista över strängar Egenskapen labels anger en uppsättning termer som används för att beskriva det här objektet. Termerna är användardefinierade eller betrodda grupper definierade. Dessa etiketter visas som taggar i Microsoft Sentinel.
confidence (valfritt) integer Egenskapen confidence identifierar det förtroende som skaparen har för att deras data ska vara korrekta. Konfidensvärdet måste vara ett tal i intervallet 0–100.

Bilaga A innehåller en tabell med normativa mappningar till andra konfidensskalor som måste användas när konfidensvärdet presenteras i någon av dessa skalor.

Om förtroendeegenskapen inte finns är innehållets förtroende ospecificerat.
lang (valfritt) sträng Egenskapen lang identifierar språket för textinnehållet i det här objektet. När det finns måste det vara en språkkod som överensstämmer med RFC5646. Om egenskapen inte finns är en språket i innehållet (engelska).

Den här egenskapen bör finnas om objekttypen innehåller översättningsbara textegenskaper (till exempel namn, beskrivning).

Språket för enskilda fält i det här objektet kan åsidosätta lang egenskapen i detaljerade markeringar (se avsnitt 7.2.3).
object_marking_refs (valfritt, inklusive TLP) lista över strängar Egenskapen object_marking_refs anger en lista över ID-egenskaper för märkningsdefinitionsobjekt som gäller för det här objektet. Använd t.ex. TLP-märkningsdefinitions-ID (Traffic Light Protocol) för att ange indikatorkällans känslighet. Mer information om vilka märkningsdefinitions-ID:er som ska användas för TLP-innehåll finns i avsnitt 7.2.1.4

I vissa fall, även om det är ovanligt, kan själva märkningsdefinitionerna markeras med vägledning för delning eller hantering. I det här fallet får den här egenskapen inte innehålla några referenser till samma märkningsdefinitionsobjekt (det vill: den får inte innehålla några cirkelreferenser).

Se avsnitt 7.2.2 för ytterligare definition av datamarkeringar.
external_references (valfritt) lista över objekt Egenskapen external_references anger en lista över externa referenser som refererar till icke-STIX-information. Den här egenskapen används för att tillhandahålla en eller flera URL:er, beskrivningar eller ID:er till poster i andra system.
granular_markings (valfritt) lista över detaljerad markering Egenskapen granular_markings hjälper till att definiera delar av indikatorn på olika sätt. Indikatorspråket är till exempel engelska, en men beskrivningen är tyska, de.

I vissa fall, även om det är ovanligt, kan själva märkningsdefinitionerna markeras med vägledning för delning eller hantering. I det här fallet får den här egenskapen inte innehålla några referenser till samma märkningsdefinitionsobjekt (dvs. den får inte innehålla några cirkelreferenser).

Se avsnitt 7.2.3 för ytterligare definition av datamarkeringar.

Bearbeta svarsmeddelandet

Svarshuvudet innehåller en HTTP-statuskod. Mer information om hur du tolkar API-anropsresultatet finns i den här tabellen.

Statuskod Description
200 Lyckades. API:et returnerar 200 när en eller flera indikatorer har verifierats och publicerats.
400 Felaktigt format. Något i begäran är inte korrekt formaterat.
401 Behörighet saknas.
404 Filen hittades inte. Det här felet uppstår vanligtvis när arbetsyte-ID:t inte hittas.
429 Antalet begäranden på en minut har överskridits.
500 Serverfel. Vanligtvis ett fel i API:et eller Microsoft Sentinel-tjänsterna.

Svarstexten är en matris med felmeddelanden i JSON-format:

Fältnamn Datatyp Description
fel Matris med felobjekt Lista över valideringsfel

Felobjekt

Fältnamn Datatyp Description
recordIndex heltal Index för indikatorerna i begäran
errorMessages Matris med strängar Felmeddelanden

Begränsningsgränser för API:et

Alla gränser tillämpas per användare:

  • 100 indikatorer per begäran.
  • 100 begäranden per minut.

Om det finns fler begäranden än gränsen returneras en 429 http-statuskod i svarshuvudet med följande svarstext:

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}

Cirka 10 000 indikatorer per minut är det maximala dataflödet innan ett begränsningsfel tas emot.

Exempelbegärantext

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

Exempel på svarstext med valideringsfel

Om alla indikatorer har verifierats returneras en HTTP 200-status med en tom svarstext.

Om verifieringen misslyckas för en eller flera indikatorer returneras svarstexten med mer information. Om du till exempel skickar en matris med fyra indikatorer och de tre första är bra men den fjärde inte har ett (obligatoriskt id fält) genereras ett HTTP-statuskod 200-svar tillsammans med följande brödtext:

{
    "errors": [
        {
            "recordIndex":3, 
            "errorMessages": [
                "Error for Property=id: Required property is missing. Actual value: NULL."
            ]
        }
    ]
}

Indikatorerna skickas som en matris, så börjar recordIndex vid 0.

Nästa steg

Mer information om hur du arbetar med hotinformation i Microsoft Sentinel finns i följande artiklar: