.. _corelight-client:

.. Version number is filled in automatically. .. |version| replace:: 1.5.22

==================================== Corelight Sensor Command Line Client

.. contents::

Überblick

Dieses Tool stellt einen Kommandozeilen-Client für den Corelight Sensor <https://www.corelight.com>_ bereit, ein Bro <https://www.bro.org>_-Appliance, die von Grund auf von den Entwicklern von Bro entwickelt wurde, um Netzwerkverkehr in hochwertige Daten für Ihre Analyse-Pipeline zu transformieren. Mit dem Kommandozeilen-Client können Sie einen Corelight Sensor remote über seine umfassende RESTful API konfigurieren und steuern. Eine erweiterte Version dieser Client-Übersicht finden Sie in der Corelight Sensor-Dokumentation.

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

Lizenz

Dieser Client ist Open Source unter einer BSD-Lizenz. Details finden Sie in COPYING.

Installation

Der Kommandozeilen-Client benötigt Python >= 3.4 mit dem requests-Modul als Hauptabhängigkeit.

Der einfachste Weg, den Client zu installieren, ist über den Python Package Index::

# pip3 install corelight-client

Alternativ können Sie die neueste Version von GitHub installieren::

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

Wenn alles korrekt installiert ist, gibt --help eine Nutzungsanweisung aus::

# 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]
[...]

Beachten Sie, dass --help anfangs noch keine weiteren Befehle anzeigt. Fahren Sie mit dem nächsten Abschnitt fort, damit der Client sich mit Ihrem Gerät verbinden kann.

Zugriff und Authentifizierung

Sie müssen den Zugriff auf die Corelight API über die Konfigurationsoberfläche des Geräts aktivieren. Außerdem müssen Sie Passwörter für die API-Benutzer admin (für uneingeschränkten Zugriff) und monitor (für schreibgeschützten Zugriff) festlegen. Weitere Informationen finden Sie in der Corelight Sensor-Dokumentation.

Als Nächstes müssen Sie dem corelight-client die Netzwerkadresse Ihres Corelight Sensors mitteilen. Dafür haben Sie drei Möglichkeiten:

• Fügen Sie -b <address> zur Kommandozeile hinzu.

• Erstellen Sie eine Konfigurationsdatei ~/.corelight-client.rc mit dem Inhalt device=<address>.

• Setzen Sie die Umgebungsvariable CORELIGHT_DEVICE=<address>.

Wenn alles eingerichtet ist, fragt corelight-client --help nun nach einem Benutzernamen und Passwort und zeigt dann die vollständige Liste der Befehle an, die die Geräte-API dem Client ermöglicht. Wenn Sie das Speichern der Anmeldedaten bestätigen, speichert der Client sie in ~/.corelight-client/credentials zur späteren Wiederverwendung. Sie können Authentifizierungsinformationen auch über die Konfigurationsdatei_ oder als Globale Optionen_ angeben.

Verwendung

Der Client bietet die Funktionalität der API über eine Reihe von Befehlen im Format <command> <subcommand> [options] an. Durch Hinzufügen von --help zu einem beliebigen Befehl erhalten Sie eine Beschreibung seiner gesamten Funktionalität und Optionen.

Wenn die --help-Ausgabe eine Option eines Befehls als vom Typ file auflistet, müssen Sie den Pfad zu einer zu sendenden Datei angeben. Darüber hinaus können Sie dem Wert jeder Option file:// voranstellen, um seinen Inhalt aus einer Datei zu lesen, anstatt ihn direkt auf der Kommandozeile anzugeben.

(Hinweis: Die --help-Ausgabe enthält die Liste der Befehle nur, wenn der Client sich mit dem Gerät verbinden und authentifizieren kann.)

.. _corelight-client-options:

Globale Optionen

Der corelight-client unterstützt die folgenden globalen Kommandozeilenoptionen. Die Optionen --device und --fleet sollten sich gegenseitig ausschließend verwendet werden. Alle anderen Optionen gelten für alle Anfragen:

--async Wartet nicht auf die Beendigung asynchroner Befehle, bevor es beendet wird.

--device Gibt die Netzwerkadresse eines Corelight Sensor-Geräts an.

--fleet Gibt die Netzwerkadresse eines Corelight Fleet Managers an.

--uid Gibt die UID eines Corelight Sensors an, der über den angegebenen Corelight Fleet Manager verwaltet wird.

--cache=<file> Legt eine benutzerdefinierte Datei zum Zwischenspeichern von Corelight Sensor-Metadaten fest.

--debug Aktiviert Debug-Ausgaben, die HTTP-Anfragen und -Antworten anzeigen.

--password Gibt das Passwort für die Authentifizierung an.

--mfa Gibt den 2FA-Verifizierungscode für die Authentifizierung mit dem angegebenen Corelight Fleet Manager an. Verwenden Sie '-', um den Benutzer zu fragen.

--ssl-ca-cert Gibt eine Datei an, die ein benutzerdefiniertes SSL-CA-Zertifikat zur Validierung der Authentizität des Geräts enthält.

--ssl-no-verify-certificate Weist den Client an, jedes SSL-Zertifikat des Corelight Sensors zu akzeptieren.

--ssl-no-verify-hostname Weist den Client an, das SSL-Zertifikat des Corelight Sensors zu akzeptieren, auch wenn es nicht mit seinem Hostnamen übereinstimmt.

--socket Weist den Client an, einen Unix-Domain-Socket zum Senden von Anfragen zu verwenden.

--user Gibt den Benutzernamen für die Authentifizierung an.

--version Zeigt die Version des corelight-client an und beendet das Programm.

--ignore-meta Sendet keine Metadaten-Informationen an den Sensor-API-Aufruf, es sei denn, sie werden auf der Kommandozeile angegeben.

--automation Aktiviert ein Bündel automatisierungsfreundlicher Verhaltensweisen: Anfrage-Timeouts, Wiederholungen bei vorübergehenden Fehlern, strukturierte JSON-Fehler, die kuratierte Exit-Code-Taxonomie und strikte nicht-interaktive Bestätigung. Weitere Details finden Sie unter Automatisierung_ weiter unten. Kann auch durch Setzen der Umgebungsvariable CORELIGHT_AUTOMATION=1 aktiviert werden.

--timeout Legt das Anfrage-Timeout in Sekunden fest, entweder als einzelne Zahl N (angewendet auf sowohl Verbindungsaufbau als auch Lesen) oder als connect,read. Standardmäßig 10,3600, wenn --automation aktiviert ist.

--retries Legt die Anzahl der Wiederholungsversuche bei vorübergehenden Fehlern fest (Verbindungsfehler und HTTP 429/502/503/504 bei idempotenten Anfragen). Standardmäßig 3, wenn --automation aktiviert ist, andernfalls 0.

--retry-max-time Legt die maximale Gesamtzahl an Sekunden fest, die für Wiederholungen aufgewendet werden soll. Standardmäßig 120, wenn --automation aktiviert ist.

--error-format Legt das Ausgabe-/Fehlerformat auf text oder json fest. Standardmäßig json, wenn --automation aktiviert ist, andernfalls text.

--assume-yes Fährt mit bestätigungsgeschützten Vorgängen fort, ohne nachzufragen (Alias: --confirm). Erforderlich, um destruktive Vorgänge auszuführen, während --automation aktiviert ist; andernfalls schlagen diese Vorgänge mit einem Fehler "Bestätigung erforderlich" fehl.

Automatisierung