Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Met de API voor het uploaden van indicatoren Microsoft Sentinel konden platformen voor bedreigingsinformatie of aangepaste toepassingen indicatoren van inbreuk in de STIX-indeling importeren in een Microsoft Sentinel werkruimte. Dit document dient als verwijzing naar de verouderde API.
Belangrijk
Deze API is in PREVIEW, maar wordt niet meer aanbevolen. Gebruik de nieuwe STIX-objecten-API in preview om bedreigingsinformatie te uploaden. Zie STIX-objecten-API voor meer informatie. De aanvullende voorwaarden voor Azure preview bevatten aanvullende juridische voorwaarden die van toepassing zijn op Azure functies die in bètaversie, preview of anderszins nog niet algemeen beschikbaar zijn.
Een API-aanroep voor uploadindicatoren bestaat uit vijf onderdelen:
- De aanvraag-URI
- Berichtkop van HTTP-aanvraag
- Hoofdtekst van HTTP-aanvraagbericht
- Optioneel de header van het HTTP-antwoordbericht verwerken
- Optioneel 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 met de Microsoft identity platform of de basisstappen als onderdeel van de installatie van de API-gegevensconnector voor het uploaden van indicatoren voor meer informatie over toepassingsregistratie.
Machtigingen
Voor deze API moet aan de aanroepende Microsoft Entra toepassing de rol Microsoft Sentinel inzender op werkruimteniveau worden toegekend.
De aanvraag maken
In deze sectie worden de eerste drie van de vijf eerder besproken onderdelen behandeld. U moet eerst het toegangstoken ophalen van Microsoft Entra ID, dat u gebruikt om de berichtkop van de aanvraag samen te stellen.
Een toegangstoken verkrijgen
Verkrijg een Microsoft Entra-toegangstoken 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 eigenschap in het accessTokenAcceptedVersionapp-manifest van de API die door uw toepassing wordt aangeroepen. Als accessTokenAcceptedVersion 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. U kunt ook aanvragen verzenden 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}
- Scope:
"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 waren twee versies van de verouderde API. Afhankelijk van het eindpunt was een andere matrixnaam vereist in de hoofdtekst van de aanvraag. Dit werd ook vertegenwoordigd door twee versies van de actie voor de logische app-connector.
- Naam van connectoractie: Bedreigingsinformatie - Indicatoren van inbreuk uploaden (afgeschaft)
- Eindpunt:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - Matrix van indicatorennaam:
value
- Eindpunt:
- Naam van connectoractie: Bedreigingsinformatie - Indicatoren van 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 met indicatoren in STIX 2.0- of 2.1-indeling |
Maak de matrix met indicatoren met behulp van de specificatie stix 2.1-indicatorindeling, die hier voor uw gemak is samengevat met koppelingen naar belangrijke secties. Houd er ook rekening mee dat sommige eigenschappen, hoewel geldig voor STIX 2.1, geen overeenkomende indicatoreigenschappen hebben in Microsoft Sentinel.
| Eigenschapsnaam | Type | Beschrijving |
|---|---|---|
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, wordt de API standaard ingesteld op 2.1 |
type (vereist) |
tekenreeks | De waarde van deze eigenschap moet zijn indicator. |
created (vereist) |
Tijdstempel | Zie sectie 3.2 voor specificaties van deze gemeenschappelijke eigenschap. |
modified (vereist) |
Tijdstempel | 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 bieden om producten en analisten te helpen begrijpen wat deze indicator daadwerkelijk doet. |
description (optioneel) |
tekenreeks | Een beschrijving met meer details en context over de indicator, mogelijk met inbegrip van het doel en de belangrijkste kenmerken. Producenten moeten deze eigenschap bieden 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 de indicator-type-ov |
pattern (vereist) |
tekenreeks | Het detectiepatroon voor deze indicator kan worden uitgedrukt als een 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 worden gebruikt waarmee het patroon werkt. 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 wordt gemaakt. |
valid_from (vereist) |
Tijdstempel | Het tijdstip waarop deze indicator wordt beschouwd als een geldige indicator van het gedrag waarmee deze is gerelateerd of vertegenwoordigt. |
valid_until (optioneel) |
Tijdstempel | Het tijdstip waarop deze indicator niet langer moet worden beschouwd als een geldige indicator van het gedrag waarmee deze is gerelateerd 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 tekenreeks | De kill chain-fase(s) waarmee 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 eigenschap ID 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 ongedefinieerd voor objectmakers die anoniem willen blijven. |
revoked (optioneel) |
booleaans | 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 idobject mogen niet worden gemaakt.De standaardwaarde van deze eigenschap is false. |
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 de betrouwbaarheid 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 op met id-eigenschappen van markeringsdefinitieobjecten die van toepassing zijn op dit object. Gebruik bijvoorbeeld de TLP-markeringsdefinitie-id (Traffic Light Protocol) om de gevoeligheid van de indicatorbron aan te geven. 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 bevatten naar hetzelfde markeringsdefinitieobject (dat wil gezegd, de eigenschap mag geen kringverwijzingen bevatten). Zie sectie 7.2.2 voor 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 om een of meer URL's, beschrijvingen of id's op te geven voor records in andere systemen. |
granular_markings (optioneel) |
lijst met gedetailleerde markeringen | De granular_markings eigenschap helpt delen van de indicator op een andere manier te definiëren. De indicatortaal is bijvoorbeeld Engels, en maar de beschrijving is Duits, de.In 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 markeringsdefinitieobject (dit wil bijvoorbeeld dat deze geen kringverwijzingen mag 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 | Succes. De API retourneert 200 wanneer een of meer indicatoren zijn gevalideerd en gepubliceerd. |
| 400 | Ongeldige indeling. Iets in de aanvraag is niet correct opgemaakt. |
| 401 | Onbevoegde. |
| 404 | Bestand 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 van 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 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 er een beperkingsfout wordt ontvangen.
Voorbeeld van aanvraagbody
{
"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"
}
]
}
]
}
Voorbeeld van antwoordtekst met validatiefout
Als alle indicatoren zijn gevalideerd, wordt een HTTP 200-status geretourneerd met een lege antwoordtekst.
Als de validatie voor een of meer indicatoren mislukt, wordt de antwoordtekst geretourneerd met meer informatie. Als u bijvoorbeeld een matrix met vier indicatoren verzendt en de eerste drie goed zijn, maar de vierde geen (een 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 de recordIndex begint bij 0.
Volgende stap
Deze API is verouderd. Migreer om de API voor STIX-objecten te gebruiken om bedreigingsinformatie te uploaden. Zie STIX-objecten-API voor meer informatie.