Uhkien tietojen tuominen Microsoft Sentinel latauksen ohjelmointirajapinnan avulla (esikatselu)

Tuo Microsoft Sentinel latauksen ohjelmointirajapinnan kanssa käytettävät uhkatiedot. Käytätpä uhkatietoalustaa tai mukautettua sovellusta, käytä tätä asiakirjaa lisäviittauksena ohjeisiin kohdassa Vihjeen yhdistäminen latauksen ohjelmointirajapintaan. Tietoyhdistimen asentamista ei vaadita yhteyden muodostamiseksi ohjelmointirajapintaan. Tuotava uhkatieto sisältää kompromissi-ilmaisimet ja muut STIX-toimialueobjektit.

Structured Threat Information Expression (STIX) on kieli, jolla ilmaistaan kyberuhkia ja havaittavaa tietoa. Seuraavien toimialueobjektien parannettu tuki sisältyy latauksen ohjelmointirajapintaan:

• Ilmaisin
• hyökkäyskuvio
• uhkatoimija
• Identiteetti
• Suhde

Lisätietoja on artikkelissa Johdanto STIX:ään.

Ohjelmointirajapinnan kutsuminen

Latauksen ohjelmointirajapinnan kutsussa on viisi osaa:

1. Pyynnön URI
2. HTTP-pyyntöviestin otsikko
3. HTTP-pyyntöviestin teksti
4. Vaihtoehtoisesti voit käsitellä HTTP-vastausviestin otsikon
5. Vaihtoehtoisesti voit käsitellä HTTP-vastausviestin tekstin

Asiakassovelluksen rekisteröiminen Microsoft Entra ID

Microsoft Sentinel todentaminen edellyttää kelvollista Microsoft Entra käyttöoikeustietuetta. Lisätietoja sovelluksen rekisteröinnistä on kohdassa Sovelluksen rekisteröiminen Microsoftin käyttäjätietoympäristö tai perusvaiheet osana Yhdistä uhkatietoja latauksen ohjelmointirajapinnan määrityksen avulla.

Tämä ohjelmointirajapinta edellyttää, että kutsuvan Microsoft Entra sovellukselle myönnetään Microsoft Sentinel osallistujan rooli työtilatasolla.

Luo pyyntö

Tässä osiossa käsitellään kolmea ensimmäistä niistä viidestä osasta, joita käsiteltiin aiemmin. Sinun on ensin hankittava käyttöoikeustietue Microsoft Entra ID, jota käytät pyyntöviestin otsikon kokoamiseen.

Käyttöoikeustietueen hankkiminen

Hanki Microsoft Entra käyttöoikeustietue OAuth 2.0 -todennuksella. V1.0 ja V2.0 ovat ohjelmointirajapinnan hyväksymiä kelvollisia tunnuksia.

Vastaanotetun tunnuksen versio (v1.0 tai v2.0) määräytyy sen ohjelmointirajapinnan sovellusluettelon ominaisuuden mukaanaccessTokenAcceptedVersion, jota sovelluksesi kutsuu. Jos accessTokenAcceptedVersion asetuksena on 1, sovelluksesi saa v1.0-tunnuksen.

Microsoftin todentamiskirjaston (MSAL) avulla voit hankkia joko v1.0- tai v2.0-käyttöoikeustietueen. Käyttöoikeustietueen avulla voit luoda valtuutusotsikon, joka sisältää haltijatunnuksen.

Esimerkiksi lataus-ohjelmointirajapinnan pyyntö käyttää seuraavia elementtejä käyttöoikeustietueen noutamiseen ja valtuutusotsikon luomiseen, jota käytetään kussakin pyynnössä:

• VIESTI https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token

Otsikot Microsoft Entra sovelluksen käyttämiseen:

• grant_type: "client_credentials"
• client_id: {Microsoft Entra App} -asiakastunnus
• client_secret tai client_certificate: {Microsoft Entra App}
• Soveltamisala: "https://management.azure.com/.default"

Jos accessTokenAcceptedVersion sovelluksen luettelotiedostossa on 1, sovelluksesi saa v1.0-käyttöoikeustietueen, vaikka se kutsuu v2-tunnuksen päätepistettä.

Resurssin/vaikutusalueen arvo on tunnuksen käyttäjäryhmä. Tämä ohjelmointirajapinta hyväksyy vain seuraavat käyttäjäryhmät:

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

Pyynnön viestin kokoaminen

Pyynnön URI

Ohjelmointirajapinnan versiointi: api-version=2024-02-01-preview
Päätepiste: https://api.ti.sentinel.azure.com/workspaces/{workspaceId}/threat-intelligence-stix-objects:upload?api-version={apiVersion}
Menetelmä: POST

Pyynnön otsikko

Authorization: Sisältää OAuth2-haltijatunnuksen
Content-Type: application/json

Pyynnön leipäteksti

Leipätekstin JSON-objekti sisältää seuraavat kentät:

Luo STIX-objektien matriisi STIX-muotomäärityksen avulla. Joitakin STIX-ominaisuusmäärityksiä laajennetaan täällä kätevyyden vuoksi linkittäen aiheeseen liittyviin STIX-asiakirjan osiin. Huomaa myös, että joillakin ominaisuuksilla, jotka ovat kelvollisia STIX:lle, ei ole vastaavia objektirakenteen ominaisuuksia Microsoft Sentinel.

