Bedreigingsinformatie importeren in Microsoft Sentinel met de upload-API (preview)

Importeer bedreigingsinformatie voor gebruik in Microsoft Sentinel met de upload-API. Of u nu een platform voor bedreigingsinformatie of een aangepaste toepassing gebruikt, gebruik dit document als een aanvullende verwijzing naar de instructies in Uw TIP verbinden met de upload-API. Het installeren van de gegevensconnector is niet vereist om verbinding te maken met de API. De bedreigingsinformatie die u kunt importeren, bevat indicatoren van inbreuk en andere STIX-domeinobjecten.

Structured Threat Information Expression (STIX) is een taal voor het uiten van cyberdreigingen en waarneembare informatie. Verbeterde ondersteuning voor de volgende domeinobjecten is opgenomen in de upload-API:

• Indicator
• aanvalspatroon
• bedreigingsacteur
• identiteit
• Relatie

Zie Inleiding tot STIX voor meer informatie.

De API aanroepen

Een aanroep van de upload-API bestaat uit vijf onderdelen:

1. De aanvraag-URI
2. Berichtkop van HTTP-aanvraag
3. Hoofdtekst van HTTP-aanvraagbericht
4. Optioneel de header van het HTTP-antwoordbericht verwerken
5. 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 upload-API een geldig Microsoft Entra toegangstoken vereist. Zie Een toepassing registreren met de Microsoft identity platform voor meer informatie over toepassingsregistratie of zie de basisstappen als onderdeel van de installatie van Verbinding maken met bedreigingsinformatie met upload-API.

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 ontvangen versie van het token (v1.0 of v2.0) wordt bepaald door de accessTokenAcceptedVersion eigenschap in het app-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. Gebruik het toegangstoken om de autorisatieheader te maken die het bearer-token bevat.

Een aanvraag voor de upload-API gebruikt bijvoorbeeld de volgende elementen om een toegangstoken op te halen en de autorisatieheader te maken, die in elke aanvraag wordt gebruikt:

