Importer trusselintelligens for å Microsoft Sentinel med API-en for opplasting (forhåndsvisning)

Importer trusselintelligens som skal brukes i Microsoft Sentinel med opplastings-API-en. Enten du bruker en plattform for trusselintelligens eller et egendefinert program, kan du bruke dette dokumentet som en ekstra referanse til instruksjonene i Koble til tipset med opplastings-API-en. Det er ikke nødvendig å installere datakoblingen for å koble til API-en. Trusselintelligensen du kan importere inkluderer indikatorer for kompromisser og andre STIX-domeneobjekter.

Structured Threat Information Expression (STIX) er et språk for å uttrykke cybertrussel og observerbar informasjon. Forbedret støtte for følgende domeneobjekter er inkludert i opplastings-API-en:

• Indikator
• angrepsmønster
• trusselskuespiller
• Identitet
• Forhold

Hvis du vil ha mer informasjon, kan du se Innføring i STIX.

Kall API-en

Et kall til opplastings-API-en 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

Hvis du vil godkjenne for Microsoft Sentinel, krever forespørselen om opplasting av API-en 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 Koble til trusselintelligens med opplasting av API-oppsett.

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 mottas, bestemmes av accessTokenAcceptedVersion egenskapen i appmanifestet for API-en som programmet kaller opp. Hvis accessTokenAcceptedVersion den er satt til 1, mottar programmet et v1.0-token.

Bruk Microsoft Authentication Library (MSAL) til å skaffe enten et v1.0- eller v2.0-tilgangstoken. Bruk tilgangstokenet til å opprette godkjenningshodet som inneholder bærertokenet.

En forespørsel om opplasting av API bruker for eksempel følgende elementer til å hente et tilgangstoken og opprette godkjenningshodet, som brukes i hver forespørsel:

• 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 eller client_certificate: {secrets of the 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

Forespørsels-URI

API-versjonskontroll: api-version=2024-02-01-preview
Endepunktet: https://api.ti.sentinel.azure.com/workspaces/{workspaceId}/threat-intelligence-stix-objects:upload?api-version={apiVersion}
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 STIX-objekter ved hjelp av STIX-formatspesifikasjonen. Noen av stix-egenskapsspesifikasjonene er utvidet her for enkelhets skyld med koblinger til de relevante STIX-dokumentdelene. Vær også oppmerksom på at enkelte egenskaper, selv om de er gyldige for STIX, ikke har tilsvarende objektskjemaegenskaper i Microsoft Sentinel.

Eksempelforespørselsmelding

Her er et eksempel på en PowerShell-funksjon som bruker et selvsignert sertifikat lastet opp til en Entra appregistrering for å generere tilgangstokenet og autorisasjonshodet:

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
}

Vanlige egenskaper

Alle objektene du importerer med API-en for opplasting, deler disse felles egenskapene.

Hvis du vil ha mer informasjon, kan du se VANLIGE EGENSKAPER FOR STIX.

Indikator

Hvis du vil ha mer informasjon, kan du se STIX-indikator.

Angrepsmønster

Følg STIX-spesifikasjonene for å opprette et STIX-objekt for angrepsmønster. Bruk dette eksemplet som en ekstra referanse.

Hvis du vil ha mer informasjon, kan du se STIX-angrepsmønster.

Identitet

Følg STIX-spesifikasjonene for å opprette et STIX-objekt for identitet. Bruk dette eksemplet som en ekstra referanse.

Hvis du vil ha mer informasjon, kan du se STIX-identitet.

Trusselskuespiller

Følg STIX-spesifikasjonene for å opprette et STIX-objekt for trusselaktør. Bruk dette eksemplet som en ekstra referanse.

Hvis du vil ha mer informasjon, kan du se STIX trusselskuespiller.

Forhold

Følg STIX-spesifikasjonene for å opprette et STIX-relasjonsobjekt. Bruk dette eksemplet som en ekstra referanse.

Hvis du vil ha mer informasjon, kan du se STIX-relasjon.

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 objekter 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 objekter per minutt er den maksimale gjennomstrømmingen før det mottas en begrensningsfeil.

Brødtekst for eksempelindikatorforespørsel

Følgende eksempel viser hvordan du representerer to indikatorer i STIX-spesifikasjonen. Test Indicator 2 uthever Traffic Light Protocol (TLP) satt til hvit med den tilordnede objektmerkingen, og tydeliggjør beskrivelsen og etikettene er på engelsk.

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

Eksempel på svartekst med valideringsfeil

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

Hvis validering mislykkes for ett eller flere objekter, 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."
            ]
        }
    ]
}

Objektene sendes som en matrise, slik at de recordIndex begynner på 0.

Andre eksempler

Eksempelindikator

I dette eksemplet er indikatoren merket med den grønne TLP-en ved hjelp marking-definition--089a6ecb-cc15-43cc-9494-767639779123 av fellesegenskapen object_marking_refs . Flere utvidelsesattributter for toxicity og rank er også inkludert. Selv om disse egenskapene ikke er i det Microsoft Sentinel skjemaet for indikatorer, utløser ikke inntak av et objekt med disse egenskapene en feil. Egenskapene refereres rett og slett ikke til eller indekseres i arbeidsområdet.

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

Eksempel på angrepsmønster

Dette angrepsmønsteret og andre STIX-objekter som ikke er indikatorer, kan bare vises i administrasjonsgrensesnittet med mindre du velger de nye STIX-tabellene. Hvis du vil ha mer informasjon om tabellene som kreves for å vise objekter som dette i KQL, kan du se Vis trusselintelligensen.

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

Eksempelrelasjon med trusselaktør og identitet

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

Neste trinn

Hvis du vil lære mer om hvordan du arbeider med trusselintelligens i Microsoft Sentinel, kan du se følgende artikler:

• Forstå trusselintelligens
• Arbeid med trusselindikatorer
• Bruk samsvarende analyser til å oppdage trusler
• Bruk intelligensfeeden fra Microsoft og aktiver MDTI-datakoblingen