.. _corelight-client:

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

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

.. contents::

Visão geral

Esta ferramenta fornece um cliente de linha de comando para o Corelight Sensor <https://www.corelight.com>, um appliance Bro <https://www.bro.org> projetado do zero pelos criadores do Bro para transformar tráfego de rede em dados de alta fidelidade para o seu pipeline de análise. Usando o cliente de linha de comando, você pode configurar e controlar um Corelight Sensor remotamente através de sua abrangente API RESTful. Consulte a documentação do Corelight Sensor para uma versão estendida desta visão geral do cliente.

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

Licença

Este cliente é de código aberto sob uma licença BSD. Consulte COPYING para detalhes.

Instalação

O cliente de linha de comando precisa de Python >= 3.4 com o módulo requests instalado como sua principal dependência.

A maneira mais fácil de instalar o cliente é através do Python Package Index::

# pip3 install corelight-client

Alternativamente, você pode instalar a versão mais recente do GitHub::

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

Se tudo estiver instalado corretamente, --help fornecerá uma mensagem de uso::

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

Observe que, inicialmente, --help ainda não mostrará nenhum outro comando para usar. Prossiga para a próxima seção para permitir que o cliente se conecte ao seu dispositivo.

Acesso e autenticação

Você precisa habilitar o acesso à API do Corelight através da interface de configuração do dispositivo. Você também precisa definir senhas para os usuários da API admin (para acesso ilimitado) e monitor (para acesso somente leitura). Consulte a documentação do Corelight Sensor para mais informações.

Em seguida, você precisa informar ao corelight-client o endereço de rede do seu Corelight Sensor. Você tem três opções para fazer isso:

Adicionar -b <address> à linha de comando.
Criar um arquivo de configuração ~/.corelight-client.rc com o conteúdo device=<address>.
Definir a variável de ambiente CORELIGHT_DEVICE=<address>.

Se tudo estiver configurado, corelight-client --help agora solicitará um nome de usuário e senha, e então mostrará a lista completa de comandos que a API do dispositivo permite ao cliente oferecer. Se você confirmar o salvamento das credenciais, o cliente as armazenará em ~/.corelight-client/credentials para reutilização futura. Você também pode especificar informações de autenticação através do Configuration File_ ou como Global Options_.

Uso

O cliente oferece a funcionalidade da API através de um conjunto de comandos no formato <command> <subcommand> [options]. Ao adicionar --help a qualquer comando, você obtém uma descrição de toda a sua funcionalidade e opções.

Se a saída de --help listar a opção de um comando como sendo do tipo file, o cliente exige que você especifique o caminho para um arquivo a enviar. Além disso, você pode prefixar o valor de qualquer opção com file:// para ler seu conteúdo de um arquivo em vez de fornecê-lo na própria linha de comando.

(Nota: A saída de --help conterá a lista de comandos somente se o cliente puder se conectar e autenticar no dispositivo.)

.. _corelight-client-options:

Opções globais

O corelight-client suporta as seguintes opções globais de linha de comando. As opções --device e --fleet devem ser usadas mutuamente exclusivas entre si. Todas as outras opções se aplicam a todas as requisições:

--async Não aguarda a conclusão de comandos assíncronos antes de sair.

--device Especifica o endereço de rede de um dispositivo Corelight Sensor.

--fleet Especifica o endereço de rede de um Corelight Fleet Manager.

--uid Especifica o UID de um Corelight Sensor gerenciado através do Corelight Fleet Manager especificado.

--cache=<file> Define um arquivo personalizado para armazenar em cache os metadados do Corelight Sensor.

--debug Habilita a saída de depuração mostrando requisições e respostas HTTP.

--password Especifica a senha para autenticação.

--mfa Especifica o código de verificação 2FA para autenticação com o Corelight Fleet Manager especificado. Use '-' para perguntar ao usuário.

--ssl-ca-cert Especifica um arquivo contendo um certificado SSL CA personalizado para validar a autenticidade do dispositivo.

--ssl-no-verify-certificate Instrui o cliente a aceitar qualquer certificado SSL do Corelight Sensor.

--ssl-no-verify-hostname Instrui o cliente a aceitar o certificado SSL do Corelight Sensor mesmo que ele não corresponda ao seu hostname.

--socket Instrui o cliente a usar um unix domain socket para enviar requisições.

--user Especifica o nome de usuário para autenticação.

--version Exibe a versão do corelight-client e sai.

--ignore-meta Não envia informações de metadados para a chamada da API do sensor, a menos que seja especificado na CLI.

--automation Habilita um conjunto de comportamentos amigáveis à automação: timeouts de requisição, novas tentativas em falhas transitórias, erros JSON estruturados, a taxonomia curada de códigos de saída e confirmação estritamente não interativa. Consulte Automation_ abaixo para detalhes. Também pode ser habilitado definindo a variável de ambiente CORELIGHT_AUTOMATION=1.

--timeout Define o timeout da requisição em segundos, seja como um único número N (aplicado tanto à conexão quanto à leitura) ou como connect,read. O padrão é 10,3600 quando --automation está habilitado.

--retries Define o número de novas tentativas para falhas transitórias (erros de conexão e HTTP 429/502/503/504 para requisições idempotentes). O padrão é 3 quando --automation está habilitado, 0 caso contrário.

--retry-max-time Define o número máximo total de segundos a gastar em novas tentativas. O padrão é 120 quando --automation está habilitado.

--error-format Define o formato de saída/erro como text ou json. O padrão é json quando --automation está habilitado, text caso contrário.

--assume-yes Prossegue através de operações protegidas por confirmação sem solicitar (alias: --confirm). Necessário para realizar operações destrutivas enquanto --automation está habilitado; caso contrário, essas operações falham com um erro de confirmação obrigatória.

Automação

Passar --automation (ou definir CORELIGHT_AUTOMATION=1) habilita um conjunto de comportamentos amigáveis à automação e ativa a taxonomia de códigos de saída abaixo. Isso implica --noblock e usa como padrão um timeout de 10s para conexão / 3600s para leitura, 3 novas tentativas (limitadas a 120s no total) e saída JSON tanto para sucesso quanto para erro. Cada parte pode ser substituída por sua própria flag.

corelight-client

Mais Populares