• 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 of client_certificate: {geheimen van de 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.net
• https://management.azure.com/
• https://management.azure.com

Het aanvraagbericht samenstellen

Aanvraag-URI

API-versiebeheer: api-version=2024-02-01-preview
Eindpunt: https://api.ti.sentinel.azure.com/workspaces/{workspaceId}/threat-intelligence-stix-objects:upload?api-version={apiVersion}
Methode: POST

Aanvraagheader

Authorization: Bevat het OAuth2 bearer-token
Content-Type: application/json

Aanvraagtekst

Het JSON-object voor de hoofdtekst bevat de volgende velden:

Maak de matrix met STIX-objecten met behulp van de stix-indelingsspecificatie. Enkele van de STIX-eigenschappenspecificaties worden hier voor uw gemak uitgebreid met koppelingen naar de relevante STIX-documentsecties. Houd er ook rekening mee dat sommige eigenschappen, hoewel geldig voor STIX, geen overeenkomende objectschema-eigenschappen hebben in Microsoft Sentinel.

Voorbeeld van aanvraagbericht

Hier volgt een voorbeeld van een PowerShell-functie die gebruikmaakt van een zelfondertekend certificaat dat is geüpload naar een Entra app-registratie om het toegangstoken en de autorisatieheader te genereren:

function Test-UploadApi {
<#
.SYNOPSIS
    requires Powershell module MSAL.PS version 4.37 or higher
    https://www.powershellgallery.com/packages/MSAL.PS/
.EXAMPLE
    Test-Api -API UploadApi -WorkspaceName "workspacename" -ResourceGroupName "rgname" -AppId "00001111-aaaa-2222-bbbb-3333cccc4444" -TenantName "contoso.onmicrosoft.com" -FilePath "C:\Users\user\Documents\stixobjects.json"
#>
[CmdletBinding()]
param (
    [Parameter(Mandatory = $true)]
    [string]$TenantName,
    [Parameter(Mandatory = $true)]
    [string]$CertThumbprint,
    [Parameter(Mandatory = $true)]
    [string]$AppId,
    [Parameter(Mandatory = $true)]
    [string]$WorkspaceId,
    [Parameter(Mandatory = $true)]
    [string]$FilePath
)
$Scope = "https://management.azure.com/.default"
# Connection details for getting initial token with self-signed certificate from local store
$connectionDetails = @{
    'TenantId'          = $TenantName
    'ClientId'          = $AppId
    'ClientCertificate' = Get-Item -Path "Cert:\CurrentUser\My\$CertThumbprint"
    scope               = $Scope
}
# Request the token
#  Using Powershell module MSAL.PS https://www.powershellgallery.com/packages/MSAL.PS/
#  Get-MsalToken is automatically using OAuth 2.0 token endpoint https://login.microsoftonline.com/$TenantName/oauth2/v2.0/token
#  and sets auth flow to grant_type = 'client_credentials'
$token = Get-MsalToken @connectionDetails

# Create header
#  Again relying on MSAL.PS which has method CreateAuthorizationHeader() getting us the bearer token
$Header = @{
    'Authorization' = $token.CreateAuthorizationHeader()
}
$Uri = "https://api.ti.sentinel.azure.com/workspaces/$workspaceId/threat-intelligence-stix-objects:upload?api-version=$apiVersion"
$stixobjects = get-content -path $FilePath
if(-not $stixobjects) { Write-Host "No file found at $FilePath"; break }
$results = Invoke-RestMethod -Uri $Uri -Headers $Header -Body $stixobjects -Method POST -ContentType "application/json"

$results | ConvertTo-Json -Depth 4
}

Algemene eigenschappen

Alle objecten die u importeert met de upload-API delen deze algemene eigenschappen.

Zie algemene eigenschappen van STIX voor meer informatie.

Indicator

Zie STIX-indicator voor meer informatie.

Aanvalspatroon

Volg de STIX-specificaties voor het maken van een STIX-object met een aanvalspatroon. Gebruik dit voorbeeld als extra referentie.

Zie STIX-aanvalspatroon voor meer informatie.

Identiteit

Volg de STIX-specificaties voor het maken van een STIX-object voor identiteit. Gebruik dit voorbeeld als extra referentie.

Zie STIX-identiteit voor meer informatie.

Bedreigingsacteur

Volg de STIX-specificaties voor het maken van een STIX-object voor bedreigingsacteur. Gebruik dit voorbeeld als extra referentie.

Zie STIX-bedreigingsacteur voor meer informatie.

Relatie

Volg de STIX-specificaties voor het maken van een relatie STIX-object. Gebruik dit voorbeeld als extra referentie.

Zie STIX-relatie voor meer informatie.

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.

De hoofdtekst van het antwoord is een matrix met foutberichten in JSON-indeling:

Foutobject

Beperkingslimieten voor de API

Alle limieten worden per gebruiker toegepast:

• 100 objecten 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 objecten per minuut is de maximale doorvoer voordat er een beperkingsfout wordt ontvangen.

Hoofdtekst van voorbeeldindicatoraanvraag

In het volgende voorbeeld ziet u hoe u twee indicatoren weergeeft in de STIX-specificatie. Test Indicator 2 markeert het Traffic Light Protocol (TLP) dat is ingesteld op wit met de markering van toegewezen objecten, en de beschrijving en labels zijn in het Engels.

{
    "sourcesystem": "test", 
    "stixobjects":[
        {
            "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 STIX-objecten zijn gevalideerd, wordt een HTTP 200-status geretourneerd met een lege antwoordtekst.

Als de validatie voor een of meer objecten mislukt, 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 (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 objecten worden verzonden als een matrix, dus de recordIndex begint bij 0.

Andere voorbeelden

Voorbeeldindicator

In dit voorbeeld wordt de indicator gemarkeerd met de groene TLP door in de object_marking_refs gemeenschappelijke eigenschap te gebruikenmarking-definition--089a6ecb-cc15-43cc-9494-767639779123. Meer extensiekenmerken van toxicity en rank zijn ook opgenomen. Hoewel deze eigenschappen niet in het Microsoft Sentinel schema voor indicatoren voor indicatoren, wordt er geen fout geactiveerd als u een object met deze eigenschappen opneemt. Er wordt niet naar de eigenschappen verwezen of geïndexeerd in de werkruimte.

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
    {
          "type": "indicator",
          "spec_version": "2.1",
          "id": "indicator--12345678-71a2-445c-ab86-927291df48f8",
          "created": "2010-02-26T18:29:07.778Z",
          "modified": "2011-02-26T18:29:07.778Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "extensions": {
            "extension-definition--d83fce45-ef58-4c6c-a3f4-1fbc32e98c6e": {
              "extension_type": "property-extension",
              "rank": 5,
              "toxicity": 8
            }
          },
          "name": "Indicator 2.1 Test",
          "description": "TS ID: 35766958; iType: bot_ip; State: active; Org: 52.3667; Source: Emerging Threats - Compromised",
          "indicator_types": [
            "threatstream-severity-low",
            "threatstream-confidence-80"
          ],
          "pattern": "[ipv4-addr:value = '94.102.52.185']",
          "pattern_type": "stix",
          "pattern_version": "2.1",
          "valid_from": "2015-02-26T18:29:07.778Z",
          "valid_until": "2016-02-26T18:29:07.778Z",
          "kill_chain_phases": [
            {
              "kill_chain_name": "lockheed-martin-cyber-kill-chain",
              "phase_name": "reconnaissance"
            }
          ]
        }
    ]
}

Voorbeeld van aanvalspatroon

Dit aanvalspatroon en andere stix-objecten zonder indicator kunnen alleen worden weergegeven in de beheerinterface, tenzij u zich aanmeldt voor de nieuwe STIX-tabellen. Zie Uw bedreigingsinformatie weergeven voor meer informatie over de tabellen die zijn vereist voor het weergeven van objecten zoals deze in KQL.

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
        {
          "type": "attack-pattern",
          "spec_version": "2.1",
          "id": "attack-pattern--fb6aa549-c94a-4e45-b4fd-7e32602dad85",
          "created": "2015-05-15T09:12:16.432Z",
          "modified": "2015-05-20T09:12:16.432Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": false,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "extensions": {
            "extension-definition--d83fce45-ef58-4c6c-a3f4-1fbc32e98c6e": {
              "extension_type": "property-extension",
              "rank": 5,
              "toxicity": 8
            }
          },
          "external_references": [
            {
              "source_name": "capec",
              "description": "spear phishing",
              "external_id": "CAPEC-163"
            }
          ],
          "name": "Attack Pattern 2.1",
          "description": "menuPass appears to favor spear phishing to deliver payloads to the intended targets. While the attackers behind menuPass have used other RATs in their campaign, it appears that they use PIVY as their primary persistence mechanism.",
          "kill_chain_phases": [
            {
              "kill_chain_name": "mandiant-attack-lifecycle-model",
              "phase_name": "initial-compromise"
            }
          ],
          "aliases": [
            "alias_1",
            "alias_2"
          ]
        }
    ]
}

