Reference til api'en til indikatorer for ældre upload

API'en til Microsoft Sentinel upload af indikatorer tillod trusselsintelligensplatforme eller brugerdefinerede programmer at importere indikatorer for kompromis i STIX-formatet til et Microsoft Sentinel arbejdsområde. Dette dokument fungerer som en reference til den ældre API.

Vigtigt!

Denne API er en prøveversion, men anbefales ikke længere. Brug den nye STIX-objekt-API som prøveversion til at uploade trusselsintelligens. Du kan få flere oplysninger under API til STIX-objekter. De supplerende vilkår for Azure prøveversion indeholder yderligere juridiske vilkår, der gælder for Azure funktioner, der er i beta, prøveversion eller på anden måde endnu ikke er offentligt tilgængelige.

Et API-kald til uploadindikatorer indeholder fem komponenter:

  1. Anmodningens URI
  2. HTTP-anmodningsmeddelelsesheader
  3. Brødtekst i HTTP-anmodningsmeddelelse
  4. Behandl eventuelt HTTP-svarmeddelelsesheaderen
  5. Behandl eventuelt HTTP-svarmeddelelsens brødtekst

Registrer dit klientprogram med Microsoft Entra ID

For at godkende til Microsoft Sentinel kræver anmodningen til API'en til uploadindikatorer et gyldigt Microsoft Entra adgangstoken. Du kan finde flere oplysninger om programregistrering under Registrer et program med Microsoft-identitetsplatform, eller se de grundlæggende trin som en del af konfigurationen af API-dataconnectoren til uploadindikatorer.

Tilladelser

Denne API kræver, at det kaldende Microsoft Entra program tildeles rollen Microsoft Sentinel bidragyder på arbejdsområdeniveau.

Opret anmodningen

Dette afsnit omhandler de første tre af de fem komponenter, der blev drøftet tidligere. Du skal først hente adgangstokenet fra Microsoft Entra ID, som du bruger til at samle din anmodningsmeddelelsesheader.

Hent et adgangstoken

Hent et Microsoft Entra adgangstoken med OAuth 2.0-godkendelse. V1.0 og V2.0 er gyldige tokens, der accepteres af API'en.

Den version af tokenet (v1.0 eller v2.0), som dit program modtager, bestemmes af accessTokenAcceptedVersion egenskaben i appmanifestet for den API, som dit program kalder. Hvis accessTokenAcceptedVersion er indstillet til 1, modtager dit program et v1.0-token.

Brug Microsoft Authentication Library MSAL til at hente enten et v1.0- eller v2.0-adgangstoken. Du kan også sende anmodninger til REST-API'en i følgende format:

  • INDLÆG https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
  • Overskrifter til brug af Microsoft Entra app:
  • grant_type: "client_credentials"
  • client_id: {Klient-id for Microsoft Entra App}
  • client_secret: {Hemmeligheden ved Microsoft Entra App}
  • Omfanget: "https://management.azure.com/.default"

Hvis accessTokenAcceptedVersion i appmanifestet er indstillet til 1, modtager dit program et v1.0-adgangstoken, selvom det kalder v2-tokenslutpunktet.

Ressource-/områdeværdien er målgruppen for tokenet. Denne API accepterer kun følgende målgrupper:

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

Saml anmodningsmeddelelsen

Der var to versioner af den ældre API. Afhængigt af slutpunktet kræves der et andet matrixnavn i anmodningens brødtekst. Dette blev også repræsenteret af to versioner af connectorhandlingen for logikappen.

Skærmbillede af handlingsnavne for logic app-connectors for API'en til uploadindikatorer Microsoft Sentinel.

  1. Navn på connectorhandling: Threat Intelligence – Upload indikatorer for kompromis (frarådes)
    • Slutpunkt: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
    • Matrix af indikatorers navn: value
    { "sourcesystem":"TIsource-example", "value":[] }
  • Navn på connectorhandling: Threat Intelligence – Upload indikatorer for kompromis (V2) (prøveversion)
    • Slutpunkt: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
    • Matrix af indikatorers navn: indicators 
      {
   "sourcesystem":"TIsource-example",
   "indicators":[]
}

Anmod om URI

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

Anmodningsheader

Authorization: Indeholder OAuth2-ihændehavertokenet
Content-Type: application/json

Brødtekst i anmodning

JSON-objektet for brødteksten indeholder følgende felter:

Feltnavn Datatype Beskrivelse
SourceSystem (påkrævet) Streng Identificer navnet på kildesystemet. Værdien Microsoft Sentinel er begrænset.
indikatorer (påkrævet) Array En matrix af indikatorer i STIX 2.0- eller 2.1-format

