Fare riferimento all'API degli indicatori di caricamento legacy

L'API Microsoft Sentinel indicatori di caricamento ha consentito alle piattaforme di intelligence sulle minacce o alle applicazioni personalizzate di importare indicatori di compromissione nel formato STIX in un'area di lavoro Microsoft Sentinel. Questo documento funge da riferimento all'API legacy.

Importante

Questa API è in ANTEPRIMA, ma non è più consigliata. Usare la nuova API degli oggetti STIX in anteprima per caricare l'intelligence sulle minacce. Per altre informazioni, vedere API degli oggetti STIX. Le condizioni aggiuntive per l'anteprima Azure includono termini legali aggiuntivi che si applicano alle funzionalità Azure in versione beta, in anteprima o in altro modo non ancora rilasciate nella disponibilità generale.

Una chiamata API degli indicatori 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 degli indicatori 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 come parte della configurazione del connettore dati api degli indicatori di caricamento.

Autorizzazioni

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 dall'applicazione è determinata dalla proprietà nel manifesto dell'app dell'API chiamata dall'applicazioneaccessTokenAcceptedVersion. 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:

• 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: {segreto dell'app Microsoft Entra}
• 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 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

Esistono due versioni dell'API legacy. A seconda dell'endpoint, nel corpo della richiesta era necessario un nome di matrice diverso. Questo è stato rappresentato anche da due versioni dell'azione del connettore dell'app per la logica.

1. Nome dell'azione del connettore: Intelligence per le minacce - Caricare gli indicatori di compromissione (deprecato)
   • Endpoint: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
   • Matrice di nome degli indicatori: value

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

• Nome dell'azione del connettore: Intelligence per le minacce - Caricare gli indicatori di compromissione (V2) (anteprima)
  • Endpoint: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
  • Matrice di nome degli indicatori: indicators

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

URI richiesta

Controllo delle versioni delle 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

Corpo della richiesta

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

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

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

Nome proprietà	Tipo	Descrizione
id (obbligatorio)	stringa	ID usato per identificare l'indicatore. Vedere la sezione 2.9 per le specifiche su come creare un oggetto id. Il formato è simile a 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, l'API verrà impostata per impostazione predefinita 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 usato 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 altri dettagli e contesto sull'indicatore, includendone potenzialmente lo scopo e le caratteristiche chiave. 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 proveniredall'indicatore-tipo-ov
pattern (obbligatorio)	stringa	Il modello di rilevamento per questo indicatore potrebbe essere espresso come pattern 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 modello. Il valore di questa proprietà deve corrispondere al tipo di dati del modello inclusi nella proprietà pattern.
pattern_version (facoltativo)	stringa	Versione del linguaggio del modello utilizzato per i dati nella proprietà pattern, che deve corrispondere al tipo di dati del modello inclusi nella proprietà pattern. Per i modelli che non hanno una specifica formale, deve essere usata la versione di compilazione o codice con cui il modello è noto per funzionare. Per il linguaggio del modello STIX, la versione della specifica dell'oggetto determina il valore predefinito. Per altre lingue, il valore predefinito deve essere la versione più recente del linguaggio di creazione dei modelli al momento della creazione dell'oggetto.
valid_from (obbligatorio)	Timestamp	Il tempo dal quale questo indicatore è considerato un indicatore valido dei comportamenti a cui è correlato o rappresenta.
valid_until (facoltativo)	Timestamp	Ora 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 all'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 l'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)	booleano	Gli oggetti revocati non sono più considerati validi dall'autore dell'oggetto. Revocare un oggetto è permanente; Le versioni future dell'oggetto con questo idoggetto non devono essere create. 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 da un gruppo di attendibilità definito. Queste etichette verranno visualizzate come tag in Microsoft Sentinel.
confidence (facoltativo)	integer	La confidence proprietà identifica la sicurezza dell'autore nella correttezza dei dati. Il valore di confidenza deve essere un numero compreso tra 0 e 100. L'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à confidence non è presente, la confidenza del contenuto non è specificata.
lang (facoltativo)	stringa	La lang proprietà identifica la lingua del contenuto di testo in questo oggetto. Se presente, deve essere un codice del linguaggio conforme a 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. Il linguaggio 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 degli oggetti di definizione di contrassegno che si applicano a questo oggetto. Ad esempio, usare l'ID definizione del contrassegno TLP (Traffic Light Protocol) per designare la sensibilità dell'origine dell'indicatore. Per informazioni dettagliate su quali ID di definizione di contrassegno usare per il contenuto TLP, vedere la sezione 7.2.1.4 In alcuni casi, anche se non comuni, le definizioni di contrassegno stesse potrebbero essere contrassegnate con linee guida per la condivisione o la gestione. In questo caso, questa proprietà non deve contenere riferimenti allo stesso oggetto Marking Definition, ovvero non può contenere riferimenti circolari. Per ulteriori 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 fa 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 è l'inglese, en ma la descrizione è il tedesco, de. In alcuni casi, anche se non comuni, le definizioni di contrassegno stesse potrebbero essere contrassegnate con linee guida per la condivisione o la gestione. In questo caso, questa proprietà non deve contenere riferimenti allo stesso oggetto Marking Definition, ovvero non può contenere riferimenti circolari. Per ulteriori 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. Per altre informazioni su come interpretare il risultato della chiamata API, fare riferimento a questa tabella.

Codice di stato	Descrizione
200	Completato. 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	Il numero di richieste in un minuto è stato superato.
500	Errore del server. In genere un errore nell'API o nei servizi di Microsoft Sentinel.

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

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

Oggetto Error

Nome del 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 sono 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 di 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 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 indicatori vengono inviati come matrice, quindi inizia recordIndex in corrispondenza di 0.

Passaggio successivo

Questa API è legacy. Eseguire la migrazione per usare l'API degli oggetti STIX per caricare l'intelligence sulle minacce. Per altre informazioni, vedere API degli oggetti STIX.