[Déconseillé] Créer un connecteur sans code hérité pour Microsoft Sentinel

Référencez ce document si vous devez gérer ou mettre à jour un connecteur de données en fonction de cette version héritée antérieure du CCP.

Le CCP fournit aux partenaires, aux utilisateurs expérimentés et aux développeurs la possibilité de créer des connecteurs personnalisés, de les connecter et d’ingérer des données sur Microsoft Sentinel. Les connecteurs créés par le biais de la CCP peuvent être déployés via une API, un modèle ARM ou une solution dans le hub de contenu de Microsoft Sentinel.

Les connecteurs créés à l’aide de la CCP sont entièrement SaaS, sans aucune exigence en matière d’installation de service, et comprennent également un monitoring de l’intégrité et une assistance complète fournis par Microsoft Sentinel.

Créez votre connecteur de données en définissant des configurations JSON, avec des paramètres qui déterminent l’apparence de la page du connecteur de données dans Microsoft Sentinel ainsi que des paramètres d’interrogation qui définissent le fonctionnement de la connexion.

Pour créer votre connecteur CCP et vous connecter à votre source de données à partir de Microsoft Sentinel, procédez comme suit :

Cet article décrit la syntaxe utilisée dans les configurations JSON de la plateforme CCP et les procédures de déploiement de votre connecteur via une API, un modèle ARM ou une solution Microsoft Sentinel.

Prérequis

Avant de générer un connecteur, nous vous recommandons de comprendre le comportement de votre source de données et la manière exacte dont Microsoft Sentinel devra se connecter.

Par exemple, vous devez connaître les différents types d’authentification, de pagination et de points de terminaison d’API nécessaires à l’établissement des connexions.

Créer un fichier config JSON de connecteur

Votre connecteur CCP personnalisé comporte deux sections JSON principales nécessaires au déploiement. Complétez ces zones pour définir la façon dont votre connecteur s’affiche sur le portail Azure et comment il connecte Microsoft Sentinel à votre source de données.

• connectorUiConfig. Définit les éléments visuels et le texte affiché sur la page du connecteur de données dans Microsoft Sentinel. Pour plus d’informations, consultez Configurer l’interface utilisateur de votre connecteur.

• pollingConfig. Définit la façon dont Microsoft Sentinel recueille les données de votre source de données. Pour plus d’informations, consultez Configurer les paramètres d’interrogation de votre connecteur.

Ensuite, si vous déployez votre connecteur sans code via ARM, vous devrez inclure ces sections dans le modèle ARM pour les connecteurs de données.

Examinez les autres exemples de connecteurs de données CCP ou téléchargez l’exemple de modèle DataConnector_API_CCP_template.json (préversion).

Configurer l’interface utilisateur de votre connecteur

Cette section décrit les options de configuration disponibles pour personnaliser l’interface utilisateur de la page du connecteur de données.

L’illustration suivante montre la page d’un exemple de connecteur de données, où sont mis en évidence des numéros qui correspondent aux zones importantes de l’interface utilisateur :

1. Titre. Titre affiché pour votre connecteur de données.
2. Logo. Icône affichée pour votre connecteur de données. Sa personnalisation n’est possible que si le déploiement s’effectue dans le cadre d’une solution.
3. Status. Indique si votre connecteur de données est connecté ou pas à Microsoft Sentinel.
4. Graphiques de données. Affiche les requêtes pertinentes et la quantité de données ingérées au cours des deux dernières semaines.
5. Onglet Instructions. Comporte une section Prérequis, avec une liste de validations minimales à opérer par l’utilisateur avant qu’il puisse activer le connecteur, et une section Instructions pour guider l’utilisateur dans l’activation du connecteur. Cette section peut inclure du texte, des boutons, des formulaires, des tableaux et d’autres widgets courants pour simplifier le processus.
6. Onglet Étapes suivantes. Contient des informations utiles pour comprendre comment rechercher des données dans les journaux des événements, tels que des exemples de requêtes.

