Informations de référence sur l’API d’indicateurs de chargement (préversion) pour importer les renseignements sur les menaces dans Microsoft Sentinel
L’API d’indicateurs de chargement de Microsoft Sentinel permet aux plateformes de renseignement sur les menaces ou aux applications personnalisées d’importer les indicateurs de compromission au format STIX dans un espace de travail Microsoft Sentinel. Que vous utilisiez l’API avec le connecteur de données API d’indicateurs de chargement de Microsoft Sentinel ou dans le cadre d’une solution personnalisée, aidez-vous de ce document de référence.
Important
Cette API est actuellement en PRÉVERSION. Les Conditions d’utilisation supplémentaires des préversions Microsoft Azure incluent des conditions légales supplémentaires qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou pas encore disponibles dans la version en disponibilité générale.
Un appel à l’API d’indicateurs de chargement se compose de cinq éléments :
- URI de requête
- En-tête du message de requête HTTP
- Corps du message de requête HTTP
- Traitement facultatif de l’en-tête du message de réponse HTTP
- Traitement facultatif du corps du message de réponse HTTP
Inscrire votre application cliente avec l’ID Microsoft Entra
Pour s’authentifier auprès de Microsoft Sentinel, la demande adressée à l’API des indicateurs de chargement nécessite un jeton d’accès Microsoft Entra valide. Pour plus d’informations sur l’inscription d’une application, consultez Inscrire une application avec la plateforme d’identités Microsoft ou consultez les étapes de base du processus de configuration du connecteur de données API d’indicateurs de chargement.
Autorisations
Cette API nécessite que l’application Microsoft Entra appelante soit accordée au rôle contributeur Microsoft Sentinel au niveau de l’espace de travail.
Créer la requête
Cette section couvre les trois premiers des cinq composants listés ci-dessus. Vous devez d’abord acquérir le jeton d’accès à partir de l’ID Microsoft Entra, que vous utilisez pour assembler votre en-tête de message de demande.
Obtenir un jeton d’accès
Acquérir un jeton d’accès Microsoft Entra avec authentification OAuth 2.0. Les versions v1.0 et v2.0 sont des jetons valides acceptés par l’API.
La version du jeton (v1.0 ou v2.0) que votre application reçoit est déterminée par la propriété accessTokenAcceptedVersion dans le manifeste de l’application de l’API que votre application appelle. Si accessTokenAcceptedVersion est définie sur 1, votre application recevra un jeton v1.0.
Utilisez la bibliothèque d’authentification Microsoft MSAL pour acquérir un jeton d’accès v1.0 ou v2.0. Ou envoyez des requêtes à l’API REST au format suivant :
- POST
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - En-têtes pour l’utilisation de l’application Microsoft Entra :
- grant_type : "client_credentials"
- client_id : {ID client de Microsoft Entra App}
- client_secret : {secret de Microsoft Entra App}
- scope :
"https://management.azure.com/.default"
Si accessTokenAcceptedVersion dans le manifeste de l’application est défini sur 1, votre application recevra un jeton d’accès v1.0, même si elle appelle le point de terminaison du jeton v2.
La valeur resource/scope (ressource/étendue) correspond à l’audience du jeton. Cette API accepte uniquement les audiences suivantes :
https://management.core.windows.net/https://management.core.windows.nethttps://management.azure.com/https://management.azure.com
Assembler le message de requête
Il existe deux versions de l’API d’indicateurs de chargement. Selon le point de terminaison, un autre nom de tableau est requis dans le corps de la demande. Cela est également représenté par deux versions de l’action du connecteur d’application logique.
Nom de l’action du connecteur : Threat Intelligence - Charger des indicateurs de compromission (déconseillé)
- Point de terminaison :
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - Tableau de noms d’indicateurs :
value{ "sourcesystem":"TIsource-example", "value":[] }
- Point de terminaison :
Nom de l’action du connecteur : Threat Intelligence - Charger les indicateurs de compromission (V2) (préversion)
- Point de terminaison :
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - Tableau de noms d’indicateurs :
indicators{ "sourcesystem":"TIsource-example", "indicators":[] }
- Point de terminaison :
URI de demande
Version d’API : api-version=2022-07-01
Point de terminaison : https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
Méthode : POST
En-tête de requête
Authorization : contient le jeton du porteur OAuth2
Content-Type: application/json
Corps de la demande
L’objet JSON du corps contient les champs suivants :
| Nom du champ | Type de données | Description |
|---|---|---|
| SourceSystem (obligatoire) | string | Identifie le nom de votre système source. La valeur Microsoft Sentinel est restreinte. |
| indicateurs (requis) | tableau | Tableau d’indicateurs au format STIX 2.0 ou 2.1 |
Créez le tableau d’indicateurs à l’aide de la spécification du format d’indicateur STIX 2.1, qui a été condensée ici à votre convenance avec des liens vers des sections importantes. Notez également que certaines propriétés, bien que valides pour STIX 2.1, n’ont aucune propriété d’indicateur correspondante dans Microsoft Sentinel.
| Nom de la propriété | Type | Description |
|---|---|---|
id (requis) |
string | ID utilisé pour identifier l’indicateur. Consultez la section 2.9 pour connaître les spécifications s’appliquant à la création d’un id. Le format est similaire à indicator--<UUID> |
spec_version (facultatif) |
string | Version de l’indicateur STIX. Cette valeur est obligatoire dans la spécification STIX, mais étant donné que cette API prend uniquement en charge STIX 2.0 et 2.1, quand ce champ n’est pas défini, l’API est définie par défaut sur 2.1 |
type (requis) |
string | La valeur de cette propriété doit obligatoirement être indicator. |
created (requis) |
timestamp | Consultez la section 3.2 pour connaître les spécifications de cette propriété commune. |
modified (requis) |
timestamp | Consultez la section 3.2 pour connaître les spécifications de cette propriété commune. |
name (facultatif) |
string | Nom utilisé pour identifier l’indicateur. Les producteurs doivent généralement fournir cette propriété pour aider les produits et les analystes à comprendre ce que cet indicateur fait réellement. |
description (facultatif) |
string | Description qui fournit plus de détails et de contexte au sujet de l’indicateur, par exemple son objectif et ses caractéristiques principales. Les producteurs doivent généralement fournir cette propriété pour aider les produits et les analystes à comprendre ce que cet indicateur fait réellement. |
indicator_types (facultatif) |
Liste de chaînes | Ensemble de catégorisations pour cet indicateur. Les valeurs de cette propriété doivent généralement provenir de indicator-type-ov |
pattern (requis) |
string | Le modèle de détection de cet indicateur peut être exprimé sous la forme d’un STIX Patterning ou d’un autre langage approprié comme SNORT, YARA, etc. |
pattern_type (requis) |
string | Langage du modèle utilisé dans cet indicateur. La valeur de cette propriété doit généralement provenir des types de modèles. La valeur de cette propriété doit obligatoirement correspondre au type de données de modèle inclus dans la propriété pattern. |
pattern_version (facultatif) |
string | Version du langage du modèle utilisé pour les données dans la propriété pattern, qui doit obligatoirement correspondre au type de données de modèle inclus dans la propriété pattern. Pour les modèles sans spécification formelle, la version de build ou de code avec laquelle le modèle fonctionne habituellement doit généralement être utilisée. Pour le langage STIX Patterning, la version de spécification de l’objet détermine la valeur par défaut. Pour les autres langages, la valeur par défaut doit généralement être la dernière version du langage de modèle utilisée au moment de la création de cet objet. |
valid_from (requis) |
timestamp | Date/heure à partir de laquelle cet indicateur est considéré comme un indicateur valide des comportements auxquels il est lié ou qu’il représente. |
valid_until (facultatif) |
timestamp | Date/heure à laquelle cet indicateur ne doit plus être considéré comme un indicateur valide des comportements auxquels il est lié ou qu’il représente. Si la propriété valid_until est omise, aucune contrainte ne s’applique quant à la durée de validité de l’indicateur. Cet horodatage doit obligatoirement être ultérieur à l’horodatage valid_from. |
kill_chain_phases (facultatif) |
Liste de chaînes | La ou les phases de la chaîne de destruction auxquelles cet indicateur correspond. La valeur de cette propriété doit généralement provenir de la phase de la chaîne de destruction. |
created_by_ref (facultatif) |
string | La propriété created_by_ref spécifie la propriété ID de l’entité qui a créé cet objet. Si cet attribut est omis, la source de cette information n’est pas définie. Pour les créateurs d’objets qui souhaitent rester anonymes, conservez cette valeur non définie. |
revoked (facultatif) |
boolean | Les objets révoqués ne sont plus considérés comme valides par le créateur d’objet. La révocation d’un objet est permanente ; Les futures versions de l’objet avec cela id ne doivent pas être créées.La valeur par défaut de cette propriété est false. |
labels (facultatif) |
Liste de chaînes | La propriété labels spécifie un ensemble de termes employés pour décrire cet objet. Les termes sont définis par l’utilisateur ou par le groupe d’approbation. Ces étiquettes s’affichent sous forme de balises dans Microsoft Sentinel. |
confidence (facultatif) |
entier | La propriété confidence indique la confiance que le créateur a dans l’exactitude de ses données. La valeur de confiance doit obligatoirement être un nombre compris entre 0 et 100.L’Annexe A contient une table des mappages normatifs à d’autres échelles de confiance qui doivent obligatoirement être utilisés pour présenter la valeur de confiance dans l’une de ces échelles. Si la propriété de confiance est omise, la confiance du contenu n’est pas spécifiée. |
lang (facultatif) |
string | La propriété lang identifie la langue du contenu textuel dans cet objet. Quand elle est présente, elle doit obligatoirement être un code de langage conforme à la spécificationRFC 5646. Si la propriété est omise, la langue du contenu est en (anglais).Cette propriété doit généralement être présente si le type d’objet contient des propriétés de texte traduisible (par exemple, un nom ou une description). La langage des champs individuels de cet objet peut remplacer la propriété lang dans des marquages granulaires (voir la section 7.2.3). |
object_marking_refs (facultatif, y compris le protocole TLP) |
Liste de chaînes | La propriété object_marking_refs spécifie une liste des propriétés d’ID des objets de définition de marquage qui s’appliquent à cet objet. Par exemple, utilisez l’ID de définition de marquage du protocole TLP (Traffic Light Protocol) pour désigner la sensibilité de la source de l’indicateur. Pour obtenir plus d’informations sur les ID de définition de marquage à utiliser pour le contenu du protocole TLP, voir la section 7.2.1.4Dans de rares cas, les définitions de marquage peuvent elles-mêmes être marquées avec des aides de partage ou de gestion. Le cas échéant, cette propriété ne doit pas contenir de références au même objet de définition de marquage (elle ne peut donc pas contenir de références circulaires). Consultez la section 7.2.2 pour en savoir plus sur la définition des marquages de données. |
external_references (facultatif) |
liste d’objets | La propriété external_references spécifie une liste de références externes à des informations ne relevant pas du système STIX. Vous utilisez cette propriété pour fournir une ou plusieurs URL, des descriptions ou des ID d’enregistrements dans d’autres systèmes. |
granular_markings (facultatif) |
liste de marquages granulaires | La propriété granular_markings permet de définir des parties de l’indicateur différemment. Par exemple, la langue de l’indicateur est l’anglais, en, mais la description est en langue allemande, de.Dans de rares cas, les définitions de marquage peuvent elles-mêmes être marquées avec des aides de partage ou de gestion. Le cas échéant, cette propriété ne doit pas contenir de références au même objet de définition de marquage (elle ne peut donc pas contenir de références circulaires). Consultez la section 7.2.3 pour en savoir plus sur la définition des marquages de données. |
Traiter le message de réponse
L’en-tête de réponse contient un code d’état HTTP. Pour plus d’informations sur l’interprétation du résultat de l’appel d’API, reportez-vous au tableau ci-dessous.
| Code d’état | Description |
|---|---|
| 200 | Opération réussie. L’API retourne 200 quand un ou plusieurs indicateurs ont été validés et publiés avec succès. |
| 400 | Format incorrect. Un élément de la requête n’est pas correctement mis en forme. |
| 401 | Non autorisé. |
| 404 | Fichier introuvable. En règle générale, cette erreur se produit quand l’ID de l’espace de travail est introuvable. |
| 429 | Le nombre de requêtes par minute a été dépassé. |
| 500 | Erreur de serveur. Il s’agit généralement d’une erreur dans l’API ou dans les services Microsoft Sentinel. |
Le corps de la réponse est un tableau de messages d’erreur au format JSON :
| Nom du champ | Type de données | Description |
|---|---|---|
| erreurs | Tableau d’objets d’erreur | Liste d’erreurs de validation |
Objet Error
| Nom du champ | Type de données | Description |
|---|---|---|
| recordIndex | int | Index des indicateurs dans la requête |
| errorMessages | Tableau de chaînes | Messages d’erreur |
Seuils de limitation pour l’API
Toutes les limites sont appliquées par utilisateur :
- 100 indicateurs par requête.
- 100 requêtes par minute.
S’il y a plus de requêtes que la limite, un code d’état HTTP 429 dans l’en-tête de réponse est retourné avec le corps de réponse suivant :
{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}
Le nombre maximal est d’environ 10 000 indicateurs par minute avant qu’une erreur de limitation ne soit reçue.
Exemple de corps de la demande
{
"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"
}
]
}
]
}
Exemple de corps de réponse avec une erreur de validation
Si tous les indicateurs sont validés correctement, un code d’état HTTP 200 est retourné avec un corps de réponse vide.
Si la validation échoue pour un ou plusieurs indicateurs, le corps de réponse retourné contient des informations supplémentaires. Par exemple, si vous envoyez un tableau de quatre indicateurs et que seuls les trois premiers sont valides, car le quatrième n’a pas le champ id (obligatoire), un code d’état HTTP 200 est généré avec le corps de réponse suivant :
{
"errors": [
{
"recordIndex":3,
"errorMessages": [
"Error for Property=id: Required property is missing. Actual value: NULL."
]
}
]
}
Les indicateurs étant envoyés sous forme de tableau, recordIndex commence à 0.
Étapes suivantes
Pour plus d’informations sur l’utilisation du renseignement sur les menaces (la Threat Intelligence) dans Microsoft Sentinel, reportez-vous aux articles suivants :
- Comprendre le renseignement sur les menaces
- Utiliser des indicateurs de menace
- Utiliser l’analytique de correspondance pour détecter les menaces
- Utiliser le flux de renseignement de Microsoft et activer le connecteur de données MDTI