Marquer un équipement via l'API REST

Les balises peuvent vous aider à classer les appareils qui partagent une caractéristique commune parmi des centaines d'appareils potentiellement découverts sur votre réseau.

Vous souhaiterez peut-être étiqueter les appareils en fonction de leur rôle sur votre réseau, tels que les appareils qui constituent vos serveurs de développement et de production. Par exemple, si vous exécutez plusieurs instances AWS dans votre environnement, il est essentiel de les dimensionner en fonction de leur charge de travail. Une instance sous-dimensionnée peut entraîner des performances médiocres ; une instance surdimensionnée est inutilement coûteuse. Si vous balisez vos instances AWS, vous pouvez facilement configurer des groupes d'équipements par taille d'instance, puis créer un tableau de bord pour surveiller les indicateurs d'utilisation et de performance.

Dans ce guide, vous allez apprendre à créer une étiquette, à trouver l'équipement que vous souhaitez étiqueter, puis à ajouter l'étiquette à l'appareil. Un exemple de script est fourni à la fin, qui ajoute une étiquette d'équipement donnée à toutes les adresses IP lues à partir d'un fichier CSV.

Before you begin

  • Pour les capteurs et les machines virtuelles ECA, vous devez disposer d'une clé d'API valide pour apporter des modifications via l' API REST et suivre les procédures ci-dessous. (Voir Génération d'une clé d'API.)
  • Pour Reveal (x) 360, vous devez disposer d'informations d'identification d'API REST valides pour apporter des modifications via l' API REST et suivre les procédures ci-dessous. (Voir Création d'informations d'identification pour l'API REST.)

Création d'un tag

Si vous avez déjà un tag dans le système, vous pouvez ignorer cette étape. L'exemple de script au bas de ce guide vérifie la présence d'une balise et n'en crée une nouvelle que si nécessaire.

  1. Dans un navigateur, accédez à l'explorateur d'API REST.
    L'URL est le nom d'hôte ou l'adresse IP de votre sonde ou console, suivi de /api/v1/explore/. Par exemple, si votre nom d'hôte est seattle-eda, l'URL est https://seattle-eda/api/v1/explore/.
  2. Cliquez Entrez la clé API puis collez ou saisissez votre clé API dans Clé API champ.
  3. Cliquez Autoriser puis cliquez sur Fermer.
  4. Cliquez Balise puis cliquez sur Publication/tags.
  5. Cliquez Essayez-le.
    Le schéma JSON est automatiquement ajouté au corps zone de texte des paramètres.
  6. Dans le name champ, remplacez string avec le nouveau nom de tag.
  7. Cliquez Envoyer la demande pour créer le tag.

Récupérez les appareils qui correspondent à vos critères

Au cours de cette étape, vous allez rechercher les appareils que vous souhaitez étiqueter et noter leur identifiant. Vous devez disposer de l'identifiant de l'équipement avant de pouvoir étiqueter un appareil.

  1. Faites défiler la page vers le haut et cliquez sur Appareil pour afficher le fonctionnement de l'équipement.
  2. Cliquez POST /appareils/recherche.
  3. Cliquez Essayez-le.
    Le schéma JSON est automatiquement ajouté à la zone de texte des paramètres du corps.
  4. Dans le corps de la zone de texte, saisissez les critères de recherche qui sélectionnent les appareils.
    Les critères de recherche suivants renvoient un équipement dont l'adresse IP est 10.10.10.200 :
    {
      "filter": {
        "field": "ipaddr",
        "operand": "10.10.10.200",
        "operator": "="
      }
    }

    Pour plus d'informations sur les filtres de recherche d'équipements, voir Valeurs d'opérande pour la recherche d'équipements.

  5. Cliquez Envoyer une demande.
    Dans le Réponse du serveur section, la Organisme de réponse affiche des informations sur chaque équipement correspondant à vos critères de recherche, y compris l'identifiant de l'équipement.

Attribuer le tag à un équipement

Au cours de cette étape, vous allez attribuer une étiquette à un équipement en fonction de l'identifiant de l'équipement que vous avez trouvé à l'étape précédente.

  1. Faites défiler la page vers le bas et cliquez sur Tag pour afficher les opérations relatives aux balises.
  2. Cliquez POST /tags/ {id} /appareils/ {child id}.
  3. Cliquez Essayez-le.
  4. Dans le identifiant d'enfant dans ce champ, saisissez l'identifiant de l'équipement que vous souhaitez étiqueter.
  5. Dans le identifiant dans ce champ, saisissez l'ID du tag que vous souhaitez attribuer.
  6. Cliquez Envoyer une demande pour attribuer le tag à l'équipement.
Conseil :Après avoir cliqué Envoyer une demande, vous pouvez cliquer sur les onglets pour afficher les scripts relatifs à l'opération dans Curl, Python 2.7 ou Ruby.

Récupérez et exécutez l'exemple de script Python

Le référentiel GitHub ExtraHop contient un exemple de script Python qui crée une étiquette d'équipement, puis l'attribue à tous les appareils dont les adresses IP sont spécifiées dans un fichier CSV. Le script crée une nouvelle balise uniquement si la balise spécifiée n'existe pas déjà.

  1. Accédez au Référentiel GitHub d'exemples de code ExtraHop et téléchargez le tag_device/tag_device.py fichier sur votre machine locale.
  2. Dans un éditeur de texte, ouvrez le tag_device.py archivez et remplacez les variables de configuration suivantes par des informations provenant de votre environnement :
    • Pour les capteurs et les machines virtuelles ECA, spécifiez les variables de configuration suivantes :

      HÔTE: L'adresse IP ou le nom d'hôte de la sonde ou de la machine virtuelle ECA.

      CLÉ_API: La clé API.

      ÉTIQUETTE: Le nom de la balise

      LISTE_D'APPAREILS: Le fichier qui contient la liste des adresses IP

    • Pour Reveal (x) 360, spécifiez les variables de configuration suivantes :

      HÔTE: Le nom d'hôte de l'API Reveal (x) 360. Ce nom d'hôte est affiché sur la page d'accès à l'API Reveal (x) 360 sous API Endpoint. Le nom d'hôte n'inclut pas /oauth2/token.

      IDENTIFIANT: L'ID des informations d'identification de l'API REST Reveal (x) 360.

      SECRET: Le secret des informations d'identification de l'API REST Reveal (x) 360.

      ÉTIQUETTE: Le nom de la balise

      LISTE_D'APPAREILS: Le fichier qui contient la liste des adresses IP

  3. Exécutez la commande suivante :
    python3 tag_device.py
    Remarque :Si le script renvoie un message d'erreur indiquant que la vérification du certificat SSL a échoué, assurez-vous que un certificat fiable a été ajouté à votre sonde ou à votre console. Vous pouvez également ajouter le verify=False option permettant de contourner la vérification des certificats. Cependant, cette méthode n'est pas sûre et n'est pas recommandée. Le code suivant envoie une requête HTTP GET sans vérification du certificat :
    requests.get(url, headers=headers, verify=False)
Last modified 2024-03-20