Voici les sections connectorUiConfig et la syntaxe nécessaire pour configurer l’interface utilisateur :

Il est compliqué d’assembler tous ces éléments. Utilisez l’outil de validation de l’expérience utilisateur de la page du connecteur pour tester les composants que vous assemblez.

dataTypes

graphQueries

Définit une requête qui présente l’ingestion des données au cours des deux dernières semaines dans le volet Graphiques de données.

Fournissez soit une requête pour tous les types de données du connecteur de données, soit une requête différente pour chaque type de données.

instructionSteps

Cette section fournit des paramètres qui définissent l’ensemble des instructions qui s’affichent sur la page de votre connecteur de données dans Microsoft Sentinel.

instructions

Affiche un groupe d’instructions, avec différentes options en tant que paramètres et la possibilité d’imbriquer davantage d’instructionsSteps dans des groupes.

APIKey

Vous pouvez créer un modèle de fichier config JSON, avec des paramètres d’espace réservé, afin de le réutiliser pour plusieurs connecteurs ou même pour créer un connecteur avec des données que vous n’avez pas encore.

Pour créer des paramètres d’espace réservé, définissez un tableau supplémentaire nommé userRequestPlaceHoldersInput dans la section Instructions de votre fichier config JSON de la CCP en utilisant la syntaxe suivante :

"instructions": [
                {
                  "parameters": {
                    "enable": "true",
                    "userRequestPlaceHoldersInput": [
                      {
                        "displayText": "Organization Name",
                        "requestObjectKey": "apiEndpoint",
                        "placeHolderName": "{{placeHolder}}"
                      }
                    ]
                  },
                  "type": "APIKey"
                }
              ]

Le paramètre userRequestPlaceHoldersInput comprend les attributs suivants :

CopyableLabel

Exemple :

Exemple de code :

{
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}

InfoMessage

Voici un exemple de message d’information inclus :

À l’inverse, l’illustration suivante montre un message d’information non inlined :

InstructionStepsGroup

Voici un exemple de groupe d’instructions pouvant être développé :

Pour obtenir un exemple détaillé, consultez le JSON de configuration du connecteur DNS Windows.

InstallAgent

Certains types InstallAgent apparaissent sous la forme d’un bouton, d’autres sous la forme d’un lien. Voici des exemples des deux :

metadata

Cette section fournit des métadonnées dans l’interface utilisateur du connecteur de données sous la zone Description.

autorisations

resourceProvider

sampleQueries

Configurer d’autres options de lien

Pour définir un lien inclus en utilisant Markdown, servez-vous de l’exemple suivant. Ici, un lien est fourni dans la description d’une instruction :

{
   "title": "",
   "description": "Make sure to configure the machine's security according to your organization's security policy\n\n\n[Learn more >](https://aka.ms/SecureCEF)"
}

Pour définir un lien comme modèle ARM, utilisez l’exemple suivant comme guide :

{
   "title": "Azure Resource Manager (ARM) template",
   "description": "1. Click the **Deploy to Azure** button below.\n\n\t[![Deploy To Azure](https://aka.ms/deploytoazurebutton)]({URL to custom ARM template})"
}

Valider l’expérience utilisateur de la page du connecteur de données

Suivez ces étapes pour afficher et valider l’expérience utilisateur du connecteur.

1. L’utilitaire de test est accessible via l’URL https://aka.ms/sentineldataconnectorvalidateurl
2. Accédez à Microsoft Sentinel -> Connecteurs de données
3. Cliquez sur le bouton « importer » et sélectionnez un fichier JSON qui contient uniquement la section connectorUiConfig de votre connecteur de données.

Pour plus d’informations sur cet outil de validation, consultez les instructions Générer le connecteur dans notre guide de génération GitHub.

Configurer les paramètres d’interrogation de votre connecteur

Cette section décrit la configuration de l’interrogation des données de votre source de données pour un connecteur de données sans code.

Le code suivant illustre la syntaxe de la section pollingConfig du fichier config de la CCP.

