Use the roxctl CLI

Learn how to use the StackRox Kubernetes Security Platform's roxctl command-line interface (CLI).

5 minute read

roxctl is a command-line interface for running commands on the StackRox Kubernetes Security Platform. This overview covers roxctl syntax, describes the command operations, and provides some common command examples.

Install and set up roxctl CLI

  1. You can download the roxctl CLI for your platform Linux or macOS.
  2. After you download roxctl CLI, follow the instructions in Set up roxctl CLI section.

Download roxctl CLI on Linux

To download the latest version of the roxctl CLI:

To download a specific version, replace <version> in the following command with the specific version:

Copy
curl -u <stackrox.io_username> -L https://install.stackrox.io/<version>/bin/Linux/roxctl -o roxctl

Download roxctl CLI on macOS

To download the latest version of the roxctl CLI:

To download a specific version, replace <version> in the following command with the specific version:

Copy
curl -u <stackrox.io_username> -L https://install.stackrox.io/<version>/bin/Darwin/roxctl -o roxctl

Download from the StackRox portal

In the StackRox portal:

  1. Select CLI from the Infobar on top, and then select:

    • Linux 64-bit, to download the roxctl CLI for Linux.
    • Mac 64-bit, to download the roxctl CLI for macOS.

Set up roxctl CLI

  1. Make the roxctl binary executable and add it to your PATH:
    • on Linux:
      Copy
      chmod +x roxctl
      sudo mv roxctl /usr/local/bin/roxctl
    • on macOS, you must also remove all extended attributes:
      Copy
      xattr -c roxctl
      chmod +x roxctl
      mv roxctl /usr/local/bin/roxctl
  2. Verify the roxctl version you’ve installed:
    Copy
    roxctl version

Use the roxctl CLI in a container image

The roxctl client is the default entry point in the StackRox Kubernetes Security Platform roxctl image.

To run the roxctl client in a container image:

  1. Log in to the registry.redhat.io registry:
    Copy
    docker login registry.redhat.io
  2. Pull the latest container image for the roxctl CLI:
    Copy
    docker pull registry.redhat.io/rh-acs/roxctl:3.0.59.1
  3. Run the roxctl CLI:
    Copy
    docker run -e ROX_API_TOKEN=$ROX_API_TOKEN -it registry.redhat.io/rh-acs/roxctl:3.0.59.1 -e $ROX_ENDPOINT [command]

If you have a stackrox.io account use the image location as stackrox.io/roxctl:3.0.59.1 and provide your StackRox credentials.

See Red Hat Container Registry Authentication for information about downloading images from registry.redhat.io.

Syntax

Use the following syntax to run roxctl commands from your terminal:

Copy
roxctl [resources] [commands] [flags]

where resources, command, and flags are:

  • resources: Specifies the resources on which you want to perform operations. For example, central, cluster, image, or deployment.
  • commands: Specifies the operation that you want to perform on one or more resources. For example, roxctl central debug.
  • flags: Specifies options for each command. For example, you can use the -e or --endpoint flag to specify the StackRox Central API endpoint to contact.

View CLI help

Use the --help flag to get a complete list of resources and commands. The --help command lists CLI reference information about available resources, commands, and their flags.

For example,

  • to find all resources, run the following command:
    Copy
    roxctl --help
  • to find available commands for a specific resource, run the following command:
    Copy
    roxctl central --help
  • to find available flags for a specific command, run the following command:
    Copy
    roxctl central debug --help

Authentication

For authentication, you can use an authentication token or your administrator password. We recommend using an authentication token in a production environment because each token is assigned specific role-based access control permissions.

To generate an authentication token:

  1. Navigate to the StackRox portal.

  2. Go to Platform Configuration > Integrations.

  3. Scroll down to the Authentication Tokens category, and select API Token.

  4. Select Generate Token.

  5. Enter a name for the token and select a role that provides the required level of access (for example, Continuous Integration or Sensor Creator).

  6. Select Generate.

    Copy the generated token and securely store it. You won’t be able to view it again.

  7. After you have generated the authentication token, export it as ROX_API_TOKEN variable:

    Copy
    export ROX_API_TOKEN=<api-token>

If you are using the StackRox Kubernetes Security Platform version 3.0.47 or newer, you can also save the token in a file and use it with the --token-file option. For example:

Copy
roxctl central debug dump --token-file <token-file>
  • You can’t use both the -password (-p) and the --token-file options simultaneously.
  • If you’ve already set ROX_API_TOKEN variable, and specify the --token-file option, roxctl uses the specified token file for authentication.
  • If you’ve already set ROX_API_TOKEN variable, and specify the --password option, roxctl uses the specified password for authentication.

Networking options

When you’re using roxctl to connect to StackRox Central, you can use some optional flags to get the precise behavior you need.

Plaintext HTTP

If your Central instance is exposed over an HTTP (non-TLS-enabled) port, add --plaintext --insecure to all commands in this section. We don’t recommend exposing Central over HTTP, however, in such a case, make sure to use it in conjunction with some other means of transport security, for example, a kubectl port-forward tunnel or something similar. This flag is available starting in version 2.5.31.

Direct gRPC

If you encounter any connection issues, pass the --direct-grpc flag and check if adding that flag resolves your issues. The --direct-grpc flag doesn’t work if Central is behind a load balancer that doesn’t support HTTP/2 backends or TLS passthrough. This flag is available starting in version 2.5.31.

TLS verification

