Referera till API:et för äldre uppladdningsindikatorer

API:et för Microsoft Sentinel uppladdningsindikatorer tillät plattformar för hotinformation eller anpassade program att importera indikatorer för kompromettering i STIX-format till en Microsoft Sentinel arbetsyta. Det här dokumentet fungerar som en referens till det äldre API:et.

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

1. Begärande-URI
2. Meddelandehuvud för HTTP-begäran
3. Brödtext för HTTP-begärandemeddelande
4. Du kan också bearbeta HTTP-svarsmeddelanderubriken
5. Du kan också bearbeta HTTP-svarsmeddelandetexten

Registrera klientprogrammet med Microsoft Entra ID

För att 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-dataanslutningsappen för uppladdningsindikatorer.

Behörigheter

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

Skapa begäran

Det här avsnittet beskriver de tre första av de fem komponenter som diskuterades tidigare. Du måste först hämta åtkomsttoken från Microsoft Entra ID, som du använder för att sammanställa meddelandehuvudet 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 accepteras 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 programmet 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 App:
• 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 tokens målgrupp. 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

Det fanns två versioner av det äldre API:et. Beroende på slutpunkten krävdes ett annat matrisnamn i begärandetexten. Detta representerades också av två versioner av logikappens anslutningsåtgärd.

1. Anslutningsappens åtgärdsnamn: Hotinformation – Uppladdningsindikatorer för kompromiss (inaktuell)
   • Slutpunkt: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
   • Matris med namn på indikatorer: value

   { "sourcesystem":"TIsource-example", "value":[] }

• Namn på anslutningsappsåtgärd: Hotinformation – Ladda upp indikatorer för kompromettering (V2) (förhandsversion)
  • Slutpunkt: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
  • Matris med namn på indikatorer: indicators

    {
       "sourcesystem":"TIsource-example",
       "indicators":[]
    }
    

Begärande-URI

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

Begärandehuvud

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

Frågebrödtext

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

Skapa matrisen med indikatorer med hjälp av STIX 2.1-indikatorformatspecifikationen, som har komprimerats här för din bekvämlighet 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.

Bearbeta svarsmeddelandet

Svarshuvudet innehåller en HTTP-statuskod. Referera till den här tabellen för mer information om hur du tolkar API-anropsresultatet.

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

Felobjekt

Begränsningsgränser för API:et

Alla begränsningar 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.

Brödtext för exempelbegäran

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

Exempel på svarstext med valideringsfel

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

Om valideringen 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 id (obligatoriskt 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 på 0.

Nästa steg

Det här API:et är äldre. Migrera för att använda STIX-objekt-API:et för att ladda upp hotinformation. Mer information finns i STIX-objekt-API.