"pollingConfig": {
    "auth": {
    },
    "request": {
    },
    "response": {
    },
    "paging": {
    }
 }

La section pollingConfig comprend les propriétés suivantes :

Pour plus d’informations, consultez Exemple de code pollingConfig.

Configuration d’auth

La section auth de la configuration pollingConfig comprend les paramètres suivants, selon le type défini dans l’élément authType :

Paramètres authType de base

Paramètres authType pour APIKey

Paramètres d’authType OAuth2

La plateforme du connecteur sans code prend en charge l’octroi de code d’autorisation OAuth 2.0.

Le type d’autorisation du code d’autorisation est utilisé par les clients confidentiels et publics pour échanger un code d’autorisation pour un jeton d’accès.

Une fois que l’utilisateur est retourné au client via l’URL de redirection, l’application obtient le code d’autorisation de l’URL et l’utilise pour demander un jeton d’accès.

Voici un exemple de la façon dont une configuration OAuth2 peut se présenter :

"pollingConfig": {
    "auth": {
        "authType": "OAuth2",
        "authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent",
        "redirectionEndpoint": "https://portal.azure.com/TokenAuthorize",
        "tokenEndpoint": "https://oauth2.googleapis.com/token",
        "authorizationEndpointQueryParameters": {},
        "tokenEndpointHeaders": {
            "Accept": "application/json"
        },
        "TokenEndpointQueryParameters": {},
        "isClientSecretInHeader": false,
        "scope": "https://www.googleapis.com/auth/admin.reports.audit.readonly",
        "grantType": "authorization_code",
        "contentType": "application/x-www-form-urlencoded",
        "FlowName": "AuthCode"
    },

Paramètres authType pour Session

Configuration de requête

La section request de la configuration pollingConfig comprend les paramètres suivants :

Configuration de réponse

La section response de la configuration pollingConfig comprend les paramètres suivants :

Le code suivant illustre un exemple de la valeur eventsJsonPaths pour un message de niveau supérieur :

"eventsJsonPaths": [
              "$"
            ]

Configuration de pagination

La section paging de la configuration pollingConfig comprend les paramètres suivants :

Exemple de code pollingConfig

Le code suivant illustre un exemple de la section pollingConfig du fichier config de la CCP :

"pollingConfig": {
    "auth": {
        "authType": "APIKey",
        "APIKeyIdentifier": "token",
        "APIKeyName": "Authorization"
     },
     "request": {
        "apiEndpoint": "https://api.github.com/../{{placeHolder1}}/audit-log",
        "rateLimitQPS": 50,
        "queryWindowInMin": 15,
        "httpMethod": "Get",
        "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
        "retryCount": 2,
        "timeoutInSeconds": 60,
        "headers": {
           "Accept": "application/json",
           "User-Agent": "Scuba"
        },
        "queryParameters": {
           "phrase": "created:{_QueryWindowStartTime}..{_QueryWindowEndTime}"
        }
     },
     "paging": {
        "pagingType": "LinkHeader",
        "pageSizeParaName": "per_page"
     },
     "response": {
        "eventsJsonPaths": [
          "$"
        ]
     }
}

Déployer votre connecteur dans Microsoft Sentinel et démarrer l’ingestion des données

Après avoir créé votre fichier config JSON, comprenant à la fois l’interface utilisateur et la configuration d’interrogation, déployez votre connecteur dans votre espace de travail Microsoft Sentinel.

1. Utilisez l’une des options suivantes pour déployer votre connecteur de données.

   Conseil

   L’avantage du déploiement par le biais d’un modèle Azure Resource Manager (ARM) est que plusieurs valeurs sont intégrées au modèle et que vous n’avez pas besoin de les définir manuellement dans un appel d’API.

   • Déployer le bot avec un modèle ARM
   • Déployer via une API

   Encapsulez vos collections de configurations JSON dans un modèle ARM pour déployer votre connecteur. Pour garantir un déploiement de votre connecteur de données dans l’espace de travail approprié, veillez à définir ce dernier dans le modèle ARM ou à le sélectionner au moment de déployer le modèle ARM.

   1. Préparez un fichier JSON de modèle ARM pour votre connecteur. Par exemple, consultez les fichiers JSON de modèle ARM suivants :

      • Connecteur de données dans la solution Slack
      • Connecteur de données dans la solution GitHub

   2. Dans le portail Azure, recherchez Déployer un modèle personnalisé.

   3. Sur la page Déploiement personnalisé, sélectionnez Créer votre propre modèle dans l’éditeur>Charger un fichier. Naviguez jusqu’à votre modèle ARM local et sélectionnez-le, puis enregistrez vos modifications.

   4. Sélectionnez votre abonnement et votre groupe de ressources, puis entrez dans l’espace de travail Log Analytics où vous souhaitez déployer votre connecteur personnalisé.

   5. Sélectionnez Vérifier + créer pour déployer votre connecteur personnalisé sur Microsoft Sentinel.

   6. Dans Microsoft Sentinel, accédez à la page Connecteurs de données, puis recherchez votre nouveau connecteur. Configurez-le pour démarrer l’ingestion des données.

   Pour plus d’informations, consultez Déployer un modèle local dans la documentation d’Azure Resource Manager.

2. Configurez votre connecteur de données pour connecter votre source de données et commencer à ingérer des données dans Microsoft Sentinel. Vous pouvez vous connecter à votre source de données soit via le portail, comme avec les connecteurs de données prêts à l’emploi, soit via une API.

   Lorsque vous utilisez le portail Azure pour vous connecter, les données utilisateur sont envoyées automatiquement. Lorsque vous vous connectez via l’API, vous devez envoyer les paramètres d’authentification pertinents dans l’appel d’API.

   • Connexion via le portail Azure
   • Connexion via l’API

   Dans la page de votre connecteur de données Microsoft Sentinel, suivez les instructions que vous avez fournies pour vous connecter au connecteur de données.

   La page du connecteur de données dans Microsoft Sentinel est contrôlée par la configuration InstructionSteps dans l’élément connectorUiConfig du fichier config JSON de la plateforme CCP. Si vous rencontrez des problèmes avec la connexion à l’interface utilisateur, assurez-vous que vous disposez de la bonne configuration pour votre type d’authentification.

3. Dans Microsoft Sentinel, accédez à la page Journaux et vérifiez que les journaux de votre source de données arrivent dans votre espace de travail.

Si vous ne voyez pas de données affluer dans Microsoft Sentinel, consultez la documentation et les ressources de dépannage de votre source de données, vérifiez les détails de la configuration et vérifiez la connectivité. Pour plus d’informations, consultez Superviser l’intégrité de vos connecteurs de données.

Déconnecter votre connecteur

Si vous n’avez plus besoin des données de votre connecteur, déconnectez-le pour arrêter le flux de données.

Appliquez l'une des méthodes suivantes :

• Portail Azure : Dans la page de votre connecteur de données Microsoft Sentinel, sélectionnez Déconnexion.

• API : Utilisez l’API DISCONNECT pour envoyer un appel PUT avec un corps vide à l’URL suivante :

  https://management.azure.com /subscriptions/{{SUB}}/resourceGroups/{{RG}}/providers/Microsoft.OperationalInsights/workspaces/{{WS-NAME}}/providers/Microsoft.SecurityInsights/dataConnectors/{{Connector_Id}}/disconnect?api-version=2021-03-01-preview
  

Étapes suivantes

Si vous ne l’avez pas encore fait, partagez votre nouveau connecteur de données sans code avec la communauté Microsoft Sentinel ! Créez une solution pour votre connecteur de données et partagez-la sur le marketplace de Microsoft Sentinel.

Pour plus d'informations, consultez la rubrique

• À propos des solutions Microsoft Sentinel
• Informations de référence sur les modèles ARM de connecteur de données