Esimerkkipyyntöviesti

Tässä on PowerShell-mallifunktio, joka käyttää Entra sovelluksen rekisteröintiin ladattua itse allekirjoitettua varmennetta käyttöoikeustietueen ja valtuutusotsikon luomiseksi:

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
}

Yleiset ominaisuudet

Kaikki palvelimeen lataamisen ohjelmointirajapinnan avulla tuomasi objektit jakavat nämä yleiset ominaisuudet.

Lisätietoja on kohdassa STIX:n yleiset ominaisuudet.

Ilmaisin

Lisätietoja on kohdassa STIX-ilmaisin.

Hyökkäyskuvio

Noudata STIX-määrityksiä hyökkäyskuvion STIX-objektin luomiseksi. Käytä tätä esimerkkiä ylimääräisenä viittauksena.

Lisätietoja on artikkelissa STIX-hyökkäysmalli.

Käyttäjätiedot

Noudata STIX-määrityksiä käyttäjätietojen STIX-objektin luomiseksi. Käytä tätä esimerkkiä ylimääräisenä viittauksena.

Lisätietoja on kohdassa STIX-käyttäjätiedot.

Uhka-toimija

Noudata uhkatoimin STIX-objektin luomisen STIX-määrityksiä. Käytä tätä esimerkkiä ylimääräisenä viittauksena.

Lisätietoja on artikkelissa STIX-uhkatoimija.

Suhde

Noudata STIX-määrityksiä suhteen STIX-objektin luomiseksi. Käytä tätä esimerkkiä ylimääräisenä viittauksena.

Lisätietoja on artikkelissa STIX-suhde.

Vastausviestin käsitteleminen

Vastauksen otsikko sisältää HTTP-tilakoodin. Tästä taulukosta saat lisätietoja ohjelmointirajapintakutsun tuloksen tulkitsemisesta.

Vastauksen leipäteksti on virhesanomien matriisi JSON-muodossa:

Virheobjekti

Ohjelmointirajapinnan rajoittamista koskevat rajoitukset

Kaikkia rajoituksia sovelletaan käyttäjää kohti:

• 100 objektia pyyntöä kohden.
• 100 pyyntöä minuutissa.

Jos pyyntöjä on enimmäismäärää enemmän, 429 vastauksen otsikossa palautetaan http-tilakoodi, jossa on seuraava vastausteksti:

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

Noin 10 000 objektia minuutissa on suurin sallittu siirtomäärä, ennen kuin rajoitusvirhe vastaanotetaan.

Malliilmaisimen pyynnön leipäteksti

Seuraavassa esimerkissä näytetään, miten kaksi STIX-määrityksen ilmaisinta esitetään. Test Indicator 2 korostaa TLP (Traffic Light Protocol) -protokollan valkoiseksi yhdistetyllä objektimerkinnällä ja selventää sen kuvausta ja selitteitä englanniksi.

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

Vastauksen leipätekstimalli, jossa on vahvistusvirhe

Jos kaikki STIX-objektit vahvistetaan onnistuneesti, palautetaan HTTP 200 -tila, jossa on tyhjä vastausteksti.

Jos yhden tai useamman objektin vahvistus epäonnistuu, saat vastauksen leipätekstistä lisätietoja. Jos esimerkiksi lähetät matriisin, jossa on neljä ilmaisinta ja kolme ensimmäistä ovat hyviä, mutta neljännellä ei ole (pakollista id kenttää), luodaan HTTP-tilakoodi 200 vastaus seuraavan leipätekstin kanssa:

{
    "errors": [
        {
            "recordIndex":3, 
            "errorMessages": [
                "Error for Property=id: Required property is missing. Actual value: NULL."
            ]
        }
    ]
}

Objektit lähetetään matriisina, joten recordIndex alkaa kohdasta 0.

Muut mallit

Malliilmaisin

Tässä esimerkissä object_marking_refs ilmaisin on merkitty vihreällä TLP:llä käyttämällä marking-definition--089a6ecb-cc15-43cc-9494-767639779123 yleistä ominaisuutta. Lisää laajennusmääritteitä - ja rank -määritteitä toxicity sisältyy myös. Vaikka nämä ominaisuudet eivät ole ilmaisimien Microsoft Sentinel rakenteessa, objektin käyttö näillä ominaisuuksilla ei käynnistä virhettä. Ominaisuuksiin ei yksinkertaisesti viitata tai indeksoida työtilassa.

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

Hyökkäysmalli

Tämä hyökkäysmalli ja muut muut kuin ilmaisimen STIX-objektit ovat tarkasteltavissa vain hallintaliittymässä, ellet valitse uusia STIX-taulukoita. Lisätietoja taulukoista, joita tarvitaan tämänkaltaisten objektien tarkastelemiseen KQL:ssä, on artikkelissa Uhkatietojen tarkasteleminen.

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

Esimerkkisuhde uhkanäyttelijän ja käyttäjätietojen kanssa

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

Seuraavat vaiheet

Lisätietoja uhkatietojen käsittelystä Microsoft Sentinel on seuraavissa artikkeleissa:

• Tutustu uhkien hallintaan
• Uhkien ilmaisimien käsitteleminen
• Uhkien tunnistaminen vastaavilla analytiikalla
• Hyödynnä Microsoftin tietosyötettä ja ota MDTI-tietoyhdistin käyttöön