Verwijzen naar de API voor uploadindicatoren (preview) om bedreigingsinformatie te importeren in Microsoft Sentinel
Met de API voor uploadindicatoren van Microsoft Sentinel kunnen bedreigingsinformatieplatforms of aangepaste toepassingen indicatoren van inbreuk in de STIX-indeling importeren in een Microsoft Sentinel-werkruimte. Of u nu de API gebruikt met de API-gegevensconnector van Microsoft Sentinel uploadindicatoren of als onderdeel van een aangepaste oplossing, dit document fungeert als referentie.
Belangrijk
Deze API is momenteel in PREVIEW. De Aanvullende voorwaarden voor Azure-previews omvatten aanvullende juridische voorwaarden die van toepassing zijn op Azure-functies die in bèta of preview zijn of die anders nog niet algemeen beschikbaar zijn.
Een API-aanroep voor uploadindicatoren heeft vijf onderdelen:
- De aanvraag-URI
- Berichtheader http-aanvraag
- Hoofdtekst van HTTP-aanvraagbericht
- De header van het HTTP-antwoordbericht optioneel verwerken
- Eventueel de hoofdtekst van het HTTP-antwoordbericht verwerken
Uw clienttoepassing registreren bij Microsoft Entra-id
Voor verificatie bij Microsoft Sentinel is voor de aanvraag voor de API voor uploadindicatoren een geldig Microsoft Entra-toegangstoken vereist. Zie Een toepassing registreren bij het Microsoft Identity Platform of de basisstappen bekijken als onderdeel van de installatie van de API-gegevensconnector voor uploadindicatoren voor meer informatie over toepassingsregistratie.
Machtigingen
Voor deze API moet de aanroepende Microsoft Entra-toepassing de rol Microsoft Sentinel-inzender op werkruimteniveau worden verleend.
De aanvraag maken
In deze sectie worden de eerste drie van de vijf eerder besproken onderdelen behandeld. U moet eerst het toegangstoken verkrijgen van Microsoft Entra-id, die u gebruikt om de berichtkop van uw aanvraag samen te stellen.
Een toegangstoken verkrijgen
Een Microsoft Entra-toegangstoken verkrijgen met OAuth 2.0-verificatie. V1.0 en V2.0 zijn geldige tokens die door de API worden geaccepteerd.
De versie van het token (v1.0 of v2.0) die uw toepassing ontvangt, wordt bepaald door de accessTokenAcceptedVersion eigenschap in het app-manifest van de API die uw toepassing aanroept. Als accessTokenAcceptedVersion dit is ingesteld op 1, ontvangt uw toepassing een v1.0-token.
Gebruik MICROSOFT Authentication Library MSAL om een v1.0- of v2.0-toegangstoken te verkrijgen. Of verzend aanvragen naar de REST API in de volgende indeling:
- VERZENDEN
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - Headers voor het gebruik van Microsoft Entra App:
- grant_type: "client_credentials"
- client_id: {Client-id van Microsoft Entra App}
- client_secret: {geheim van Microsoft Entra App}
- draagwijdte:
"https://management.azure.com/.default"
Als accessTokenAcceptedVersion in het app-manifest is ingesteld op 1, ontvangt uw toepassing een v1.0-toegangstoken, ook al wordt het v2-tokeneindpunt aangeroepen.
De waarde van de resource/het bereik is de doelgroep van het token. Deze API accepteert alleen de volgende doelgroepen:
https://management.core.windows.net/https://management.core.windows.nethttps://management.azure.com/https://management.azure.com
Het aanvraagbericht samenstellen
Er zijn twee versies van de API voor uploadindicatoren. Afhankelijk van het eindpunt is een andere matrixnaam vereist in de hoofdtekst van de aanvraag. Dit wordt ook vertegenwoordigd door twee versies van de actie voor de connector van de logische app.
Naam van connectoractie: Bedreigingsinformatie - Indicatoren voor inbreuk uploaden (afgeschaft)
- Eindpunt:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - Matrix van indicatorennaam:
value{ "sourcesystem":"TIsource-example", "value":[] }
- Eindpunt:
Naam van connectoractie: Bedreigingsinformatie - Indicatoren voor inbreuk uploaden (V2) (preview)
- Eindpunt:
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - Matrix van indicatorennaam:
indicators{ "sourcesystem":"TIsource-example", "indicators":[] }
- Eindpunt:
Aanvraag-URI
API-versiebeheer: api-version=2022-07-01
Eindpunt: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
Methode: POST
Aanvraagheader
Authorization: Bevat het OAuth2 bearer-token
Content-Type: application/json
Aanvraagtekst
Het JSON-object voor de hoofdtekst bevat de volgende velden:
| Veldnaam | Gegevenstype | Beschrijving |
|---|---|---|
| SourceSystem (vereist) | tekenreeks | Identificeer de naam van uw bronsysteem. De waarde Microsoft Sentinel is beperkt. |
| indicatoren (vereist) | matrix | Een matrix van indicatoren in STIX 2.0- of 2.1-indeling |
Maak de matrix met indicatoren met behulp van de specificatie van de STIX 2.1-indicatorindeling, die hier voor uw gemak is verkort met koppelingen naar belangrijke secties. Let ook op sommige eigenschappen, terwijl deze geldig zijn voor STIX 2.1, geen bijbehorende indicatoreigenschappen hebben in Microsoft Sentinel.
| Eigenschapsnaam | Type | Description |
|---|---|---|
id (vereist) |
tekenreeks | Een id die wordt gebruikt om de indicator te identificeren. Zie sectie 2.9 voor specificaties over het maken van een id. De indeling ziet er ongeveer als volgt uit indicator--<UUID> |
spec_version (optioneel) |
tekenreeks | STIX-indicatorversie. Deze waarde is vereist in de STIX-specificatie, maar omdat deze API alleen STIX 2.0 en 2.1 ondersteunt wanneer dit veld niet is ingesteld, wordt de API standaard ingesteld op 2.1 |
type (vereist) |
tekenreeks | De waarde van deze eigenschap moet zijn indicator. |
created (vereist) |
timestamp | Zie sectie 3.2 voor specificaties van deze gemeenschappelijke eigenschap. |
modified (vereist) |
timestamp | Zie sectie 3.2 voor specificaties van deze gemeenschappelijke eigenschap. |
name (optioneel) |
tekenreeks | Een naam die wordt gebruikt om de indicator te identificeren. Producenten moeten deze eigenschap verstrekken om producten en analisten te helpen begrijpen wat deze indicator daadwerkelijk doet. |
description (optioneel) |
tekenreeks | Een beschrijving die meer details en context biedt over de indicator, mogelijk inclusief het doel en de belangrijkste kenmerken ervan. Producenten moeten deze eigenschap verstrekken om producten en analisten te helpen begrijpen wat deze indicator daadwerkelijk doet. |
indicator_types (optioneel) |
lijst met tekenreeksen | Een set categorisaties voor deze indicator. De waarden voor deze eigenschap moeten afkomstig zijn van het indicatortype-ov |
pattern (vereist) |
tekenreeks | Het detectiepatroon voor deze indicator kan worden uitgedrukt als STIX-patroon of een andere geschikte taal, zoals SNORT, YARA, enzovoort. |
pattern_type (vereist) |
tekenreeks | De patroontaal die in deze indicator wordt gebruikt. De waarde voor deze eigenschap moet afkomstig zijn van patroontypen. De waarde van deze eigenschap moet overeenkomen met het type patroongegevens dat is opgenomen in de patrooneigenschap. |
pattern_version (optioneel) |
tekenreeks | De versie van de patroontaal die wordt gebruikt voor de gegevens in de patrooneigenschap, die moet overeenkomen met het type patroongegevens dat is opgenomen in de patrooneigenschap. Voor patronen die geen formele specificatie hebben, moet de build- of codeversie waarmee het patroon werkt, worden gebruikt. Voor de STIX-patroontaal bepaalt de specificatieversie van het object de standaardwaarde. Voor andere talen moet de standaardwaarde de meest recente versie van de patroontaal zijn op het moment dat dit object is gemaakt. |
valid_from (vereist) |
timestamp | De tijd van waaruit deze indicator wordt beschouwd als een geldige indicator van het gedrag dat aan of vertegenwoordigt. |
valid_until (optioneel) |
timestamp | Het tijdstip waarop deze indicator niet langer als een geldige indicator moet worden beschouwd van het gedrag dat aan of vertegenwoordigt. Als de eigenschap valid_until wordt weggelaten, is er geen beperking voor de laatste tijd waarvoor de indicator geldig is. Deze tijdstempel moet groter zijn dan de valid_from tijdstempel. |
kill_chain_phases (optioneel) |
lijst met tekenreeksen | De kill chain-fase(s) waarop deze indicator overeenkomt. De waarde voor deze eigenschap moet afkomstig zijn van de Kill Chain-fase. |
created_by_ref (optioneel) |
tekenreeks | De eigenschap created_by_ref geeft de id-eigenschap op van de entiteit die dit object heeft gemaakt. Als dit kenmerk wordt weggelaten, is de bron van deze informatie niet gedefinieerd. Houd deze waarde niet gedefinieerd voor objectmakers die anoniem willen blijven. |
revoked (optioneel) |
boolean | Ingetrokken objecten worden niet langer als geldig beschouwd door de maker van het object. Het intrekken van een object is permanent; toekomstige versies van het object met dit id object mogen niet worden gemaakt.De standaardwaarde van deze eigenschap is onwaar. |
labels (optioneel) |
lijst met tekenreeksen | De labels eigenschap geeft een set termen op die worden gebruikt om dit object te beschrijven. De termen zijn door de gebruiker gedefinieerd of vertrouwensgroep gedefinieerd. Deze labels worden weergegeven als tags in Microsoft Sentinel. |
confidence (optioneel) |
geheel getal | De confidence eigenschap identificeert het vertrouwen dat de maker heeft in de juistheid van de gegevens. De betrouwbaarheidswaarde moet een getal in het bereik van 0-100 zijn.Bijlage A bevat een tabel met normatieve toewijzingen aan andere betrouwbaarheidsschalen die moeten worden gebruikt bij het presenteren van de betrouwbaarheidswaarde in een van deze schalen. Als de betrouwbaarheidseigenschap niet aanwezig is, is het vertrouwen van de inhoud niet opgegeven. |
lang (optioneel) |
tekenreeks | De lang eigenschap identificeert de taal van de tekstinhoud in dit object. Wanneer deze aanwezig is, moet het een taalcode zijn die voldoet aan RFC5646. Als de eigenschap niet aanwezig is, is en de taal van de inhoud (Engels).Deze eigenschap moet aanwezig zijn als het objecttype vertaalbare teksteigenschappen bevat (bijvoorbeeld naam, beschrijving). De taal van afzonderlijke velden in dit object kan de lang eigenschap in gedetailleerde markeringen overschrijven (zie sectie 7.2.3). |
object_marking_refs (optioneel, inclusief TLP) |
lijst met tekenreeksen | De object_marking_refs eigenschap geeft een lijst met id-eigenschappen op van markeringsdefinitieobjecten die van toepassing zijn op dit object. Gebruik bijvoorbeeld de definitie-id voor het markeren van het Traffic Light Protocol (TLP) om de gevoeligheid van de indicatorbron aan te wijzen. Zie sectie 7.2.1.4 voor meer informatie over welke markeringsdefinitie-id's moeten worden gebruikt voor TLP-inhoudIn sommige gevallen, hoewel ongebruikelijk, kunnen markeringsdefinities zelf worden gemarkeerd met richtlijnen voor delen of afhandelen. In dit geval mag deze eigenschap geen verwijzingen naar hetzelfde object Markeringsdefinitie bevatten (dat wil gezegd, het mag geen kringverwijzingen bevatten). Zie sectie 7.2.2 voor een verdere definitie van gegevensmarkeringen. |
external_references (optioneel) |
lijst met objecten | De external_references eigenschap geeft een lijst met externe verwijzingen op die verwijst naar niet-STIX-informatie. Deze eigenschap wordt gebruikt voor het opgeven van een of meer URL's, beschrijvingen of id's voor records in andere systemen. |
granular_markings (optioneel) |
lijst met gedetailleerde markeringen | De granular_markings eigenschap helpt bij het anders definiëren van onderdelen van de indicator. De indicatortaal is bijvoorbeeld Engels, en maar de beschrijving is Duits. deIn sommige gevallen, hoewel ongebruikelijk, kunnen markeringsdefinities zelf worden gemarkeerd met richtlijnen voor delen of afhandelen. In dit geval mag deze eigenschap geen verwijzingen bevatten naar hetzelfde object Markeringsdefinitie (dit kan dus geen kringverwijzingen bevatten). Zie sectie 7.2.3 voor verdere definitie van gegevensmarkeringen. |
Het antwoordbericht verwerken
De antwoordheader bevat een HTTP-statuscode. Raadpleeg deze tabel voor meer informatie over het interpreteren van het resultaat van de API-aanroep.
| Statuscode | Beschrijving |
|---|---|
| 200 | Geslaagd. De API retourneert 200 wanneer een of meer indicatoren zijn gevalideerd en gepubliceerd. |
| 400 | Ongeldige indeling. Iets in de aanvraag is niet juist opgemaakt. |
| 401 | Onbevoegd. |
| 404 | Het bestand is niet gevonden. Deze fout treedt meestal op wanneer de werkruimte-id niet wordt gevonden. |
| 429 | Het aantal aanvragen in een minuut is overschreden. |
| 500 | Serverfout. Meestal een fout in de API- of Microsoft Sentinel-services. |
De hoofdtekst van het antwoord is een matrix met foutberichten in JSON-indeling:
| Veldnaam | Gegevenstype | Beschrijving |
|---|---|---|
| fouten | Matrix met foutobjecten | Lijst met validatiefouten |
Foutobject
| Veldnaam | Gegevenstype | Beschrijving |
|---|---|---|
| recordIndex | int | Index van de indicatoren in de aanvraag |
| errorMessages | Matrix tekenreeksen | Foutberichten |
Beperkingslimieten voor de API
Alle limieten worden per gebruiker toegepast:
- 100 indicatoren per aanvraag.
- 100 aanvragen per minuut.
Als er meer aanvragen zijn dan de limiet, wordt er een 429 HTTP-statuscode in de antwoordheader geretourneerd met de volgende antwoordtekst:
{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}
Ongeveer 10.000 indicatoren per minuut is de maximale doorvoer voordat een beperkingsfout wordt ontvangen.
Tekst van voorbeeldaanvraag
{
"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"
}
]
}
]
}
Voorbeeldtekst van antwoord met validatiefout
Als alle indicatoren zijn gevalideerd, wordt een HTTP 200-status geretourneerd met een lege antwoordtekst.
Als de validatie mislukt voor een of meer indicatoren, wordt de hoofdtekst van het antwoord geretourneerd met meer informatie. Als u bijvoorbeeld een matrix met vier indicatoren verzendt en de eerste drie goed zijn, maar de vierde geen (vereist veld) heeft id , wordt een HTTP-statuscode 200-antwoord gegenereerd, samen met de volgende hoofdtekst:
{
"errors": [
{
"recordIndex":3,
"errorMessages": [
"Error for Property=id: Required property is missing. Actual value: NULL."
]
}
]
}
De indicatoren worden verzonden als een matrix, dus begint bij recordIndex 0.
Volgende stappen
Zie de volgende artikelen voor meer informatie over het werken met bedreigingsinformatie in Microsoft Sentinel:
- Informatie over bedreigingsinformatie
- Werken met bedreigingsindicatoren
- Overeenkomende analyses gebruiken om bedreigingen te detecteren
- De intelligence-feed van Microsoft gebruiken en MDTI-gegevensconnector inschakelen