roxctl CLI

Red Hat Advanced Cluster Security for Kubernetes 3.71

roxctl CLI

Red Hat OpenShift Documentation Team

摘要

本文档论述了如何安装和使用 roxctl 命令行界面，包括 roxctl 语法和操作。它提供了一些常见的命令示例。

第 1 章 roxctl CLI 入门

roxctl 是一个命令行界面 (CLI)，用于在 Red Hat Advanced Cluster Security for Kubernetes 上运行命令。本主题描述了 roxctl 语法、操作，并提供一些常见的示例。

1.1. 安装 roxctl CLI

您可以通过下载二进制文件来安装 roxctl CLI。或者，您可以从容器镜像运行 roxctl CLI。

1.1.1. 通过下载二进制文件安装 roxctl CLI

您可以安装 roxctl CLI，以便使用命令行界面与 Red Hat Advanced Cluster Security for Kubernetes 进行交互。您可以在 Linux、Windows 或 macOS 上安装 roxctl。

1.1.1.1. 在 Linux 中安装 roxctl CLI

您可以按照以下流程在 Linux 上安装 roxctl CLI 二进制文件。

流程

  1. 下载 roxctl CLI 的最新版本： 

    $ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.71.3/bin/Linux/roxctl

  2. 使 roxctl 二进制文件可执行： 

    $ chmod +x roxctl

  3. 将 roxctl 二进制文件放到 PATH 中的目录中：

    要查看您的 PATH，请执行以下命令： 

    $ echo $PATH

验证

  • 验证您已安装的 roxctl 版本： 

    $ roxctl version

1.1.1.2. 在 macOS 上安装 roxctl CLI

您可以按照以下流程在 macOS 中安装 roxctl CLI 二进制文件。

流程

  1. 下载 roxctl CLI 的最新版本： 

    $ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.71.3/bin/Darwin/roxctl

  2. 从二进制文件中删除所有扩展属性： 

    $ xattr -c roxctl

  3. 使 roxctl 二进制文件可执行： 

    $ chmod +x roxctl

  4. 将 roxctl 二进制文件放到 PATH 中的目录中：

    要查看您的 PATH，请执行以下命令： 

    $ echo $PATH

验证

  • 验证您已安装的 roxctl 版本： 

    $ roxctl version

1.1.1.3. 在 Windows 上安装 roxctl CLI

您可以按照以下流程在 Windows 上安装 roxctl CLI 二进制文件。

流程

  • 下载 roxctl CLI 的最新版本： 

    $ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.71.3/bin/Windows/roxctl.exe

验证

  • 验证您已安装的 roxctl 版本： 

    $ roxctl version

1.1.2. 从容器运行 roxctl CLI

roxctl 客户端是 Red Hat Advanced Cluster Security for Kubernetes roxctl 镜像的默认入口点。在容器镜像中运行 roxctl 客户端：

流程

  1. 登录到 registry.redhat.io registry。 

    $ docker login registry.redhat.io

  2. 为 roxctl CLI 拉取最新的容器镜像。 

    $ docker pull registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:3.71.3

安装 CLI 后，您可以使用以下命令运行它： 

$ docker run -e ROX_API_TOKEN=$ROX_API_TOKEN \
  -it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:3.71.3 \
  -e $ROX_CENTRAL_ADDRESS <command>

验证

  • 验证您已安装的 roxctl 版本。 

    $ docker run -it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:3.71.3 version

1.2. 使用 roxctl CLI 进行身份验证

要进行身份验证，您可以使用身份验证令牌或管理员密码。红帽建议在生产环境中使用身份验证令牌，因为每个令牌被分配特定的访问控制权限。

使用以下步骤生成身份验证令牌。

流程

  1. 进入 RHACS 门户。
  2. 进入 Platform Configuration → Integrations。
  3. 向下滚动到 Authentication Tokens 类别，然后点 API Token。
  4. 点 Generate Token。
  5. 输入令牌的名称并选择提供所需访问级别的角色（例如： Continuous Integration 或 Sensor Creator）。

  6. 点 Generate。

    重要

    复制生成的令牌并安全地存储它。您将无法再次查看它。

注意

生成身份验证令牌后，将其导出为 ROX_API_TOKEN 变量： 

$ export ROX_API_TOKEN=<api_token>

您还可以将令牌保存到文件中，并将其与 --token-file 选项一起使用。例如： 

$ roxctl central debug dump --token-file <token_file>
  • 您不能同时使用 -password (-p) 和 --token-file 选项。
  • 如果您已经设置了 ROX_API_TOKEN 变量，并指定 --token-file 选项，roxctl CLI 会使用指定的令牌文件进行身份验证。
  • 如果您已经设置了 ROX_API_TOKEN 变量，并指定 --password 选项，roxctl CLI 将使用指定的密码进行身份验证。

1.3. 使用 roxctl CLI

参阅以下部分以了解如何使用 CLI 完成常见任务。

注意

  • 在使用这些命令前导出以下变量： 

    $ export ROX_API_TOKEN=<api_token>
    $ export ROX_CENTRAL_ADDRESS=<address>:<port_number>
  • 您可以使用 --help 选项获取有关命令的更多信息。

1.3.1. 管理 Central 的数据库

Central 存储以下信息：

  • 在集群中观察到的活动，
  • 从集成镜像 registry 或扫描程序获取的信息，以及
  • Red Hat Advanced Cluster Security for Kubernetes 配置。

您可以使用 roxctl CLI 备份和恢复 Central 的数据库。

备份 Central 数据库

运行以下命令以备份 Central 的数据库： 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central backup
恢复中央数据库

运行以下命令来恢复 Central 的数据库： 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central db restore <backup_filename>

1.3.2. 管理安全集群

