Chapter 1. Getting started with the roxctl CLI

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.

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:

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:4.0.5 \
  -e $ROX_CENTRAL_ADDRESS <command>

Note the following guidelines:

Central stores information about:

You can back up and restore Central’s database by using the roxctl CLI.

Backing up Central database

Run the following command to back up Central’s database:

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central backup

Restoring Central database

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.

Generating Sensor deployment files

$ 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

Read the --help output to see other options that you might need to use depending on your system architecture.

Verify 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.

Installing Sensor by using the generate YAML files

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.

Downloading Sensor bundle for existing clusters

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>

Deleting cluster integration

$ roxctl -e "$ROX_CENTRAL_ADDRESS" cluster delete --name=<cluster_name>

You can use the roxctl CLI to check deployment YAML files and images for policy compliance.

Configuring output format

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 example, 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

Different options are available to configure the output. The following table lists the options and the format in which they are available.

$ 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}"

Checking deployment YAML files

The following command checks build-time and deploy-time violations of your security policies in YAML deployment files. Use this command to validate:

$ roxctl -e "$ROX_CENTRAL_ADDRESS" deployment check --file=<yaml_filename>

Checking images

The following command checks build-time violations of your security policies in images.

$ roxctl -e "$ROX_CENTRAL_ADDRESS" image check --image=<image_name>

Checking image scan results

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.

Managing Central log level

Central saves information to its container logs.

Viewing the logs

You can see the container logs for Central by running:

$ kubectl logs -n stackrox <central_pod>

$ oc logs -n stackrox <central_pod>

Viewing current log level

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

Changing the log level

Run the following command to change the log level:

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log --level=<log_level> 1

Retrieving debugging information

To gather debugging information for investigating issues, run the following command:

$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug dump

The build-time network policy generator is included in the roxctl CLI. For the build-time network policy generation feature, roxctl CLI does not need to communicate with RHACS Central so you can use it in any development environment.

The roxctl generate netpol command supports the following options: