$ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.72.3/bin/Linux/roxctl
roxctl
is a command-line interface (CLI) for running commands on Red Hat Advanced Cluster Security for Kubernetes.
This topic describes roxctl
syntax, operations, and provides some common examples.
You can install the roxctl
CLI by downloading the binary.
Or, you can run the roxctl
CLI from a container image.
You can install the roxctl
CLI to interact with Red Hat Advanced Cluster Security for Kubernetes from a
command-line interface. You can install roxctl
on Linux, Windows, or macOS.
You can install the roxctl
CLI binary on Linux by using the following procedure.
Download the latest version of the roxctl
CLI:
$ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.72.3/bin/Linux/roxctl
Make the roxctl
binary executable:
$ chmod +x roxctl
Place the roxctl
binary in a directory that is on your PATH
:
To check your PATH
, execute the following command:
$ echo $PATH
Verify the roxctl
version you have installed:
$ roxctl version
You can install the roxctl
CLI binary on macOS by using the following procedure.
Download the latest version of the roxctl
CLI:
$ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.72.3/bin/Darwin/roxctl
Remove all extended attributes from the binary:
$ xattr -c roxctl
Make the roxctl
binary executable:
$ chmod +x roxctl
Place the roxctl
binary in a directory that is on your PATH
:
To check your PATH
, execute the following command:
$ echo $PATH
Verify the roxctl
version you have installed:
$ roxctl version
You can install the roxctl
CLI binary on Windows by using the following procedure.
Download the latest version of the roxctl
CLI:
$ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.72.3/bin/Windows/roxctl.exe
Verify the roxctl
version you have installed:
$ roxctl version
The roxctl
client is the default entry point in Red Hat Advanced Cluster Security for Kubernetes roxctl
image.
To run the roxctl
client in a container image:
You must first generate an authentication token from the RHACS portal.
Log in to the registry.redhat.io
registry.
$ docker login registry.redhat.io
Pull the latest container image for the roxctl
CLI.
$ docker pull registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:3.72.3
After you install the CLI, you can run it by using the following command:
$ docker run -e ROX_API_TOKEN=$ROX_API_TOKEN \
-it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:3.72.3 \
-e $ROX_CENTRAL_ADDRESS <command>
Verify the roxctl
version you have installed.
$ docker run -it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:3.72.3 version
roxctl
CLIFor authentication, you can use an authentication token or your administrator password. Red Hat recommends using an authentication token in a production environment because each token is assigned specific access control permissions.
Use the following steps to generate an authentication token.
Navigate to the RHACS portal.
Go to Platform Configuration → Integrations.
Scroll down to the Authentication Tokens category, and click API Token.
Click Generate Token.
Enter a name for the token and select a role that provides the required level of access (for example, Continuous Integration or Sensor Creator).
Click Generate.
Copy the generated token and securely store it. You will not be able to view it again. |
After you have generated the authentication token, export it as
You can also save the token in a file and use it with the
|
Review the following sections to learn how to complete common tasks using the CLI.
|
Central stores information about:
Activity observed in your clusters,
Information retrieved from integrated image registries or scanners, and
Red Hat Advanced Cluster Security for Kubernetes configuration.
You can back up and restore Central’s database by using the roxctl
CLI.
Run the following command to back up Central’s database:
$ roxctl -e "$ROX_CENTRAL_ADDRESS" central backup
Run the following command to restore Central’s database:
$ roxctl -e "$ROX_CENTRAL_ADDRESS" central db restore <backup_filename>
To secure a Kubernetes or an OpenShift Container Platform cluster, you must deploy Red Hat Advanced Cluster Security for Kubernetes services into the cluster.
You can generate deployment files in the RHACS portal by navigating to the Platform Configuration → Clusters view, or you can use the roxctl
CLI.
$ roxctl -e "$ROX_CENTRAL_ADDRESS" sensor generate k8s --name <cluster_name> --central "$ROX_CENTRAL_ADDRESS"
$ roxctl -e "$ROX_CENTRAL_ADDRESS" sensor generate openshift --openshift-version <ocp-version> --name <cluster_name> --central "$ROX_CENTRAL_ADDRESS" (1)
1 | For the --openshift-version option specify the major OpenShift Container Platform version number for your cluster. For example, specify 3 for OpenShift Container Platform version 3.x and specify 4 for OpenShift Container Platform version 4.x . |
Read the --help
output to see other options that you might need to use depending on your system architecture.
Make sure that the endpoint you provide for --central
can be reached from the cluster where you are deploying Red Hat Advanced Cluster Security for Kubernetes services.
If you are using a non-gRPC capable load balancer, such as HAProxy, AWS Application Load Balancer (ALB), or AWS Elastic Load Balancing (ELB):
|
When you generate the Sensor deployment files, roxctl
creates a directory called sensor-<cluster_name>
in your working directory. The script to install Sensor is present in this directory. Run the sensor installation script to install Sensor.
$ ./sensor-<cluster_name>/sensor.sh
If you get a warning that you do not have the required permissions to install Sensor, follow the on-screen instructions, or contact your cluster administrator for help.
Use the following command to download Sensor bundles for existing clusters by specifying a cluster name or ID.
$ roxctl sensor get-bundle <cluster_name_or_id>
$ roxctl -e "$ROX_CENTRAL_ADDRESS" cluster delete --name=<cluster_name>
Deleting cluster integration will not remove Red Hat Advanced Cluster Security for Kubernetes services running in the cluster.
You can remove them by running the |
You can use the roxctl
CLI to check deployment YAML files and images for policy compliance.
When you check policy compliance by using the deployment check
, image check
, or image scan
commands, you can specify the output format by using the -o
option. This option determines how the output of a command is displayed in the terminal.
You can change the output format by adding the -o
option to the command and specifying the format as json
, table
, csv
, or junit
.
For examle, the following command checks a deployment and then displays the result in csv
format:
$ roxctl -e "$ROX_CENTRAL_ADDRESS" \
deployment check --file =<yaml_filename> \
-o csv
When you do not specify the
|
Different options are available to configure the output. The following table lists the options and the format in which they are available.
Option | Description | Formats |
---|---|---|
|
Use this option to display the JSON output in a compact format. |
|
|
Use this option to specify custom headers. |
|
|
Use this option to omit the header row from the output. |
|
|
Use this option to specify GJSON paths to select specific items from the output. For example, to get the Policy name and Severity for a deployment check, use the following command:
|
|
|
Use this options to merge table cells that have the same value. |
|
|
Use this option to include the header row as a comment in the output. |
|
|
Use this option to specify the name of the JUnit test suite. |
|
The following command checks build-time and deploy-time violations of your security policies in YAML deployment files. Use this command to validate:
Configuration options in a YAML file, such as resource limits or privilege options; or
Aspects of the images used in a YAML file, such as components or vulnerabilities.
$ roxctl -e "$ROX_CENTRAL_ADDRESS" deployment check --file=<yaml_filename>
The following command checks build-time violations of your security policies in images.
$ roxctl -e "$ROX_CENTRAL_ADDRESS" image check --image=<image_name>
You can also check the scan results for specific images.
The following command returns the components and vulnerabilities found in the image in JSON format. The format is defined in the API reference.
$ roxctl -e "$ROX_CENTRAL_ADDRESS" image scan --image <image_name>
To cause Red Hat Advanced Cluster Security for Kubernetes to re-pull image metadata and image scan results from the associated registry and scanner, add the --force
option.
To check specific image scan results, you must have a token with both |
Central saves information to its container logs.
You can see the container logs for Central by running:
$ kubectl logs -n stackrox <central_pod>
$ oc logs -n stackrox <central_pod>
You can change the log level to see more or less information in Central logs. Run the following command to view the current log level:
$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log
Run the following command to change the log level:
$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log --level=<log_level> (1)
1 | The acceptable values for <log_level> are Panic , Fatal , Error , Warn , Info , and Debug . |
To gather debugging information for investigating issues, run the following command:
$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug dump