要保护 Kubernetes 或 OpenShift Container Platform 集群，您必须将 Red Hat Advanced Cluster Security for Kubernetes 服务部署到集群中。您可以通过进入到 Platform Configuration → Clusters 视图在 RHACS 门户生成部署文件，也可以使用 roxctl CLI。

生成 Sensor 部署 YAML 文件

Kubernetes

$ roxctl -e "$ROX_CENTRAL_ADDRESS" sensor generate k8s --name <cluster_name> --central "$ROX_CENTRAL_ADDRESS"

OpenShift Container Platform

$ roxctl -e "$ROX_CENTRAL_ADDRESS" sensor generate openshift --name <cluster_name> --central "$ROX_CENTRAL_ADDRESS"

阅读 --help 输出以查看您可能需要使用的其他选项，具体取决于您的系统架构。

确保从部署 Red Hat Advanced Cluster Security for Kubernetes 服务的集群中访问您为 --central 提供的端点。

注意

如果您使用一个支持非 gRPC 的负载均衡器，如 HAProxy、AWS Application Load Balancer (ALB) 或 AWS Elastic Load Balancing (ELB)：

  • 使用 WebSocket Secure (ws) 协议。要使用 wss，使用 ws:// 为地址添加前缀，并

  • 在地址后添加端口号，例如： 

    $ roxctl sensor generate k8s --central wss://stackrox-central.example.com:443
为现有集群下载 Sensor 捆绑包

使用以下命令通过指定集群名称或 ID 为现有集群下载 Sensor 捆绑包。 

$ roxctl sensor get-bundle <cluster_name_or_id>
删除集群集成
$ roxctl -e "$ROX_CENTRAL_ADDRESS" cluster delete --name=<cluster_name>
重要

删除集群集成不会删除集群中运行的 Red Hat Advanced Cluster Security for Kubernetes 服务。您可以从 Sensor 安装捆绑包中运行 delete-sensor.sh 脚本来删除它们。

1.3.3. 检查策略合规性

您可以使用 roxctl CLI 检查部署 YAML 文件和镜像是否合规。

配置输出格式

当您使用 deployment check, image check, 或 image scan 命令检查策略的合规性时，您可以使用 -o 选项指定输出格式。此选项决定了如何在终端中显示命令的输出。

您可以通过在命令中添加 -o 选项，并将格式指定为 json、table、csv 或 junit 来更改输出格式。

对于考试，以下命令检查部署，然后以 csv 格式显示结果： 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" \
  deployment check --file =<yaml_filename> \
  -o csv
注意

当您没有为输出格式指定 -o 选项时，会使用以下默认行为：

  • deployment check 和 image check 命令的格式是 table。
  • image scan 命令的默认输出格式是 json。这是与 CLI 旧版本兼容的旧 JSON 格式输出。若要以新的 JSON 格式获取输出，使用格式选项，如 -o json。

可以不同的选项用于配置输出。下表列出了选项及其可用格式。

选项描述格式

--compact-output

使用此选项以紧凑格式显示 JSON 输出。

json

--headers

使用这个选项指定自定义标头。

table 和 csv

--no-header

使用这个选项省略输出中的标头行。

table 和 csv

--row-jsonpath-expressions

使用这个选项指定 GJSON 路径，以选择输出中的特定项目。例如，若要获取部署检查的策略名称和严重性，请使用以下命令： 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" \
  deployment check --file=<yaml_filename> \
  -o table --headers POLICY-NAME,SEVERITY \
  --row-jsonpath-expressions="{results.#.violatedPolicies.#.name,results.#.violatedPolicies.#.severity}"

table 和 csv

--merge-output

使用此选项合并具有相同值的表单元。

table

headers-as-comment

使用这个选项在输出中将标头行包含为注释。

csv

--junit-suite-name

使用此选项指定 JUnit 测试套件的名称。

junit

检查部署 YAML 文件

以下命令检查 YAML 部署文件中的安全策略的构建时间和部署时间违反情况。使用这个命令验证：

  • YAML 文件中的配置选项，如资源限值或特权选项；或者
  • YAML 文件中使用的镜像的各个方面，如组件或漏洞。 
$ roxctl -e "$ROX_CENTRAL_ADDRESS" deployment check --file=<yaml_filename>
检查镜像

以下命令检查镜像中安全策略的构建时违反情况。 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" image check --image=<image_name>
检查镜像扫描结果

您还可以检查特定镜像的扫描结果。

以下命令以 JSON 格式返回镜像中发现的组件和漏洞。格式在 API 引用中定义。 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" image scan --image <image_name>

要让 Red Hat Advanced Cluster Security for Kubernetes 从关联的 registry 和扫描程序中拉取镜像元数据和镜像扫描结果，请添加 --force 选项。

注意

要检查特定的镜像扫描结果，您必须具有 Image 资源的 read 和 write 权限的令牌。默认的 Continuous Integration 系统角色已具有所需的权限。

1.3.4. 调试问题

管理中央日志级别

Central 将信息保存到其容器日志中。

查看日志

您可以运行以下命令来查看 Central 的容器日志：

Kubernetes

$ kubectl logs -n stackrox <central_pod>

OpenShift Container Platform

$ oc logs -n stackrox <central_pod>

查看当前日志级别

您可以更改日志级别，以在 Central 日志中看到更多或较少的信息。运行以下命令来查看当前的日志级别： 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log
更改日志级别

运行以下命令来更改日志级别： 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log --level=<log_level> 1
1
<log_level> 可以接受的值是：Panic, Fatal, Error, Warn, Info, 和 Debug。
检索调试信息

要收集用于调查问题的调试信息，请运行以下命令： 

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug dump

法律通告

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.