.. _corelight-client:

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

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

.. contents::

Panoramica

Questo strumento fornisce un client a riga di comando per il Corelight Sensor <https://www.corelight.com>, un'appliance Bro <https://www.bro.org> progettata da zero dai creatori di Bro per trasformare il traffico di rete in dati ad alta fedeltà per la tua pipeline di analisi. Utilizzando il client a riga di comando, puoi configurare e controllare un Corelight Sensor da remoto attraverso la sua completa API RESTful. Consulta la documentazione del Corelight Sensor per una versione estesa di questa panoramica del client.

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

Licenza

Questo client è open-source sotto licenza BSD. Vedi COPYING per i dettagli.

Installazione

Il client a riga di comando richiede Python >= 3.4 con il modulo requests installato come dipendenza principale.

Il modo più semplice per installare il client è attraverso il Python Package Index::

# pip3 install corelight-client

In alternativa, puoi installare l'ultima versione da GitHub::

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

Se tutto è installato correttamente, --help ti mostrerà un messaggio di utilizzo::

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

Nota che inizialmente, --help non ti mostrerà ancora ulteriori comandi da utilizzare. Procedi alla sezione successiva per consentire al client di connettersi al tuo dispositivo.

Accesso e autenticazione

Devi abilitare l'accesso all'API di Corelight attraverso l'interfaccia di configurazione del dispositivo. Devi anche impostare le password per gli utenti API admin (per accesso illimitato) e monitor (per accesso in sola lettura). Consulta la documentazione del Corelight Sensor per maggiori informazioni.

Successivamente, devi indicare al corelight-client l'indirizzo di rete del tuo Corelight Sensor. Hai tre possibilità per farlo:

Aggiungi -b <address> alla riga di comando.
Crea un file di configurazione ~/.corelight-client.rc con il contenuto device=<address>.
Imposta la variabile d'ambiente CORELIGHT_DEVICE=<address>.

Se tutto è configurato, corelight-client --help ti chiederà ora un nome utente e una password, e poi ti mostrerà l'elenco completo dei comandi che l'API del dispositivo consente al client di offrire. Se confermi il salvataggio delle credenziali, il client le memorizzerà in ~/.corelight-client/credentials per riutilizzarle in futuro. Puoi anche specificare le informazioni di autenticazione attraverso il Configuration File_ o come Global Options_.

Utilizzo

Il client offre la funzionalità dell'API attraverso un insieme di comandi del formato <command> <subcommand> [options]. Aggiungendo --help a qualsiasi comando, ottieni una descrizione di tutte le sue funzionalità e opzioni.

Se l'output di --help elenca l'opzione di un comando come di tipo file, il client richiede di specificare il percorso di un file da inviare. Inoltre, puoi anteporre file:// al valore di qualsiasi opzione per leggerne il contenuto da un file invece di fornirlo direttamente sulla riga di comando.

(Nota: l'output di --help conterrà l'elenco dei comandi solo se il client riesce a connettersi, e ad autenticarsi, al dispositivo.)

.. _corelight-client-options:

Opzioni globali

Il corelight-client supporta le seguenti opzioni globali da riga di comando. Le opzioni --device e --fleet dovrebbero essere usate in modo mutuamente esclusivo l'una dall'altra. Tutte le altre opzioni si applicano a tutte le richieste:

--async Non attende il completamento dei comandi asincroni prima di uscire.

--device Specifica l'indirizzo di rete di un dispositivo Corelight Sensor.

--fleet Specifica l'indirizzo di rete di un Corelight Fleet Manager.

--uid Specifica l'UID di un Corelight Sensor gestito attraverso il Corelight Fleet Manager specificato.

--cache=<file> Imposta un file personalizzato per la cache dei metadati del Corelight Sensor.

--debug Abilita l'output di debug che mostra le richieste e le risposte HTTP.

--password Specifica la password per l'autenticazione.

--mfa Specifica il codice di verifica 2FA per l'autenticazione con il Corelight Fleet Manager specificato. Usa '-' per chiedere all'utente.

--ssl-ca-cert Specifica un file contenente un certificato CA SSL personalizzato per validare l'autenticità del dispositivo.

--ssl-no-verify-certificate Istruisce il client ad accettare qualsiasi certificato SSL del Corelight Sensor.

--ssl-no-verify-hostname Istruisce il client ad accettare il certificato SSL del Corelight Sensor anche se non corrisponde al suo hostname.

--socket Istruisce il client a utilizzare un unix domain socket per inviare le richieste.

--user Specifica il nome utente per l'autenticazione.

--version Mostra la versione del corelight-client ed esce.

--ignore-meta Non inviare informazioni sui metadati alla chiamata API del sensore, a meno che non sia specificato sulla CLI.

--automation Abilita un insieme di comportamenti adatti all'automazione: timeout delle richieste, tentativi in caso di errori transitori, errori JSON strutturati, la tassonomia curata dei codici di uscita e la conferma rigorosa non interattiva. Vedi Automation_ di seguito per i dettagli. Può anche essere abilitato impostando la variabile d'ambiente CORELIGHT_AUTOMATION=1.

--timeout Imposta il timeout della richiesta in secondi, sia come singolo numero N (applicato sia alla connessione che alla lettura) sia come connect,read. Il valore predefinito è 10,3600 quando --automation è abilitato.

--retries Imposta il numero di tentativi da effettuare per errori transitori (errori di connessione e HTTP 429/502/503/504 per richieste idempotenti). Il valore predefinito è 3 quando --automation è abilitato, 0 altrimenti.

--retry-max-time Imposta il numero massimo totale di secondi da dedicare ai tentativi. Il valore predefinito è 120 quando --automation è abilitato.

--error-format Imposta il formato di output/errore su text o json. Il valore predefinito è json quando --automation è abilitato, text altrimenti.

--assume-yes Procede attraverso le operazioni soggette a conferma senza chiedere (alias: --confirm). Necessario per eseguire operazioni distruttive mentre --automation è abilitato; altrimenti tali operazioni falliscono con un errore di conferma richiesta.

Automazione

Passare --automation (o impostare CORELIGHT_AUTOMATION=1) abilita un insieme di comportamenti adatti all'automazione e attiva la tassonomia dei codici di uscita riportata di seguito. Implica --noblock e imposta come valori predefiniti un timeout di 10s per la connessione / 3600s per la lettura, 3 tentativi (limitati a 120s totali) e output JSON sia per il successo che per l'errore. Ogni parte può essere sovrascritta con il proprio flag.

corelight-client

Più Popolari