Referer til API-en for eldre opplastingsindikatorer

API-en for Microsoft Sentinel opplastingsindikatorer tillot trusselintelligensplattformer eller egendefinerte programmer å importere indikatorer for kompromiss i STIX-formatet til et Microsoft Sentinel arbeidsområde. Dette dokumentet fungerer som en referanse til den eldre API-en.

Et API-kall for opplastingsindikatorer har fem komponenter:

1. Forespørsels-URI
2. Meldingshode for HTTP-forespørsel
3. Brødtekst for HTTP-forespørselsmelding
4. Du kan også behandle HTTP-svarmeldingshodet
5. Behandle brødteksten for HTTP-svarmeldingen eventuelt

Registrer klientprogrammet med Microsoft Entra ID

For å godkjenne til Microsoft Sentinel, krever forespørselen til API-en for opplastingsindikatorer et gyldig Microsoft Entra tilgangstoken. Hvis du vil ha mer informasjon om programregistrering, kan du se Registrere et program med Microsofts identitetsplattform eller se de grunnleggende trinnene som en del av konfigurasjonen av API-datakoblingen for opplastingsindikatorer.

Tillatelser

Denne API-en krever at kallet Microsoft Entra program gis Microsoft Sentinel bidragsyterrolle på arbeidsområdenivå.

Opprett forespørselen

Denne delen dekker de tre første av de fem komponentene som ble diskutert tidligere. Du må først hente tilgangstokenet fra Microsoft Entra ID, som du bruker til å sette sammen meldingshodet for forespørselen.

Hent et tilgangstoken

Hent et Microsoft Entra tilgangstoken med OAuth 2.0-godkjenning. V1.0 og V2.0 er gyldige tokener som godtas av API-en.

Versjonen av tokenet (v1.0 eller v2.0) som programmet mottar, bestemmes av accessTokenAcceptedVersion egenskapen i appmanifestet for API-en som programmet kaller opp. Hvis accessTokenAcceptedVersion den er satt til 1, vil programmet motta et v1.0-token.

Bruk Microsoft Authentication Library MSAL til å skaffe enten et v1.0- eller v2.0-tilgangstoken. Eller send forespørsler til REST-API-en i følgende format:

• INNLEGG https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
• Overskrifter for bruk av Microsoft Entra app:
• grant_type: «client_credentials»
• client_id: {Client ID for Microsoft Entra App}
• client_secret: {secret of Microsoft Entra App}
• Omfanget: "https://management.azure.com/.default"

Hvis accessTokenAcceptedVersion appmanifestet er satt til 1, mottar programmet et v1.0-tilgangstoken selv om det kaller endepunktet for v2-tokenet.

Ressursen/omfangsverdien er målgruppen for tokenet. Denne API-en godtar bare følgende målgrupper:

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

Sette sammen forespørselsmeldingen

Det var to versjoner av den eldre API-en. Avhengig av endepunktet var det nødvendig med et annet matrisenavn i forespørselsteksten. Dette ble også representert av to versjoner av logisk app-koblingshandling.

1. Koblingshandlingsnavn: Trusselintelligens - Last opp indikatorer for kompromiss (avskrevet)
   • Endepunktet: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
   • Matrise med indikatornavn: value

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

• Handlingsnavn for kobling: Trusselintelligens – Last opp indikatorer for kompromiss (V2) (forhåndsversjon)
  • Endepunktet: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
  • Matrise med indikatornavn: indicators

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

Forespørsels-URI

API-versjonskontroll: api-version=2022-07-01
Endepunktet: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
Metoden: POST

Forespørselshode

Authorization: Inneholder OAuth2-bærertokenet
Content-Type: application/json

Forespørselstekst

JSON-objektet for brødteksten inneholder følgende felt:

Opprett matrisen med indikatorer ved hjelp av spesifikasjonen for STIX 2.1-indikatorformatet, som har blitt kondensert her for enkelhets skyld med koblinger til viktige inndelinger. Vær også oppmerksom på at enkelte egenskaper, selv om de er gyldige for STIX 2.1, ikke har tilsvarende indikatoregenskaper i Microsoft Sentinel.

Behandle svarmeldingen

Svarhodet inneholder en HTTP-statuskode. Referer til denne tabellen for mer informasjon om hvordan du tolker resultatet av API-kallet.

Svarteksten er en matrise med feilmeldinger i JSON-format:

Feilobjekt

Begrensningsgrenser for API-en

Alle begrensninger brukes per bruker:

• 100 indikatorer per forespørsel.
• 100 forespørsler per minutt.

Hvis det er flere forespørsler enn grensen, returneres en 429 http-statuskode i svarhodet med følgende svartekst:

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

Omtrent 10 000 indikatorer per minutt er den maksimale gjennomstrømmingen før en begrensningsfeil mottas.

Brødtekst for eksempelforespørsel

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

Eksempel på svartekst med valideringsfeil

Hvis alle indikatorer er validert, returneres en HTTP 200-status med en tom svartekst.

Hvis validering mislykkes for én eller flere indikatorer, returneres svarteksten med mer informasjon. Hvis du for eksempel sender en matrise med fire indikatorer, og de tre første er gode, men den fjerde ikke har et id (et obligatorisk felt), genereres et HTTP-statuskode 200-svar sammen med følgende brødtekst:

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

Indikatorene sendes som en matrise, så begynner recordIndex på 0.

Neste trinn:

Denne API-en er eldre. Overfør for å bruke API-en for STIX-objekter til å laste opp trusselintelligens. Hvis du vil ha mer informasjon, kan du se API for STIX-objekter.