Opret matrixen af indikatorer ved hjælp af specifikationen STIX 2.1-indikatorformat, som er komprimeret her for at gøre det nemmere for dig med links til vigtige afsnit. Bemærk også, at nogle egenskaber ikke har tilsvarende indikatoregenskaber i Microsoft Sentinel, selvom de er gyldige for STIX 2.1.

Egenskabsnavn Type Beskrivelse
id (påkrævet) Streng Et id, der bruges til at identificere indikatoren. Se afsnit 2.9 for at få oplysninger om, hvordan du opretter en id. Formatet ligner noget indicator--<UUID>
spec_version (valgfrit) Streng STIX-indikatorversion. Denne værdi er påkrævet i STIX-specifikationen, men da denne API kun understøtter STIX 2.0 og 2.1, når dette felt ikke er angivet, vil API'en som standard være 2.1
type (påkrævet) Streng Værdien af denne egenskab skal være indicator.
created (påkrævet) Tidsstempel Se afsnit 3.2 for specifikationer for denne fælles egenskab.
modified (påkrævet) Tidsstempel Se afsnit 3.2 for specifikationer for denne fælles egenskab.
name (valgfrit) Streng Et navn, der bruges til at identificere indikatoren.

Producenter skal levere denne egenskab for at hjælpe produkter og analytikere med at forstå, hvad denne indikator rent faktisk gør.
description (valgfrit) Streng En beskrivelse, der indeholder flere oplysninger og kontekst om indikatoren, herunder eventuelt formålet med den og dens nøgleegenskaber.

Producenter skal levere denne egenskab for at hjælpe produkter og analytikere med at forstå, hvad denne indikator rent faktisk gør.
indicator_types (valgfrit) liste over strenge Et sæt kategoriser for denne indikator.

Værdierne for denne egenskab skal komme fra indikatortype-ov
pattern (påkrævet) Streng Registreringsmønsteret for denne indikator kan udtrykkes som et STIX-mønster eller et andet passende sprog, f.eks SNORT, YARA osv.
pattern_type (påkrævet) Streng Det mønstersprog, der bruges i denne indikator.

Værdien for denne egenskab skal komme fra mønstertyper.

Værdien af denne egenskab skal svare til den type mønsterdata, der er inkluderet i mønsteregenskaben.
pattern_version (valgfrit) Streng Den version af mønstersproget, der bruges til dataene i mønsteregenskaben, som skal matche den type mønsterdata, der er inkluderet i mønsteregenskaben.

For mønstre, der ikke har en formel specifikation, skal det build eller den kodeversion, som mønsteret er kendt for at arbejde med, bruges.

For STIX-mønstersproget bestemmer specifikationsversionen af objektet standardværdien.

For andre sprog skal standardværdien være den nyeste version af mønstersproget på tidspunktet for objektets oprettelse.
valid_from (påkrævet) Tidsstempel Det tidspunkt, hvorfra denne indikator anses for at være en gyldig indikator for de funktionsmåder, den er relateret til eller repræsenterer.
valid_until (valgfrit) Tidsstempel Det tidspunkt, hvor denne indikator ikke længere skal betragtes som en gyldig indikator for de funktionsmåder, den er relateret til eller repræsenterer.

Hvis egenskaben valid_until udelades, er der ingen begrænsning på det seneste tidspunkt, som indikatoren er gyldig for.

Dette tidsstempel skal være større end det valid_from tidsstempel.
kill_chain_phases (valgfrit) liste over streng Den eller de kill chain-faser, som denne indikator svarer til.

Værdien for denne egenskab skal komme fra Kill Chain Phase.
created_by_ref (valgfrit) Streng Egenskaben created_by_ref angiver id-egenskaben for den enhed, der oprettede dette objekt.

Hvis denne attribut udelades, er kilden til disse oplysninger ikke defineret. For objektoprettere, der ønsker at forblive anonyme, skal denne værdi ikke være defineret.
revoked (valgfrit) Boolesk Tilbagekaldte objekter anses ikke længere for at være gyldige af objektopretteren. Tilbagekaldelse af et objekt er permanent. fremtidige versioner af objektet med dette idmå ikke oprettes.

Standardværdien for denne egenskab er false.
labels (valgfrit) liste over strenge Egenskaben labels angiver et sæt ord, der bruges til at beskrive dette objekt. Udtrykkene er brugerdefinerede eller tillidsgruppedefinerede. Disse mærkater vises som mærker i Microsoft Sentinel.
confidence (valgfrit) Heltal Egenskaben confidence identificerer den tillid, som forfatteren har til korrektheden af deres data. Konfidensværdien skal være et tal i intervallet 0-100.

Tillæg A indeholder en tabel over normative tilknytninger til andre tillidsskalaer, der skal bruges, når konfidensværdien præsenteres i en af disse skalaer.

