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

.. contents::

Aperçu

Cet outil fournit un client en ligne de commande pour le capteur Corelight <https://www.corelight.com>, un appareil Bro <https://www.bro.org> conçu de A à Z par les créateurs de Bro pour transformer le trafic réseau en données haute fidélité pour votre pipeline d'analyse. Grâce au 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 cet aperçu du client.

:Version: |version| :Page d'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.

Le moyen le plus simple d'installer le client est via le Python Package Index::

# pip3 install corelight-client

Vous pouvez également installer la dernière version depuis GitHub::

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

Si tout est installé correctement, --help vous affichera 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 pas encore d'autres commandes à utiliser. Passez à la section suivante pour laisser le client 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 (accès illimité) et monitor (accès en lecture seule). Consultez la documentation du capteur Corelight pour plus d'informations.

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

• Ajoutez -b <address> à la ligne de commande.

• Créez un fichier de configuration ~/.corelight-client.rc avec le contenu device=<address>.

• Définissez la variable d'environnement CORELIGHT_DEVICE=<address>.

Une fois cela configuré, corelight-client --help vous demandera un nom d'utilisateur et un mot de passe, puis affichera la liste complète des commandes que l'API de l'appareil permet au client de proposer. Si vous confirmez l'enregistrement des identifiants, le client les stockera dans ~/.corelight-client/credentials pour une réutilisation ultérieure. Vous pouvez également spécifier les informations d'authentification via le Fichier de configuration_ ou les 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 plutôt que de la fournir directement sur la ligne de commande.

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

.. _corelight-client-options:

Options globales

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

--async N'attend pas la fin des commandes asynchrones avant de se terminer.

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

--fleet Spécifie l'adresse réseau d'un gestionnaire de flotte Corelight.

--uid Spécifie l'UID d'un capteur Corelight géré via le gestionnaire de flotte Corelight 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 auprès du gestionnaire de flotte Corelight spécifié. Utilisez '-' pour demander à l'utilisateur.

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

--ssl-no-verify-certificate Demande au client d'accepter tout 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 puis se termine.

--ignore-meta N'envoie pas les informations de métadonnées à l'appel API du capteur, sauf si elles sont spécifiées en ligne de commande.

.. _corelight-client-config:

Fichier de configuration

Le corelight-client recherche un fichier de configuration ~/.corelight-client.rc. Le fichier doit être composé de lignes <key>=<value>. Les commentaires commençant par # sont ignorés. corelight-client prend en charge les clés suivantes :

device L'adresse réseau d'un capteur Corelight.

fleet L'adresse réseau d'un gestionnaire de flotte Corelight.

uid L'UID d'un capteur Corelight géré via le gestionnaire de flotte Corelight spécifié.

user Le nom d'utilisateur pour l'authentification.

password Le mot de passe pour l'authentification.

mfa Le code de vérification 2FA pour l'authentification auprès d'un gestionnaire de flotte Corelight. Utilisez '-' pour demander à l'utilisateur.

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

ssl-no-verify-certificate Si défini sur false, le client acceptera n'importe quel certificat SSL d'un capteur Corelight.

ssl-no-verify-hostname Si défini sur false, le client acceptera le certificat SSL du capteur Corelight même s'il ne correspond pas à son nom d'hôte.

socket Un socket de domaine Unix à utiliser pour envoyer les requêtes.