Fare riferimento all'API degli indicatori di caricamento (anteprima) per importare informazioni sulle minacce in Microsoft Sentinel

L'API degli indicatori di caricamento di Microsoft Sentinel consente alle piattaforme di intelligence sulle minacce o alle applicazioni personalizzate di importare indicatori di compromissione nel formato STIX in un'area di lavoro di Microsoft Sentinel. Sia che si usi l'API con il connettore dati api degli indicatori di caricamento di Microsoft Sentinel o come parte di una soluzione personalizzata, questo documento funge da riferimento.

Una chiamata API per gli indicatori di caricamento include cinque componenti:

1. L'URI della richiesta
2. Intestazione del messaggio di richiesta HTTP
3. Corpo del messaggio della richiesta HTTP
4. Facoltativamente, elaborare l'intestazione del messaggio di risposta HTTP
5. Facoltativamente, elaborare il corpo del messaggio di risposta HTTP

Registrare l'applicazione client con Microsoft Entra ID

Per eseguire l'autenticazione a Microsoft Sentinel, la richiesta all'API degli indicatori di caricamento richiede un token di accesso Microsoft Entra valido. Per altre informazioni sulla registrazione dell'applicazione, vedere Registrare un'applicazione con Microsoft Identity Platform o vedere i passaggi di base come parte della configurazione del connettore dati dell'API degli indicatori di caricamento.

Autorizzazioni

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

Creare la richiesta

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

Acquisire un token di accesso

Acquisire un token di accesso Di 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 dall'applicazione è determinata dalla accessTokenAcceptedVersion proprietà nel manifesto dell'app dell'API che l'applicazione sta chiamando. Se accessTokenAcceptedVersion è impostato su 1, l'applicazione riceverà un token v1.0.

Usare MICROSOFT Authentication Library MSAL per acquisire un token di accesso v1.0 o v2.0. In alternativa, inviare richieste all'API REST nel formato seguente:

• POST https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
• Intestazioni per l'uso di Microsoft Entra App:
• grant_type: "client_credentials"
• client_id: {ID client di Microsoft Entra App}
• client_secret: {secret of Microsoft Entra App}
• portata: "https://management.azure.com/.default"

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

Il valore della 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

Esistono due versioni dell'API degli indicatori di caricamento. A seconda dell'endpoint, nel corpo della richiesta è necessario un nome di matrice diverso. Questa operazione è rappresentata anche da due versioni dell'azione del connettore dell'app per la logica.

• Nome azione connettore: Intelligence per le minacce - Caricare indicatori di compromissione (deprecato)

  • Endpoint: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
  • Matrice del nome degli indicatori: value

    {
       "sourcesystem":"TIsource-example",
       "value":[]
    }
    

• Nome azione connettore: Intelligence per le minacce - Indicatori di caricamento della compromissione (V2) (anteprima)

  • Endpoint: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
  • Matrice del nome degli indicatori: indicators

    {
       "sourcesystem":"TIsource-example",
       "indicators":[]
    }
    

URI delle richiesta

Controllo delle versioni dell'API: api-version=2022-07-01
Endpoint: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
Metodo: POST

Intestazione della richiesta

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

Testo della richiesta

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

Creare la matrice di indicatori usando la specifica di formato indicatore STIX 2.1, che è stata condensata qui per praticità con collegamenti a sezioni importanti. Si notino anche alcune proprietà, mentre valide per STIX 2.1, non dispongono di proprietà dell'indicatore corrispondenti in Microsoft Sentinel.

Elaborare il messaggio di risposta

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

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 indicatori 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 indicatori al minuto è la velocità effettiva massima prima che venga ricevuto un errore di limitazione.

Corpo della richiesta di esempio

{
    "sourcesystem": "test", 
    "indicators":[
        {
            "type": "indicator",
            "spec_version": "2.1",
            "id": "indicator--10000003-71a2-445c-ab86-927291df48f8", 
            "name": "Test Indicator 1",
            "created": "2010-02-26T18:29:07.778Z", 
            "modified": "2011-02-26T18:29:07.778Z",
            "pattern": "[ipv4-addr:value = '172.29.6.7']", 
            "pattern_type": "stix",
            "valid_from": "2015-02-26T18:29:07.778Z"
        },
        {
            "type": "indicator",
            "spec_version": "2.1",
            "id": "indicator--67e62408-e3de-4783-9480-f595d4fdae52", 
            "created": "2023-01-01T18:29:07.778Z",
            "modified": "2025-02-26T18:29:07.778Z",
            "created_by_ref": "identity--19f33886-d196-468e-a14d-f37ff0658ba7", 
            "revoked": false,
            "labels": [
                "label 1",
                "label 2"
            ],
            "confidence": 55, 
            "lang": "en", 
            "external_references": [
                {
                    "source_name": "External Test Source", 
                    "description": "Test Report",
                    "external_id": "e8085f3f-f2b8-4156-a86d-0918c98c498f", 
                    "url": "https://fabrikam.com//testreport.json",
                    "hashes": {
                        "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
                    }
                }
            ],
            "object_marking_refs": [
                "marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"
            ],
            "granular_markings": [
                {
                    "marking_ref": "marking-definition--beb3ec79-03aa-4594-ad24-09982d399b80", 
                    "selectors": [ "description", "labels" ],
                    "lang": "en"
                }
            ],
            "name": "Test Indicator 2",
            "description": "This is a test indicator to demo valid fields", 
            "indicator_types": [
                "threatstream-severity-low", "threatstream-confidence-80"
            ],
            "pattern": "[ipv4-addr:value = '192.168.1.1']", 
            "pattern_type": "stix",
            "pattern_version": "2.1",
            "valid_from": "2023-01-01T18:29:07.778Z", 
            "valid_until": "2025-02-26T18:29:07.778Z",
            "kill_chain_phases": [
                {
                    "kill_chain_name": "lockheed-martin-cyber-kill-chain", 
                    "phase_name": "reconnaissance"
                }
            ]
        }
    ]
}

Corpo della risposta di esempio con errore di convalida

Se tutti gli indicatori vengono convalidati correttamente, viene restituito uno stato HTTP 200 con un corpo della risposta vuoto.

Se la convalida non riesce per uno o più indicatori, 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 di codice di stato HTTP 200 insieme al corpo seguente:

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

Gli indicatori vengono inviati come matrice, quindi inizia recordIndex da 0.

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