Importare intelligence sulle minacce per Microsoft Sentinel con l'API di caricamento (anteprima)

Importare intelligence sulle minacce da usare in Microsoft Sentinel con l'API di caricamento. Sia che si usi una piattaforma di intelligence per le minacce o un'applicazione personalizzata, usare questo documento come riferimento supplementare alle istruzioni in Connettere il SUGGERIMENTO con l'API di caricamento. L'installazione del connettore dati non è necessaria per connettersi all'API. L'intelligence sulle minacce che è possibile importare include indicatori di compromissione e altri oggetti di dominio STIX.

Structured Threat Information Expression (STIX) è un linguaggio per esprimere le minacce informatiche e le informazioni osservabili. Con l'API di caricamento è incluso il supporto avanzato per gli oggetti di dominio seguenti:

• Indicatore
• modello di attacco
• attore di minacce
• Identità
• Relazione

Per altre informazioni, vedere Introduzione a STIX.

Chiamare l'API

Una chiamata all'API di caricamento include cinque componenti:

1. URI della richiesta
2. Intestazione del messaggio di richiesta HTTP
3. Corpo del messaggio di richiesta HTTP
4. Elaborare facoltativamente l'intestazione del messaggio di risposta HTTP
5. Elaborare facoltativamente il corpo del messaggio di risposta HTTP

Registrare l'applicazione client con Microsoft Entra ID

Per eseguire l'autenticazione in Microsoft Sentinel, la richiesta all'API di caricamento richiede un token di accesso Microsoft Entra valido. Per altre informazioni sulla registrazione dell'applicazione, vedere Registrare un'applicazione con il Microsoft Identity Platform o vedere i passaggi di base nell'ambito della configurazione connect threat intelligence with upload API (Connettere intelligence sulle minacce con l'API di caricamento).

Questa API richiede che all'applicazione chiamante Microsoft Entra venga concesso il ruolo di collaboratore Microsoft Sentinel a livello di area di lavoro.

Creare la richiesta

Questa sezione illustra i primi tre dei cinque componenti illustrati in precedenza. È prima di tutto necessario acquisire il token di accesso da Microsoft Entra ID, usato per assemblare l'intestazione del messaggio di richiesta.

Acquisire un token di accesso

Acquisire un token di accesso Microsoft Entra con l'autenticazione OAuth 2.0. V1.0 e V2.0 sono token validi accettati dall'API.

La versione del token (v1.0 o v2.0) ricevuta è determinata dalla proprietà nel manifesto dell'app dell'API chiamata dall'applicazioneaccessTokenAcceptedVersion. Se accessTokenAcceptedVersion è impostato su 1, l'applicazione riceve un token v1.0.

Usare Microsoft Authentication Library (MSAL) per acquisire un token di accesso v1.0 o v2.0. Usare il token di accesso per creare l'intestazione di autorizzazione che contiene il token di connessione.

Ad esempio, una richiesta all'API di caricamento usa gli elementi seguenti per recuperare un token di accesso e creare l'intestazione di autorizzazione, usata in ogni richiesta:

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

Intestazioni per l'uso dell'app Microsoft Entra:

