.. _corelight-client:

.. Le numéro de version est renseigné automatiquement. .. |version| replace:: 1.5.22

==================================== Client en ligne de commande pour capteur Corelight

.. contents::

Présentation

Cet outil fournit un client en ligne de commande pour le capteur Corelight <https://www.corelight.com>, une appliance Bro <https://www.bro.org> conçue de A à Z par les créateurs de Bro pour transformer le trafic réseau en données de haute fidélité pour votre pipeline d'analyse. À l'aide du client en ligne de commande, vous pouvez configurer et contrôler un capteur Corelight à distance via son API RESTful complète. Consultez la documentation du capteur Corelight pour une version étendue de cette présentation du client.

:Version: |version| :Accueil: http://www.corelight.com :GitHub: https://github.com/corelight/corelight-client :Auteur: Corelight, Inc. <https://www.corelight.com>_ [email protected]

Licence

Ce client est open-source sous licence BSD. Voir COPYING pour plus de détails.

Installation

Le client en ligne de commande nécessite Python >= 3.4 avec le module requests installé comme dépendance principale.

La façon la plus simple d'installer le client est via le Python Package Index ::

# pip3 install corelight-client

Alternativement, vous pouvez installer la dernière version depuis GitHub ::

# git clone https://github.com/corelight/corelight-client
# cd corelight-client
# pip3 install setuptools
# python3 setup.py install

Si tout est correctement installé, --help vous donnera un message d'utilisation ::

# corelight-client --help
Usage: corelight-client [<global options>] <command> <subcommand> [<options>]
          [--ssl-ca-cert SSL_CA_CERT] [--ssl-no-verify-certificate]
          [--ssl-no-verify-hostname] [--cache CACHE]
[...]

Notez qu'au départ, --help ne vous montrera encore aucune autre commande à utiliser. Passez à la section suivante pour permettre au client de se connecter à votre appareil.

Accès et authentification

Vous devez activer l'accès à l'API Corelight via l'interface de configuration de l'appareil. Vous devez également définir des mots de passe pour les utilisateurs de l'API admin (pour un accès illimité) et monitor (pour un accès en lecture seule). Consultez la documentation du capteur Corelight pour plus d'informations.

Ensuite, vous devez indiquer au corelight-client l'adresse réseau de votre capteur Corelight. Vous avez trois choix pour cela :

Ajouter -b <address> à la ligne de commande.
Créer un fichier de configuration ~/.corelight-client.rc avec le contenu device=<address>.
Définir la variable d'environnement CORELIGHT_DEVICE=<address>.

Si tout est configuré, corelight-client --help vous demandera maintenant un nom d'utilisateur et un mot de passe, puis vous montrera la liste complète des commandes que l'API de l'appareil permet au client d'offrir. Si vous confirmez l'enregistrement des identifiants, le client les stockera dans ~/.corelight-client/credentials pour une réutilisation future. Vous pouvez également spécifier les informations d'authentification via le Fichier de configuration_ ou comme Options globales_.

Utilisation

Le client offre les fonctionnalités de l'API via un ensemble de commandes au format <command> <subcommand> [options]. En ajoutant --help à n'importe quelle commande, vous obtenez une description de toutes ses fonctionnalités et options.

Si la sortie de --help indique qu'une option d'une commande est de type file, le client vous demande de spécifier le chemin d'un fichier à envoyer. De plus, vous pouvez préfixer la valeur de n'importe quelle option avec file:// pour lire son contenu depuis un fichier au lieu de le donner sur la ligne de commande elle-même.

(Remarque : la sortie de --help ne contiendra la liste des commandes que si le client peut se connecter, et s'authentifier, à l'appareil.)

.. _corelight-client-options:

Options globales

Le corelight-client prend en charge les options globales de ligne de commande suivantes. Les options --device et --fleet doivent être utilisées mutuellement exclusivement l'une de l'autre. Toutes les autres options s'appliquent à toutes les requêtes :

--async N'attend pas que les commandes asynchrones se terminent avant de quitter.

--device Spécifie l'adresse réseau d'un appareil capteur Corelight.

--fleet Spécifie l'adresse réseau d'un Corelight Fleet Manager.

--uid Spécifie l'UID d'un capteur Corelight géré via le Corelight Fleet Manager spécifié.

--cache=<file> Définit un fichier personnalisé pour la mise en cache des métadonnées du capteur Corelight.

--debug Active la sortie de débogage affichant les requêtes et réponses HTTP.

--password Spécifie le mot de passe pour l'authentification.

--mfa Spécifie le code de vérification 2FA pour l'authentification avec le Corelight Fleet Manager spécifié. Utilisez '-' pour demander à l'utilisateur.

--ssl-ca-cert Spécifie un fichier contenant un certificat CA SSL personnalisé pour valider l'authenticité de l'appareil.

--ssl-no-verify-certificate Demande au client d'accepter n'importe quel certificat SSL du capteur Corelight.

--ssl-no-verify-hostname Demande au client d'accepter le certificat SSL du capteur Corelight même s'il ne correspond pas à son nom d'hôte.

--socket Demande au client d'utiliser un socket de domaine unix pour envoyer les requêtes.

--user Spécifie le nom d'utilisateur pour l'authentification.

--version Affiche la version du corelight-client et quitte.

--ignore-meta N'envoie pas d'informations de métadonnées à l'appel API du capteur, sauf si elles sont spécifiées sur la CLI.

--automation Active un ensemble de comportements adaptés à l'automatisation : délais d'attente des requêtes, nouvelles tentatives en cas de défaillance transitoire, erreurs JSON structurées, la taxonomie curatée des codes de sortie, et confirmation non interactive stricte. Voir Automatisation_ ci-dessous pour plus de détails. Peut également être activé en définissant la variable d'environnement CORELIGHT_AUTOMATION=1.

--timeout Définit le délai d'attente des requêtes en secondes, soit sous forme d'un seul nombre N (appliqué à la fois à la connexion et à la lecture) soit sous forme connect,read. Par défaut 10,3600 lorsque --automation est activé.

--retries Définit le nombre de nouvelles tentatives à effectuer pour les défaillances transitoires (erreurs de connexion, et HTTP 429/502/503/504 pour les requêtes idempotentes). Par défaut 3 lorsque --automation est activé, 0 sinon.

--retry-max-time Définit le nombre total maximal de secondes à consacrer aux nouvelles tentatives. Par défaut 120 lorsque --automation est activé.

--error-format Définit le format de sortie/d'erreur sur text ou json. Par défaut json lorsque --automation est activé, text sinon.

--assume-yes Poursuit les opérations soumises à confirmation sans demander (alias : --confirm). Requis pour effectuer des opérations destructrices lorsque --automation est activé ; sinon ces opérations échouent avec une erreur de confirmation requise.

corelight-client

Populaires