Hvis tillidsegenskaben ikke findes, er indholdets tillid ikke angivet.
lang (valgfrit) Streng Egenskaben lang identificerer sproget for tekstindholdet i dette objekt. Når den er til stede, skal den være en sprogkode, der er i overensstemmelse med RFC5646. Hvis egenskaben ikke findes, er en sproget i indholdet (engelsk).

Denne egenskab skal være til stede, hvis objekttypen indeholder tekstegenskaber, der kan oversættes (f.eks. navn og beskrivelse).

Sproget for de enkelte felter i dette objekt kan tilsidesætte egenskaben lang i granulære markeringer (se afsnit 7.2.3).
object_marking_refs (valgfrit, herunder TLP) liste over strenge Egenskaben object_marking_refs angiver en liste over id-egenskaber for markeringsdefinitionsobjekter, der gælder for dette objekt. Brug f.eks. definitions-id'et for Traffic Light Protocol (TLP) til at angive indikatorkildens følsomhed. Du kan finde flere oplysninger om, hvilke mærkningsdefinitions-id'er der skal bruges til TLP-indhold, i punkt 7.2.1.4

I nogle tilfælde kan markering af definitioner i sig selv være markeret med vejledning til deling eller håndtering, selvom det er ualmindeligt. I dette tilfælde må denne egenskab ikke indeholde referencer til det samme markeringsdefinitionsobjekt (dvs. den kan ikke indeholde cirkulære referencer).

Se punkt 7.2.2 for yderligere definition af datamarkeringer.
external_references (valgfrit) liste over objekt Egenskaben external_references angiver en liste over eksterne referencer, der henviser til oplysninger, der ikke er STIX-oplysninger. Denne egenskab bruges til at levere en eller flere URL-adresser, beskrivelser eller id'er til poster i andre systemer.
granular_markings (valgfrit) liste over kornet markering Egenskaben granular_markings hjælper med at definere dele af indikatoren forskelligt. Indikatorsproget er f.eks. engelsk, en men beskrivelsen er tysk, de.

I nogle tilfælde kan markering af definitioner i sig selv være markeret med vejledning til deling eller håndtering, selvom det er ualmindeligt. I dette tilfælde må denne egenskab ikke indeholde referencer til det samme markeringsdefinitionsobjekt (dvs. den må ikke indeholde cirkulære referencer).

Se afsnit 7.2.3 for yderligere definition af datamarkeringer.

Behandl svarmeddelelsen

Svarheaderen indeholder en HTTP-statuskode. Se denne tabel for at få flere oplysninger om, hvordan du fortolker API-opkaldsresultatet.

Statuskode Beskrivelse
200 Succes. API'en returnerer 200, når en eller flere indikatorer valideres og publiceres.
400 Ugyldigt format. Noget i anmodningen er ikke formateret korrekt.
401 Uautoriseret.
404 Filen blev ikke fundet. Normalt forekommer denne fejl, når arbejdsområde-id'et ikke blev fundet.
429 Antallet af anmodninger i et minut er overskredet.
500 Serverfejl. Normalt en fejl i API'en eller Microsoft Sentinel-tjenesterne.

Brødteksten i svaret er en matrix af fejlmeddelelser i JSON-format:

Feltnavn Datatype Beskrivelse
Fejl Matrix af fejlobjekter Liste over valideringsfejl

Error-objekt

Feltnavn Datatype Beskrivelse
recordIndex Int Indeks for indikatorerne i anmodningen
errorMessages Matrix af strenge Fejlmeddelelser

Begrænsningsgrænser for API'en

Alle grænser anvendes pr. bruger:

  • 100 indikatorer pr. anmodning.
  • 100 anmodninger pr. minut.

Hvis der er flere anmodninger end grænsen, returneres en 429 HTTP-statuskode i svarheaderen med følgende brødtekst:

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

Ca. 10.000 indikatorer pr. minut er det maksimale gennemløb, før der modtages en begrænsningsfejl.

Brødtekst i eksempelanmodning

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

Brødtekst i eksempelsvar med valideringsfejl

Hvis alle indikatorer valideres korrekt, returneres en HTTP 200-status med en tom svartekst.

Hvis valideringen mislykkes for en eller flere indikatorer, returneres svarteksten med flere oplysninger. Hvis du f.eks. sender en matrix med fire indikatorer, og de første tre er gode, men den fjerde ikke har et id (et obligatorisk felt), genereres der 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."
            ]
        }
    ]
}

Indikatorerne sendes som en matrix, så recordIndex begynder ved 0.

Næste trin

Denne API er ældre. Overfør for at bruge STIX-objekt-API'en til at overføre trusselsintelligens. Du kan få flere oplysninger under API til STIX-objekter.

  • Last updated on