Enable offline mode

Learn how to use the StackRox Kubernetes Security Platform in clusters without internet connectivity.

4 minute read

You can use the StackRox Kubernetes Security Platform for clusters which aren’t connected to the internet by enabling the offline mode. In offline mode, StackRox components won’t connect to addresses or hosts on the internet.

To deploy and operate the StackRox Kubernetes Security Platform in offline mode:

  1. Download the StackRox Kubernetes Security Platform images in a tarball (tgz) format. These files are easy to transfer across network air gaps or other boundaries.
  2. Enable offline mode during installation.
  3. (Optional) Routinely update StackRox Scanner’s vulnerability list by uploading a new definitions file.
  4. (Optional) When required, add support for runtime collection on more kernel versions by uploading new kernel support packages.

The StackRox Kubernetes Security Platform doesn’t determine if the user-supplied hostnames, IP addresses, or other resources are on the internet. For example, if you try to integrate with a Docker registry hosted on the internet, the StackRox Kubernetes Security Platform won’t block this request.

You can only enable offline mode during the installation, not during an upgrade.

Download images for offline use

You can download the StackRox Kubernetes Security Platform images by using an offline bundle, or you can download the images directly.

Using an offline bundle

You can download the offline image bundles from a StackRox-provided server. These bundles are tarball archives of the images and also include the roxctl CLI.

  1. Download the following image bundles:

  2. Copy the image bundles to the network where you want to deploy the StackRox Kubernetes Security Platform.

To extract the StackRox Kubernetes Security Platform images and upload them to your registry, run the following commands on a host with Docker installed.

  1. Decompress the archives:

    Copy
    tar xzvf image-bundle.tgz
    tar xzvf image-bundle-collector.tgz
  2. Read the README.txt files:

    Copy
    cat image-bundle/README.txt
    cat image-collector-bundle/README.txt
  3. Run the import.sh script for each bundle.

    • If you want to push the image to a registry, provide the registry prefix when answering the prompts.
    • If you don’t provide a registry prefix, the images are only uploaded to the local Docker host. You must then manually run the docker tag and docker push commands to push the images to your registry.
    Copy
    image-bundle/import.sh
    image-collector-bundle/import.sh

Using images directly

If you don’t want to use an image bundle, you can manually pull, retag, and push the StackRox Kubernetes Security Platform images to your registry. The images included in the current version of the image bundles are:

  • stackrox.io/main:3.63.0
  • stackrox.io/scanner:2.17.4
  • stackrox.io/scanner-db:2.17.4
  • collector.stackrox.io/collector:3.1.30-latest

When you retag an image, you must maintain the name of the image and the tag. For example, use:

Copy
docker tag stackrox.io/main:3.63.0 <your-registry>/main:3.63.0

and don’t retag like the following example:

Copy
❌ docker tag stackrox.io/main:3.63.0 <your-registry>/other-name:latest

To retag an image, use the following commands:

Copy
docker login stackrox.io
docker pull <stackrox.io-image>
docker tag <stackrox.io-image> <new-image>
docker push <new-image>

The StackRox Collector image is distributed from a separate registry. To retag Collector, use the following commands:

Copy
docker login collector.stackrox.io
docker pull <collector.stackrox.io-image>
docker tag <collector.stackrox.io-image> <new-image>
docker push <new-image>

Enable offline mode during installation

To install the StackRox Kubernetes Security Platform in offline mode, follow the interactive install instructions in Quick Start.

When you answer the prompts during installation, provide the following values:

  • If you are using a registry other than StackRox’s internet-connected registry (stackrox.io), provide the locations where you have pushed the StackRox Kubernetes Security Platform images when answering the image to use prompts.
  • To enable the offline mode, enter true when answering the Enter whether to run StackRox in offline mode prompt.
Copy
Enter main image to use (default: "stackrox.io/main:3.63.0"): <your-registry>/stackrox/main:3.63.0
...
Enter whether to run StackRox in offline mode, which avoids reaching out to the internet (default: "false"): true
...
Enter Scanner DB image to use (default: "stackrox.io/scanner-db:2.17.4"): <your-registry>/stackrox/scanner-db:2.17.4
Enter Scanner image to use (default: "stackrox.io/scanner:2.17.4"): <your-registry>/stackrox/scanner:2.17.4

Then, when you add StackRox Sensor to a remote cluster in the Platform Configuration > Clusters view, be sure to use your StackRox Collector image name in the Collector Image Repository field.

Update Scanner definitions in offline mode

StackRox Scanner contains a local vulnerability definitions database. When the StackRox Kubernetes Security Platform runs in normal mode (connected to the internet), Scanner fetches new vulnerability definitions from the internet and updates its database. See Vulnerability definitions for more details.

However, when you are using the StackRox Kubernetes Security Platform in offline mode, you must manually update Scanner definitions by uploading them to Central.

When the StackRox Kubernetes Security Platform runs in offline mode, Scanner checks for new definitions from Central. If new definitions are available, Scanner downloads the new definitions from Central, marks them as default, and then uses the updated definitions for scanning images.

To update the definitions in offline mode:

  1. Download the definitions.
  2. Upload definitions to Central.
  3. Restart Scanner.
  • To download Scanner definitions, you need a system with internet access.

  • To upload Scanner definitions to central and to restart Scanner, you need a system with following command-line tools:

    • kubectl (Kubernetes) or oc (OpenShift).
    • roxctl (version 2.4.23.0 or higher). Follow the instructions in the Quick start guide to download the latest version of the roxctl command-line interface (CLI).

Download the definitions

  1. Download the latest Scanner definitions, by providing your stackrox.io username and password.

    • For Scanner version 2.0.0 and newer (StackRox Kubernetes Security Platform version 3.0.35.0 and newer):

    • For Scanner versions before 2.0.0 (StackRox Kubernetes Security Platform versions before 3.0.35.0):

Upload definitions to Central

To upload Scanner definitions to Central, you can either use an API token or your administrator password.

Upload definitions using an API token

  1. Generate an API token with administrator role. See the Authentication section of Use the API page.
  2. Create the following environment variables:
    Copy
    export ROX_API_TOKEN=<api-token>
    export CENTRAL_ADDRESS=<address>:<port-number>
  3. Upload the definitions file:
    Copy
    roxctl scanner upload-db -e "$CENTRAL_ADDRESS" --scanner-db-file=</path/to/compressed/scanner/definitions>
    On success, you receive the response Successfully stored the scanner definitions.

Upload definitions using administrator password

  1. Create the following environment variable:
    Copy
    export CENTRAL_ADDRESS=<address>:<port-number>
  2. Upload definitions to Central using the following roxctl command:
    Copy
    roxctl scanner upload-db -e "$CENTRAL_ADDRESS" --scanner-db-file=</path/to/compressed/scanner/definitions> -p <administrator-password>
    On success, you receive the response Successfully stored the scanner definitions.

Restart Scanner

If you are using the StackRox Kubernetes Security Platform version 3.0.35 (Scanner version 2.0.1) or higher, you can skip restarting Scanner. Starting with this version, Scanner requests updates from Central every 5 minutes.

To restart Scanner:

  1. Find name of the Scanner pod:

    Copy
    kubectl -n stackrox get pod
    Copy
    oc -n stackrox get pod
  2. Delete the Scanner pod:

    Copy
    kubectl -n stackrox delete pod <scanner_pod_name>
    Copy
    oc -n stackrox delete pod <scanner_pod_name>
    Kubernetes then creates a new Scanner pod, which checks with Central for updated definitions during startup, and uses the new definitions.

Upload kernel support packages

StackRox Collector monitors the runtime activity for each node in your secured clusters. To monitor the activities, Collector requires probes. These probes are kernel modules or eBPF programs specific to the Linux kernel version installed on the host. The Collector image contains a set of built-in probes.

When the StackRox Kubernetes Security Platform runs in normal mode (connected to the internet), Collector automatically downloads a new probe from a StackRox-operated server on the internet if the required probe isn’t built in.

In offline mode, you can manually download packages containing probes for all recent and supported Linux kernel versions and upload them to Central. Collectors then download these probes from Central.

To apply a new support package, see Upload support packages to Central.

Questions?

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

© 2021 StackRox Inc. All rights reserved.