.. _corelight-client:

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

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

.. contents::

Обзор

Этот инструмент предоставляет клиент командной строки для Corelight Sensor <https://www.corelight.com>, устройства Bro <https://www.bro.org>, разработанного с нуля создателями Bro для преобразования сетевого трафика в высокоточные данные для вашего аналитического конвейера. Используя клиент командной строки, вы можете удалённо настраивать и управлять Corelight Sensor через его полнофункциональный RESTful API. Расширенную версию этого обзора клиента см. в документации Corelight Sensor.

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

Лицензия

Этот клиент является открытым исходным кодом под лицензией BSD. Подробности см. в COPYING.

Установка

Клиенту командной строки требуется Python >= 3.4 с установленным модулем requests в качестве основной зависимости.

Самый простой способ установить клиент — через Python Package Index::

# pip3 install corelight-client

Либо вы можете установить последнюю версию с GitHub::

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

Если всё установлено правильно, --help выдаст вам сообщение об использовании::

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

Обратите внимание, что изначально --help ещё не покажет вам никаких дополнительных команд. Перейдите к следующему разделу, чтобы позволить клиенту подключиться к вашему устройству.

Доступ и аутентификация

Вам необходимо включить доступ к Corelight API через интерфейс конфигурации устройства. Также необходимо задать пароли для пользователей API admin (для неограниченного доступа) и monitor (для доступа только на чтение). Дополнительную информацию см. в документации Corelight Sensor.

Далее вам нужно сообщить corelight-client сетевой адрес вашего Corelight Sensor. У вас есть три варианта:

Добавить -b <address> в командную строку.
Создать файл конфигурации ~/.corelight-client.rc с содержимым device=<address>.
Задать переменную окружения CORELIGHT_DEVICE=<address>.

Если всё это настроено, corelight-client --help теперь запросит у вас имя пользователя и пароль, а затем покажет полный список команд, которые API устройства позволяет предложить клиенту. Если вы подтвердите сохранение учётных данных, клиент сохранит их в ~/.corelight-client/credentials для дальнейшего использования. Вы также можете указать информацию для аутентификации через Файл конфигурации_ или как Глобальные параметры_.

Использование

Клиент предоставляет функциональность API через набор команд формата <command> <subcommand> [options]. Добавив --help к любой команде, вы получите описание всей её функциональности и параметров.

Если в выводе --help параметр команды указан как имеющий тип file, клиент требует указать путь к файлу для отправки. Кроме того, вы можете добавить префикс file:// к значению любого параметра, чтобы прочитать его содержимое из файла вместо указания его непосредственно в командной строке.

(Примечание: вывод --help будет содержать список команд только если клиент может подключиться и аутентифицироваться на устройстве.)

.. _corelight-client-options:

Глобальные параметры

corelight-client поддерживает следующие глобальные параметры командной строки. Параметры --device и --fleet следует использовать взаимно исключающе друг от друга. Все остальные параметры применяются ко всем запросам:

--async Не ожидает завершения асинхронных команд перед выходом.

--device Указывает сетевой адрес устройства Corelight Sensor.

--fleet Указывает сетевой адрес Corelight Fleet Manager.

--uid Указывает UID Corelight Sensor, управляемого через указанный Corelight Fleet Manager.

--cache=<file> Задаёт пользовательский файл для кэширования метаданных Corelight Sensor.

--debug Включает отладочный вывод, показывающий HTTP-запросы и ответы.

--password Указывает пароль для аутентификации.

--mfa Указывает код двухфакторной верификации для аутентификации с указанным Corelight Fleet Manager. Используйте '-', чтобы запросить у пользователя.

--ssl-ca-cert Указывает файл, содержащий пользовательский SSL CA-сертификат для проверки подлинности устройства.

--ssl-no-verify-certificate Указывает клиенту принимать любой SSL-сертификат Corelight Sensor.

--ssl-no-verify-hostname Указывает клиенту принимать SSL-сертификат Corelight Sensor, даже если он не соответствует его имени хоста.

--socket Указывает клиенту использовать unix domain socket для отправки запросов.

--user Указывает имя пользователя для аутентификации.

--version Отображает версию corelight-client и завершает работу.

--ignore-meta Не отправлять информацию метаданных в вызов API сенсора, если она не указана в CLI.

--automation Включает набор поведения, удобного для автоматизации: тайм-ауты запросов, повторные попытки при временных сбоях, структурированные JSON-ошибки, выверенную таксономию кодов выхода и строгое неинтерактивное подтверждение. Подробности см. в разделе Автоматизация_ ниже. Также может быть включён установкой переменной окружения CORELIGHT_AUTOMATION=1.

--timeout Задаёт тайм-аут запроса в секундах, либо как одно число N (применяется и к подключению, и к чтению), либо как connect,read. По умолчанию 10,3600, когда включён --automation.

--retries Задаёт количество повторных попыток при временных сбоях (ошибки соединения и HTTP 429/502/503/504 для идемпотентных запросов). По умолчанию 3, когда включён --automation, иначе 0.

--retry-max-time Задаёт максимальное общее количество секунд, отводимое на повторные попытки. По умолчанию 120, когда включён --automation.

--error-format Задаёт формат вывода/ошибок: text или json. По умолчанию json, когда включён --automation, иначе text.

--assume-yes Выполняет операции, требующие подтверждения, без запроса (псевдоним: --confirm). Требуется для выполнения деструктивных операций при включённом --automation; в противном случае такие операции завершаются ошибкой о необходимости подтверждения.

Автоматизация

Передача --automation (или установка CORELIGHT_AUTOMATION=1) включает набор поведения, удобного для автоматизации, и активирует приведённую ниже таксономию кодов выхода. Она подразумевает --noblock и по умолчанию использует тайм-аут 10 с на подключение / 3600 с на чтение, 3 повторные попытки (с ограничением в 120 с суммарно) и вывод JSON как для успеха, так и для ошибок. Каждую часть можно переопределить собственным флагом.

corelight-client

Популярное