You can use the --insecure-skip-tls-verify option with most roxctl commands:

  • If you use --insecure-skip-tls-verify=false, the connection to StackRox Central fails if roxctl receives an invalid certificate.
  • If you use --insecure-skip-tls-verify=true, the connection to StackRox Central always succeeds, even if roxctl receives an invalid certificate.
  • If you don’t use this option, roxctl shows a warning message when it receives an invalid certificate, but the connection proceeds. In a future release, we intend to change roxctl to fail in this case.

The TLS verification flags are available starting in version 2.5.32.

Custom CA

If you use a custom Certificate Authority (CA) that’s not globally trusted, you can provide it using the --ca <filename> option. This flag is available starting in version 2.5.32.

Common operations

Review the following examples to learn how to complete common tasks using the roxctl CLI.

  • Export the following variables before using these commands:

    Copy
    export ROX_API_TOKEN=<api-token>
    export ROX_CENTRAL_ADDRESS=<address>:<port-number>
  • You can use the --help flag to get more information about the commands listed in this section.

Manage the Central database

StackRox Central stores information about:

  • activity observed in your clusters,
  • information retrieved from integrated image registries or scanners, and
  • how you’ve configured the StackRox Kubernetes Security Platform.

You can backup and restore the Central database by using roxctl.

Backup Central database

  • For the StackRox Kubernetes Security Platform version 3.0.55 or newer:
    Copy
    roxctl -e "$CENTRAL_ADDRESS" central backup
  • For the StackRox Kubernetes Security Platform version 3.0.54 or older:
    Copy
    roxctl -e "$CENTRAL_ADDRESS" central db backup

Restore Central database

Copy
roxctl -e "$ROX_CENTRAL_ADDRESS" central db restore <backup-filename>

Manage your StackRox Kubernetes Security Platform license

The StackRox Kubernetes Security Platform requires a license. You can add a license when you install or add one later by using roxctl. You can also upload a new license in the StackRox portal before your current license expires.

Add a license

Copy
export ROX_LICENSE_FILE=<path-to-license>
roxctl -e "$ROX_CENTRAL_ADDRESS" central license add --license=@"$ROX_LICENSE_FILE"

View information about a license key

Before you upload a license, you can decode the key to check it’s the right one to use. This command runs offline and doesn’t connect to StackRox Central.

Copy
roxctl central license info --license=<key or filename>

Manage secured clusters

To secure a Kubernetes or OpenShift cluster, you must deploy StackRox Kubernetes Security Platform services into the cluster. You can generate deployment files in the StackRox portal by navigating to the Platform Configuration > Clusters view, or you can use roxctl.

Generate sensor deployment YAML file

Copy
roxctl -e "$ROX_CENTRAL_ADDRESS" sensor generate k8s --name <cluster-name> --central "$ROX_CENTRAL_ADDRESS"
Copy
roxctl -e "$ROX_CENTRAL_ADDRESS" sensor generate openshift --name <cluster-name> --central "$ROX_CENTRAL_ADDRESS"

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

Be sure that the endpoint you provide for --central can be reached from the cluster where you are deploying StackRox services.

If you’re using a non-gRPC capable LoadBalancer, such as HAProxy, AWS Application Load Balancer (ALB), or AWS Elastic Load Balancing (ELB):

  • use the WebSocket Secure (wss) protocol. To use wss, prefix the address with wss://, and
  • add the port number after the address, for example,
    Copy
    roxctl sensor generate k8s --central wss://stackrox-central.example.com:443

Download sensor bundle for existing clusters

Use the following command to download sensor bundles for existing clusters by specifying a cluster name or ID.

Copy
roxctl sensor get-bundle <cluster-name-or-id>

Delete cluster integration

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

Deleting cluster integration won’t remove StackRox services running in the cluster. You can remove them by running the delete-sensor.sh script from the sensor installation bundle.


Check policy compliance

Check 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:

  • 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.
Copy
roxctl -e "$ROX_CENTRAL_ADDRESS" deployment check --file=<yaml-filename>

Check images

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

Copy
roxctl -e "$ROX_CENTRAL_ADDRESS" image check --image=<image-name>

Check 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 documentation.

Copy
roxctl -e "$ROX_CENTRAL_ADDRESS" image scan --image <image-name>

To cause the StackRox Kubernetes Security Platform to re-pull image metadata and image scan results from the associated registry and scanner, add the --force flag.

To check specific image scan results, you need:

  • a token with both read and write permissions for the Image resource. The default Continuous Integration System role already has the required permissions.

Debug an issue

Manage Central log level

StackRox Central prints information to its container logs. You can see these logs by running:

Copy
kubectl logs -n stackrox <central-pod>
Copy
oc logs -n stackrox <central-pod>

You can change the log level to see more or less information in the Central logs. Most of the time, you don’t need to adjust the log level. While investigating issues, we might advise you to change the log level.

  • Set log level:

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

    The acceptable values for <log-level> are Trace, InitRetry, Debug, Info, Internal, Warn, Error, Panic, or Fatal.

    The acceptable values for the StackRox Kubernetes Security Platform version 3.0.57 and newer are Panic, Fatal, Error, Warn, Info, and Debug.

  • View the current log level:

    Copy
    roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log

Retrieve debugging information

StackRox Support may ask you to provide debugging information to investigate an issue. To gather this information, run:

Copy
roxctl -e "$ROX_CENTRAL_ADDRESS" central debug dump

Questions?

We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.