Voorbeeldrelatie met bedreigingsacteur en identiteit

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
    {
          "type": "identity",
          "spec_version": "2.1",
          "id": "identity--733c5838-34d9-4fbf-949c-62aba761184c",
          "created": "2016-08-23T18:05:49.307Z",
          "modified": "2016-08-23T18:05:49.307Z",
          "name": "Identity 2.1",
          "description": "Disco Team is the name of an organized threat actor crime-syndicate.",
          "identity_class": "organization",
          "contact_information": "disco-team@stealthemail.com",
          "roles": [
            "administrators"
          ],
          "sectors": [
            "education"
          ],
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "type": "threat-actor",
          "spec_version": "2.1",
          "id": "threat-actor--dfaa8d77-07e2-4e28-b2c8-92e9f7b04428",
          "created": "2014-11-19T23:39:03.893Z",
          "modified": "2014-11-19T23:39:03.893Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "name": "Threat Actor 2.1",
          "description": "This organized threat actor group operates to create profit from all types of crime.",
          "threat_actor_types": [
            "crime-syndicate"
          ],
          "aliases": [
            "Equipo del Discoteca"
          ],
          "first_seen": "2014-01-19T23:39:03.893Z",
          "last_seen": "2014-11-19T23:39:03.893Z",
          "roles": [
            "agent"
          ],
          "goals": [
            "Steal Credit Card Information"
          ],
          "sophistication": "expert",
          "resource_level": "organization",
          "primary_motivation": "personal-gain",
          "secondary_motivations": [
            "dominance"
          ],
          "personal_motivations": [
            "revenge"
          ]
        },
        {
          "type": "relationship",
          "spec_version": "2.1",
          "id": "relationship--a2e3efb5-351d-4d46-97a0-6897ee7c77a0",
          "created": "2020-02-29T18:01:28.577Z",
          "modified": "2020-02-29T18:01:28.577Z",
          "relationship_type": "attributed-to",
          "description": "Description Relationship 2.1",
          "source_ref": "threat-actor--dfaa8d77-07e2-4e28-b2c8-92e9f7b04428",
          "target_ref": "identity--733c5838-34d9-4fbf-949c-62aba761184c",
          "start_time": "2020-02-29T18:01:28.577Z",
          "stop_time": "2020-03-01T18:01:28.577Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ]
        }
    ]
}

Volgende stappen

Zie de volgende artikelen voor meer informatie over het werken met bedreigingsinformatie in Microsoft Sentinel:

• Inzicht in bedreigingsinformatie
• Werken met bedreigingsindicatoren
• Overeenkomende analyses gebruiken om bedreigingen te detecteren
• Gebruik de intelligence-feed van Microsoft en schakel de MDTI-gegevensconnector in