Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
L’API d’indicateurs de chargement Microsoft Sentinel permettait aux plateformes de renseignement sur les menaces ou aux applications personnalisées d’importer des indicateurs de compromission au format STIX dans un espace de travail Microsoft Sentinel. Ce document sert de référence à l’API héritée.
Importante
Cette API est en préversion, mais elle n’est plus recommandée. Utilisez la nouvelle API d’objets STIX en préversion pour charger le renseignement sur les menaces. Pour plus d’informations, consultez API d’objets STIX. Les conditions supplémentaires de la préversion Azure incluent des conditions juridiques supplémentaires qui s’appliquent à Azure fonctionnalités qui sont en version bêta, en préversion ou qui ne sont pas encore publiées en disponibilité générale.
Un appel d’API d’indicateurs de chargement comporte cinq composants :
- URI de la requête
- En-tête de message de requête HTTP
- Corps du message de requête HTTP
- Si vous le souhaitez, traiter l’en-tête du message de réponse HTTP
- Traiter éventuellement le corps du message de réponse HTTP
Inscrire votre application cliente auprès de Microsoft Entra ID
Pour s’authentifier auprès de Microsoft Sentinel, la demande à l’API des indicateurs de chargement nécessite un jeton d’accès Microsoft Entra valide. Pour plus d’informations sur l’inscription d’application, consultez Inscrire une application avec le Plateforme d'identités Microsoft ou consultez les étapes de base dans le cadre de la configuration du connecteur de données API des indicateurs de chargement.
Autorisations
Cette API nécessite que l’application Microsoft Entra appelante se voit attribuer le rôle Microsoft Sentinel contributeur au niveau de l’espace de travail.
Créer la demande
Cette section couvre les trois premiers des cinq composants abordés précédemment. Vous devez d’abord acquérir le jeton d’accès à partir de Microsoft Entra ID, que vous utilisez pour assembler l’en-tête de votre message de demande.
Acquisition d’un jeton d’accès
Acquérir un jeton d’accès Microsoft Entra avec l’authentification OAuth 2.0. 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 accessTokenAcceptedVersion propriété dans le manifeste de l’application de l’API que votre application appelle. Si accessTokenAcceptedVersion est défini sur 1, votre application reçoit un jeton v1.0.
Utilisez MSAL de la bibliothèque d’authentification Microsoft pour acquérir un jeton d’accès v1.0 ou v2.0. Vous pouvez également envoyer des demandes à l’API REST au format suivant :
- POST
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - En-têtes pour l’utilisation de Microsoft Entra App :
- grant_type : « client_credentials »
- client_id : {ID client de l’application Microsoft Entra}
- client_secret : {secret of Microsoft Entra App}
- Portée:
"https://management.azure.com/.default"
Si accessTokenAcceptedVersion dans le manifeste de l’application est défini sur 1, votre application reçoit un jeton d’accès v1.0 même si elle appelle le point de terminaison de jeton v2.
La valeur de ressource/d’étendue est 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 demande
Il existait deux versions de l’API héritée. Selon le point de terminaison, un autre nom de tableau était requis dans le corps de la demande. Cela a également été représenté par deux versions de l’action de connecteur d’application logique.
- Nom de l’action du connecteur : Renseignement sur les menaces - Indicateurs de chargement de compromission (déconseillé)
- Terminaison:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - Nom du tableau des indicateurs :
value
- Terminaison:
- Nom de l’action du connecteur : Renseignement sur les menaces - Indicateurs de chargement de compromission (V2) (préversion)
- Terminaison:
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - Nom du tableau des indicateurs :
indicators{ "sourcesystem":"TIsource-example", "indicators":[] }
- Terminaison:
URI de requête
Contrôle de version de l’API : api-version=2022-07-01
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 | Identifiez le nom de votre système source. La valeur Microsoft Sentinel est restreinte. |
| indicateurs (obligatoire) | tableau | Tableau d’indicateurs au format STIX 2.0 ou 2.1 |
Créez le tableau d’indicateurs à l’aide de la spécification de format d’indicateur STIX 2.1, qui a été condensée ici pour votre commodité avec des liens vers des sections importantes. Notez également que certaines propriétés, bien que valides pour STIX 2.1, n’ont pas de propriétés d’indicateur correspondantes dans Microsoft Sentinel.
| Nom de la propriété | Type | Description |
|---|---|---|
id (obligatoire) |
string | ID utilisé pour identifier l’indicateur. Consultez la section 2.9 pour obtenir des spécifications sur la création d’un id. Le format ressemble à indicator--<UUID> |
spec_version (facultatif) |
string | Version de l’indicateur STIX. Cette valeur est requise dans la spécification STIX, mais étant donné que cette API prend uniquement en charge STIX 2.0 et 2.1, lorsque ce champ n’est pas défini, l’API est définie par défaut sur 2.1 |
type (obligatoire) |
string | La valeur de cette propriété doit être indicator. |
created (obligatoire) |
Timestamp | Consultez la section 3.2 pour connaître les spécifications de cette propriété commune. |
modified (obligatoire) |
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 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 sur l’indicateur, y compris éventuellement son objectif et ses caractéristiques clés. Les producteurs doivent 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 provenir de l’élément indicator-type-ov |
pattern (obligatoire) |
string | Le modèle de détection de cet indicateur peut être exprimé sous la forme d’un modèle STIX ou d’un autre langage approprié tel que SNORT, YARA, etc. |
pattern_type (obligatoire) |
string | Langage de modèle utilisé dans cet indicateur. La valeur de cette propriété doit provenir de types de modèles. La valeur de cette propriété doit correspondre au type de données de modèle inclus dans la propriété pattern. |
pattern_version (facultatif) |
string | Version du langage de modèle utilisé pour les données dans la propriété pattern, qui doit correspondre au type de données de modèle inclus dans la propriété pattern. Pour les modèles qui n’ont pas de spécification formelle, vous devez utiliser la version de build ou de code avec laquelle le modèle est connu pour fonctionner. Pour le langage de modèle STIX, 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 être la dernière version du langage de modèle au moment de la création de cet objet. |
valid_from (obligatoire) |
Timestamp | Heure à partir de laquelle cet indicateur est considéré comme un indicateur valide des comportements qu’il est lié ou représente. |
valid_until (facultatif) |
Timestamp | Heure à laquelle cet indicateur ne doit plus être considéré comme un indicateur valide des comportements qu’il est lié ou représente. Si la propriété valid_until est omise, il n’existe aucune contrainte sur l’heure la plus récente pour laquelle l’indicateur est valide. Ce timestamp doit être supérieur à l’horodatage valid_from. |
kill_chain_phases (facultatif) |
liste de chaînes | Phase(s) de chaîne de destruction auxquelles cet indicateur correspond. La valeur de cette propriété doit provenir de la phase kill chain. |
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 ces informations n’est pas définie. Pour les créateurs d’objets qui souhaitent rester anonymes, conservez cette valeur non définie. |
revoked (facultatif) |
valeur booléenne | Les objets révoqués ne sont plus considérés comme valides par le créateur de l’objet. La révocation d’un objet est permanente ; Les versions ultérieures de l’objet avec ce idne doivent pas être créées.La valeur par défaut de cette propriété est false. |
labels (facultatif) |
liste de chaînes | La labels propriété spécifie un ensemble de termes utilisés pour décrire cet objet. Les termes sont définis par l’utilisateur ou par groupe d’approbation. Ces étiquettes s’affichent en tant que balises dans Microsoft Sentinel. |
confidence (facultatif) |
entier | La confidence propriété identifie la confiance que le créateur a dans l’exactitude de ses données. La valeur de confiance doit être un nombre compris entre 0 et 100.L’annexe A contient une table de mappages normatifs à d’autres échelles de confiance qui doivent être utilisées lors de la présentation de la valeur de confiance dans l’une de ces échelles. Si la propriété de confiance n’est pas présente, la confiance du contenu n’est pas spécifiée. |
lang (facultatif) |
string | La lang propriété identifie la langue du contenu du texte dans cet objet. Lorsqu’il est présent, il doit s’agir d’un code de langage conforme à RFC5646. Si la propriété n’est pas présente, la langue du contenu est en (anglais).Cette propriété doit être présente si le type d’objet contient des propriétés de texte pouvant être traduites (par exemple, nom, description). La langue des champs individuels de cet objet peut remplacer la lang propriété dans les marquages granulaires (voir la section 7.2.3). |
object_marking_refs (facultatif, Y compris TLP) |
liste de chaînes | La object_marking_refs propriété spécifie une liste des propriétés d’ID des objets marquage-définition qui s’appliquent à cet objet. Par exemple, utilisez l’ID de définition de marquage TLP (Traffic Light Protocol) pour désigner la sensibilité de la source de l’indicateur. Pour plus d’informations sur les ID de définition de marquage à utiliser pour le contenu TLP, consultez la section 7.2.1.4Dans certains cas, bien que rare, les définitions de marquage elles-mêmes peuvent être marquées avec des instructions de partage ou de gestion. Dans ce cas, cette propriété ne doit pas contenir de références au même objet Définition de marquage (autrement dit, elle ne peut pas contenir de références circulaires). Consultez la section 7.2.2 pour une définition plus approfondie des marquages de données. |
external_references (facultatif) |
liste de l’objet | La external_references propriété spécifie une liste de références externes qui font référence à des informations non-STIX. Cette propriété est utilisée pour fournir une ou plusieurs URL, descriptions ou ID aux enregistrements dans d’autres systèmes. |
granular_markings (facultatif) |
liste de marquage granulaire | La granular_markings propriété 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 allemande, de.Dans certains cas, bien que rare, les définitions de marquage elles-mêmes peuvent être marquées avec des instructions de partage ou de gestion. Dans ce cas, cette propriété ne doit pas contenir de références au même objet Définition de marquage (c’est-à-dire qu’elle ne peut pas contenir de références circulaires). Consultez la section 7.2.3 pour une définition plus approfondie des marquages de données. |
Traiter le message de réponse
L’en-tête de réponse contient un code status HTTP. Pour plus d’informations sur l’interprétation du résultat de l’appel d’API, reportez-vous à ce tableau.
| Code d'état | Description |
|---|---|
| 200 | Opération réussie. L’API retourne 200 quand un ou plusieurs indicateurs sont validés et publiés. |
| 400 | Format incorrect. Un élément de la demande n’est pas correctement mis en forme. |
| 401 | Non autorisé |
| 404 | Fichier introuvable. En règle générale, cette erreur se produit lorsque l’ID d’espace de travail est introuvable. |
| 429 | Le nombre de demandes en une minute a dépassé. |
| 500 | Erreur du serveur. Généralement, une erreur dans l’API ou 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 des erreurs de validation |
Error (objet)
| 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 |
Limites de limitation pour l’API
Toutes les limites sont appliquées par utilisateur :
- 100 indicateurs par demande.
- 100 demandes par minute.
S’il y a plus de requêtes que la limite, un 429 code http status dans l’en-tête de réponse est retourné avec le corps de la réponse suivant :
{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}
Environ 10 000 indicateurs par minute sont le débit maximal avant la réception d’une erreur de limitation.
Exemple de corps de requête
{
"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 erreur de validation
Si tous les indicateurs sont validés avec succès, une status HTTP 200 est retournée avec un corps de réponse vide.
Si la validation échoue pour un ou plusieurs indicateurs, le corps de la réponse est retourné avec plus d’informations. Par exemple, si vous envoyez un tableau avec quatre indicateurs et que les trois premiers sont bons, mais que le quatrième n’a pas de id (champ obligatoire), une réponse HTTP status code 200 est générée avec le corps 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, le recordIndex commence à 0.
Étape suivante
Cette API est héritée. Effectuez une migration pour utiliser l’API d’objets STIX pour charger le renseignement sur les menaces. Pour plus d’informations, consultez API d’objets STIX.