.. _corelight-client:

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

==================================== Corelight Sensor 命令行客户端

.. contents::

概述

此工具为 Corelight Sensor <https://www.corelight.com>_ 提供了一个命令行客户端，该设备是由 Bro 的创建者从零开始设计的 Bro <https://www.bro.org>_ 设备，旨在将网络流量转化为高保真数据，以供您的分析管道使用。 使用该命令行客户端，您可以通过其全面的 RESTful API 远程配置和控制 Corelight Sensor。有关此客户端概述的扩展版本，请参阅 Corelight Sensor 文档。

:版本: |version| :主页: http://www.corelight.com :GitHub: https://github.com/corelight/corelight-client :作者: Corelight, Inc. <https://www.corelight.com>_ [email protected]

许可证

此客户端是基于 BSD 许可证的开源软件。详情请参阅 COPYING。

安装

该命令行客户端需要 Python >= 3.4，并安装 requests 模块作为其主要依赖项。

安装客户端最简单的方法是通过 Python 包 索引::

# 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 中以供将来重用。您也可以通过 配置文件_ 或 全局选项_ 指定认证信息。

用法

客户端通过一组格式为 <command> <subcommand> [options] 的命令提供 API 的功能。 通过向任何命令添加 --help，您可以获得其所有功能和 选项的描述。

如果 --help 输出将某个命令的选项列为 file 类型， 则客户端要求您指定要发送的文件的路径。此外，您可以在任何选项的值前加上 file:// 以从文件读取其内容，而不是在 命令行本身中给出。

（注意：只有当客户端能够连接并认证到设备时，--help 输出才会包含命令列表。）

.. _corelight-client-options:

全局选项

corelight-client 支持以下全局命令行 选项。--device 和 --fleet 选项应互斥使用。 所有其他选项适用于所有请求：

--async 在退出前不等待异步命令完成。

--device 指定 Corelight Sensor 设备的网络地址。

--fleet 指定 Corelight Fleet Manager 的网络地址。

--uid 指定通过指定的 Corelight Fleet Manager 管理的 Corelight Sensor 的 UID。

--cache=<file> 设置用于缓存 Corelight Sensor 元数据的自定义文件。

--debug 启用显示 HTTP 请求和回复的调试输出。

--password 指定用于认证的密码。

--mfa 指定用于通过指定的 Corelight Fleet Manager 进行认证的 2FA 验证码。使用 '-' 询问用户。

--ssl-ca-cert 指定包含用于验证设备真实性的自定义 SSL CA 证书的文件。

--ssl-no-verify-certificate 指示客户端接受任何 Corelight Sensor SSL 证书。

--ssl-no-verify-hostname 指示客户端接受 Corelight Sensor 的 SSL 证书，即使它与主机名不匹配。

--socket 指示客户端使用 unix 域套接字发送请求。

--user 指定用于认证的用户名。

--version 显示 corelight-client 的版本并退出。

--ignore-meta 除非在 CLI 上指定，否则不向 sensor API 调用发送元数据信息。

--automation 启用一组自动化友好的行为：请求超时、 瞬时故障重试、结构化 JSON 错误、精心设计的 退出代码分类法，以及严格的非交互式确认。详情请参阅 下面的 自动化_。也可以通过设置 环境变量 CORELIGHT_AUTOMATION=1 来启用。

--timeout 设置请求超时时间（以秒为单位），可以是单个数字 N （同时应用于连接和读取），也可以是 connect,read。当启用 --automation 时， 默认为 10,3600。

--retries 设置针对瞬时故障（连接 错误，以及幂等请求的 HTTP 429/502/503/504）尝试的重试次数。当启用 --automation 时， 默认为 3，否则为 0。

--retry-max-time 设置用于重试的最大总秒数。当启用 --automation 时， 默认为 120。

--error-format 将输出/错误格式设置为 text 或 json。当启用 --automation 时， 默认为 json，否则为 text。

--assume-yes 无需提示即可继续执行需要确认的操作 （别名：--confirm）。在启用 --automation 时执行破坏性操作所必需； 否则这些操作将失败并返回需要确认的错误。

自动化

传递 --automation（或设置 CORELIGHT_AUTOMATION=1）会启用一组 自动化友好的行为，并开启下面的退出代码分类法。 它隐含 --noblock，并默认为 10 秒连接 / 3600 秒读取 超时、3 次重试（总上限为 120 秒），以及成功和错误时均输出 JSON。 每一部分都可以用其自己的标志覆盖。

没有 --automation 时完全没有请求超时（客户端会无限期 阻塞），因此启用它绝不会缩短之前存在的超时。默认读取超时故意设置得很长： 它仅用于限制卡住的连接，而不是限制正常工作。某些操作（例如大文件上传）可能 合法地需要很多分钟，而读取超时适用于每次网络读取， 而不是整个传输，因此稳定的上传会不断重置它。如果您希望自动化更快放弃， 请降低 --timeout，或者在慢速链路上进行异常大的传输时提高它。

重试是幂等感知的：GET/HEAD/OPTIONS 请求在 连接失败以及 HTTP 429/502/503/504 时重试。不安全的方法 （POST/PUT/DELETE）仅在连接在到达服务器之前就超时时重试， 因此变更绝不会被发送两次。对于不安全方法上的任何其他 瞬时故障，客户端不会重试；它会以匹配的代码退出 （并在 JSON 错误信封中设置 retriable），以便调用方（只有它知道其操作是否可以安全重复）自行决定。

--retry-max-time 是重试循环的总挂钟时间预算，从 第一次尝试开始计算，并包括请求本身所花费的时间。 它在每次新尝试之前检查：一旦已用时间加上下一次退避将超过它， 就不会再开始进一步的尝试。它绝不会中断已经在进行中的 请求——单个请求的持续时间由上面的读取 超时限制，而不是由该值限制。

退出代码（仅在启用自动化时）：

===== ==================================================== 代码 含义 ===== ==================================================== 0 成功 1 通用 / 意外错误 2 用法 / 错误参数 3 连接失败或超时（重试后） 4 认证 / 授权（401/403） 5 资源未找到（404） 6 服务器错误（5xx） 7 需要确认（拒绝或阻止） 8 API 版本不受支持 ===== ====================================================

.. _corelight-client-config:

配置文件

corelight-client 会查找配置文件 ~/.corelight-client.rc。 该文件必须由 <key>=<value> 行组成。以 # 开头的注释 会被忽略。corelight-client 支持以下键：

device Corelight Sensor 设备的网络地址。

fleet Corelight Fleet Manager 的网络地址。

uid 通过指定的 Corelight Fleet Manager 管理的 Corelight Sensor 的 UID。

user 用于认证的用户名。

password 用于认证的密码。

mfa 用于通过 Corelight Fleet Manager 认证的 2FA 验证码。使用 '-' 询问用户。

ssl-ca-cert 包含用于验证设备真实性的自定义 SSL CA 证书的文件。

ssl-no-verify-certificate 如果设置为 false，客户端将接受任何 Corelight Sensor 的 SSL 证书。

ssl-no-verify-hostname 如果设置为 false，客户端将接受 Corelight Sensor 的 SSL 证书，即使它与主机名不匹配。

socket 用于发送请求的 unix 域套接字。

automation 如果设置为真值，则启用自动化友好的行为。请参阅 自动化_。

timeout 请求超时时间（以秒为单位），可以是 N 或 connect,read。

retries 针对瞬时故障尝试的重试次数。

retry-max-time 用于重试的最大总秒数。

error-format 输出/错误格式，text 或 json。