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

Articolo
10/31/2023

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.

Importante

Questa API è attualmente disponibile in ANTEPRIMA. Le condizioni aggiuntive per l'anteprima di Azure includono termini legali aggiuntivi che si applicano a funzionalità di Azure in versione beta, anteprima o diversamente non ancora disponibili a livello generale.

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

L'URI della richiesta
Intestazione del messaggio di richiesta HTTP
Corpo del messaggio della richiesta HTTP
Facoltativamente, elaborare l'intestazione del messaggio di risposta HTTP
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}
Ambito: "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

URI della richiesta

Controllo delle versioni dell'API: api-version=2022-07-01
Endpoint: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators?api-version=2022-07-01
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:

Nome campo	Tipo di dati	Descrizione
SourceSystem (obbligatorio)	stringa	Identificare il nome del sistema di origine. Il valore `Microsoft Sentinel` è limitato.
Valore (obbligatorio)	array	Matrice di indicatori in formato STIX 2.0 o 2.1

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.

Nome proprietà	Tipo	Descrizione
`id` (obbligatorio)	stringa	ID utilizzato per identificare l'indicatore. Vedere la sezione 2.9 per informazioni su come creare un oggetto `id`. Il formato è simile al seguente `indicator--<UUID>`
`spec_version` (facoltativo)	stringa	Versione dell'indicatore STIX. Questo valore è obbligatorio nella specifica STIX, ma poiché questa API supporta solo STIX 2.0 e 2.1, quando questo campo non è impostato, per impostazione predefinita l'API verrà impostata su `2.1`
`type` (obbligatorio)	stringa	Il valore di questa proprietà deve essere `indicator`.
`created` (obbligatorio)	timestamp	Vedere la sezione 3.2 per le specifiche di questa proprietà comune.
`modified` (obbligatorio)	timestamp	Vedere la sezione 3.2 per le specifiche di questa proprietà comune.
`name` (facoltativo)	stringa	Nome utilizzato per identificare l'indicatore. I produttori devono fornire questa proprietà per aiutare i prodotti e gli analisti a capire cosa fa effettivamente questo indicatore.
`description` (facoltativo)	stringa	Descrizione che fornisce maggiori dettagli e contesto sull'indicatore, potenzialmente includendone lo scopo e le caratteristiche principali. I produttori devono fornire questa proprietà per aiutare i prodotti e gli analisti a capire cosa fa effettivamente questo indicatore.
`indicator_types` (facoltativo)	Elenco di stringhe	Set di categorizzazioni per questo indicatore. I valori per questa proprietà devono provenire dall'indicatore-type-ov
`pattern` (obbligatorio)	stringa	Il modello di rilevamento per questo indicatore può essere espresso come modello STIX o un altro linguaggio appropriato, ad esempio SNORT, YARA e così via.
`pattern_type` (obbligatorio)	stringa	Linguaggio del modello usato in questo indicatore. Il valore di questa proprietà deve provenire dai tipi di pattern. Il valore di questa proprietà deve corrispondere al tipo di dati del criterio inclusi nella proprietà pattern.
`pattern_version` (facoltativo)	stringa	Versione del linguaggio del modello usato per i dati nella proprietà pattern, che deve corrispondere al tipo di dati del criterio inclusi nella proprietà pattern. Per i modelli che non hanno una specifica formale, deve essere usata la versione di compilazione o di codice con cui il modello è noto. Per il linguaggio modello STIX, la versione specifica dell'oggetto determina il valore predefinito. Per altre lingue, il valore predefinito deve essere la versione più recente del linguaggio di patterning al momento della creazione dell'oggetto.
`valid_from` (obbligatorio)	timestamp	Ora da cui questo indicatore viene considerato un indicatore valido dei comportamenti correlati a o rappresenta.
`valid_until` (facoltativo)	timestamp	Il momento in cui questo indicatore non deve più essere considerato un indicatore valido dei comportamenti a cui è correlato o rappresenta. Se la proprietà valid_until viene omessa, non esiste alcun vincolo per l'ora più recente per cui l'indicatore è valido. Questo timestamp deve essere maggiore del timestamp valid_from.
`kill_chain_phases` (facoltativo)	elenco di stringhe	Fasi della catena di interruzione a cui corrisponde questo indicatore. Il valore di questa proprietà deve provenire dalla fase Kill Chain.
`created_by_ref` (facoltativo)	stringa	La proprietà created_by_ref specifica la proprietà ID dell'entità che ha creato questo oggetto. Se questo attributo viene omesso, l'origine di queste informazioni non è definita. Per gli autori di oggetti che desiderano rimanere anonimi, mantenere questo valore indefinito.
`revoked` (facoltativo)	boolean	Gli oggetti revocati non sono più considerati validi dall'autore dell'oggetto. La revoca di un oggetto è permanente; non è necessario creare versioni future dell'oggetto con questa `id`impostazione. Il valore predefinito di questa proprietà è false.
`labels` (facoltativo)	Elenco di stringhe	La `labels` proprietà specifica un set di termini utilizzati per descrivere questo oggetto. I termini sono definiti dall'utente o dal gruppo di attendibilità. Queste etichette verranno visualizzate come tag in Microsoft Sentinel.
`confidence` (facoltativo)	integer	La `confidence` proprietà identifica l'attendibilità che l'autore ha nella correttezza dei dati. Il valore di attendibilità deve essere un numero compreso nell'intervallo compreso tra 0 e 100. Appendice A contiene una tabella di mapping normativi ad altre scale di attendibilità che devono essere usate quando si presenta il valore di attendibilità in una di queste scale. Se la proprietà di attendibilità non è presente, l'attendibilità del contenuto non è specificata.
`lang` (facoltativo)	stringa	La `lang` proprietà identifica la lingua del contenuto di testo in questo oggetto. Quando presente, deve essere un codice del linguaggio conforme alle RFC5646. Se la proprietà non è presente, la lingua del contenuto è `en` (inglese). Questa proprietà deve essere presente se il tipo di oggetto contiene proprietà di testo traducibili, ad esempio nome, descrizione. La lingua dei singoli campi in questo oggetto potrebbe eseguire l'override della `lang` proprietà nei contrassegni granulari (vedere la sezione 7.2.3).
`object_marking_refs` (facoltativo, incluso TLP)	Elenco di stringhe	La `object_marking_refs` proprietà specifica un elenco di proprietà ID di oggetti definizione di contrassegno che si applicano a questo oggetto. Ad esempio, usare l'ID definizione del contrassegno TLP (Traffic Light Protocol) per designare la riservatezza dell'origine dell'indicatore. Per informazioni dettagliate sugli ID di definizione di contrassegno da usare per il contenuto TLP, vedere la sezione 7.2.1.4 In alcuni casi, anche se non comune, i contrassegni delle definizioni stessi potrebbero essere contrassegnati con indicazioni sulla condivisione o sulla gestione. In questo caso, questa proprietà non deve contenere riferimenti allo stesso oggetto Definizione di contrassegno, ovvero non può contenere riferimenti circolari. Per altre definizioni dei contrassegni dati, vedere la sezione 7.2.2 .
`external_references` (facoltativo)	elenco di oggetti	La `external_references` proprietà specifica un elenco di riferimenti esterni che fanno riferimento a informazioni non STIX. Questa proprietà viene usata per fornire uno o più URL, descrizioni o ID ai record in altri sistemi.
`granular_markings` (facoltativo)	elenco di contrassegni granulari	La `granular_markings` proprietà consente di definire parti dell'indicatore in modo diverso. Ad esempio, la lingua dell'indicatore è inglese, `en` ma la descrizione è tedesco, `de`. In alcuni casi, anche se non comune, i contrassegni delle definizioni stessi potrebbero essere contrassegnati con indicazioni sulla condivisione o sulla gestione. In questo caso, questa proprietà non deve contenere riferimenti allo stesso oggetto Definizione di contrassegno( ad esempio, non può contenere riferimenti circolari). Per altre definizioni dei contrassegni dati, vedere la sezione 7.2.3 .

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.

Codice di stato	Descrizione
200	Esito positivo. L'API restituisce 200 quando uno o più indicatori vengono convalidati e pubblicati correttamente.
400	Formato non valido. Un elemento nella richiesta non è formattato correttamente.
401	Non autorizzato.
404	File non trovato. In genere questo errore si verifica quando l'ID dell'area di lavoro non viene trovato.
429	È stato superato il numero di richieste in un minuto.
500	Errore del server. In genere si verifica un errore nei servizi API o Microsoft Sentinel.

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

Nome campo	Tipo di dati	Descrizione
errori	Matrice di oggetti errore	Elenco degli errori di convalida

Oggetto Error

Nome campo	Tipo di dati	Descrizione
recordIndex	int	Indice degli indicatori nella richiesta
errorMessages	Matrice di stringhe	messaggi di errore

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", 
    "value":[
        {
            "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