• grant_type: "client_credentials"
• client_id: {ID client dell'app Microsoft Entra}
• client_secret o client_certificate: {segreti dell'app Microsoft Entra}
• Ambito: "https://management.azure.com/.default"

Se accessTokenAcceptedVersion nel manifesto dell'app è impostato su 1, l'applicazione riceve un token di accesso v1.0 anche se chiama l'endpoint del token v2.

Il valore di risorsa/ambito è il gruppo di destinatari del token. Questa API accetta solo i gruppi di destinatari seguenti:

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

Assemblare il messaggio di richiesta

URI richiesta

Controllo delle versioni delle API: api-version=2024-02-01-preview
Endpoint: https://api.ti.sentinel.azure.com/workspaces/{workspaceId}/threat-intelligence-stix-objects:upload?api-version={apiVersion}
Metodo: POST

Intestazione della richiesta

Authorization: contiene il token di connessione OAuth2
Content-Type: application/json

Corpo della richiesta

L'oggetto JSON per il corpo contiene i campi seguenti:

Creare la matrice di oggetti STIX usando la specifica del formato STIX. Alcune specifiche della proprietà STIX vengono espanse qui per praticità con collegamenti alle sezioni pertinenti del documento STIX. Si noti anche che alcune proprietà, anche se valide per STIX, non hanno proprietà dello schema dell'oggetto corrispondenti in Microsoft Sentinel.

Messaggio di richiesta di esempio

Ecco una funzione di PowerShell di esempio che usa un certificato autofirmato caricato in una registrazione dell'app Entra per generare il token di accesso e l'intestazione di autorizzazione:

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
}

Proprietà comuni

Tutti gli oggetti importati con l'API di caricamento condividono queste proprietà comuni.

Per altre informazioni, vedere Proprietà comuni di STIX.

Indicatore

Per altre informazioni, vedere Indicatore STIX.

Modello di attacco

Seguire le specifiche STIX per la creazione di un oggetto STIX del modello di attacco. Usare questo esempio come riferimento aggiuntivo.

Per altre informazioni, vedere Modello di attacco STIX.

Identità

Seguire le specifiche STIX per la creazione di un oggetto IDENTITY STIX. Usare questo esempio come riferimento aggiuntivo.

Per altre informazioni, vedere Identità STIX.

Attore di minacce

Seguire le specifiche STIX per la creazione di un oggetto STIX dell'attore di minacce. Usare questo esempio come riferimento aggiuntivo.

Per altre informazioni, vedere Attore di minacce STIX.

Relazione

Seguire le specifiche STIX per la creazione di un oggetto STIX di relazione. Usare questo esempio come riferimento aggiuntivo.

Per altre informazioni, vedere Relazione STIX.

Elaborare il messaggio di risposta

L'intestazione della risposta contiene un codice di stato HTTP. Per altre informazioni su come interpretare il risultato della chiamata API, fare riferimento a questa tabella.

Il corpo della risposta è una matrice di messaggi di errore in formato JSON:

Oggetto Error

Limiti di limitazione per l'API

Tutti i limiti vengono applicati per utente:

• 100 oggetti per richiesta.
• 100 richieste al minuto.

Se sono presenti più richieste rispetto al limite, viene restituito un 429 codice di stato HTTP nell'intestazione della risposta con il corpo della risposta seguente:

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

Circa 10.000 oggetti al minuto sono la velocità effettiva massima prima che venga ricevuto un errore di limitazione.

Corpo della richiesta dell'indicatore di esempio

Nell'esempio seguente viene illustrato come rappresentare due indicatori nella specifica STIX. Test Indicator 2 evidenzia il protocollo TLP (Traffic Light Protocol) impostato su bianco con il contrassegno dell'oggetto mappato e la relativa descrizione e le relative etichette sono in inglese.

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

Corpo della risposta di esempio con errore di convalida

Se tutti gli oggetti STIX vengono convalidati correttamente, viene restituito uno stato HTTP 200 con un corpo di risposta vuoto.

Se la convalida non riesce per uno o più oggetti, il corpo della risposta viene restituito con altre informazioni. Ad esempio, se si invia una matrice con quattro indicatori e i primi tre sono validi, ma il quarto non ha un id (campo obbligatorio), viene generata una risposta 200 con codice di stato HTTP insieme al corpo seguente:

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

Gli oggetti vengono inviati come matrice, quindi inizia recordIndex in corrispondenza di 0.

Altri esempi

Indicatore di esempio

In questo esempio, l'indicatore è contrassegnato con il TLP verde usando marking-definition--089a6ecb-cc15-43cc-9494-767639779123 nella object_marking_refs proprietà comune. Sono inclusi anche altri attributi di estensione di toxicity e rank . Anche se queste proprietà non sono nello schema Microsoft Sentinel per gli indicatori, l'inserimento di un oggetto con queste proprietà non genera un errore. Le proprietà semplicemente non vengono referenziate o indicizzate nell'area di lavoro.

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

Modello di attacco di esempio

Questo modello di attacco e qualsiasi altro oggetto STIX non indicatore sono visualizzabili solo nell'interfaccia di gestione, a meno che non si acconsenta esplicitamente alle nuove tabelle STIX. Per altre informazioni sulle tabelle necessarie per visualizzare oggetti come questo in KQL, vedere Visualizzare l'intelligence sulle minacce.

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

Relazione di esempio con l'attore di minacce e l'identità

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

Passaggi successivi

Per altre informazioni su come usare l'intelligence sulle minacce in Microsoft Sentinel, vedere gli articoli seguenti:

• Informazioni sull'intelligence sulle minacce
• Usare gli indicatori di minaccia
• Usare l'analisi corrispondente per rilevare le minacce
• Usare il feed di intelligence di Microsoft e abilitare il connettore dati MDTI