Quick Start

Install, configure, and test the StackRox Kubernetes Security Platform.

This guide describes step-by-step instructions for installing the StackRox Kubernetes Security Platform and conducting simple tests using sample container images.

StackRox installs as a set of services in your Kubernetes or OpenShift cluster. You can use the same central installation to secure multiple clusters.

If you want to upgrade from an existing version to a newer version, see Upgrade StackRox.

Prerequisites

To install the StackRox Kubernetes Security Platform, you need:

  • A Kubernetes or OpenShift cluster.

    See the supported platforms topic to learn more about the operating systems, container platforms, and managed Kubernetes services that we support.

    We don’t support:

    • installing the StackRox Kubernetes Security Platform on Minikube and other similar single-node clusters.
    • Amazon Elastic File System (Amazon EFS), use the Amazon Elastic Block Store (Amazon EBS) with the default gp2 volume type instead.
    • older CPUs that don’t have the Streaming SIMD Extensions (SSE) 4.2 instruction set, for example Intel processors older than Sandy Bridge and AMD processors older than Bulldozer. (Both of these processors were released in 2011.)
  • Cluster nodes with:

    • Operating system: Amazon Linux, CentOS, Container-Optimized OS from Google, CoreOS, Debian, Red Hat Enterprise Linux, or Ubuntu.

    • Processor and memory: 2 CPU cores and at least 3GiB of RAM.

      For deploying Central, we recommend that you use a machine type with 4 or more cores and apply scheduling policies to launch Central on such nodes.

  • Persistent storage by using PersistentVolumeClaim (pvc) or hostPath.

    • Use the host-mounted storage only if all your hosts (or a group of hosts) mount a shared filesystem, such as an NFS share or a storage appliance. Otherwise, your data is only saved on a single node.

    • We recommend using Solid-State Drives (SSDs) for best performance. However, you can use another storage type if you don’t have SSDs available.

    • To use an SSD on Google Kubernetes Engine (GKE), you must use an SSD StorageClass. You can use an existing StorageClass, or you can create a new StorageClass before running the installer.

      For example, to create a StorageClass, run the following command:

      Copy
      kubectl apply -f - <<EOF
      apiVersion: storage.k8s.io/v1
      kind: StorageClass
      metadata:
        name: ssd
      provisioner: kubernetes.io/gce-pd
      parameters:
        type: pd-ssd
      EOF

      Once done, you can specify the StorageClass name as ssd while answering the installer prompts.

  • A system with the kubectl (Kubernetes) or oc (OpenShift) command-line tool.

For detailed system-level requirements, see Resource requirements.

Permissions
  1. You must have the required permissions to configure Deployments in the central cluster.
  2. To secure a cluster, you must have permissions to configure Deployments, DaemonSets, ClusterRoleBindings, RoleBindings, and ServiceAccounts in that cluster.

StackRox registry access

The StackRox Kubernetes Security Platform is distributed using standard container images. You can download these images from:

  • registry.redhat.io, or
  • stackrox.io.
  1. See Red Hat Container Registry Authentication for information about downloading images from registry.redhat.io.
  2. To complete the installation using stackrox.io, you need an account with the StackRox’s container registry.

Skip these steps if you already have an account.

To create a new account:

  1. Go to https://signup.stackrox.io.
  2. Create a username and a password, consent to User Agreement, and click Sign Up. Keep a note of your username and password. They’re required to download images during the installation.
  3. Wait for your account approval. A StackRox customer support representative will contact you after we approve your account.

You can’t download StackRox Kubernetes Security Platform images until StackRox activates your account.

We respond as quickly as possible, but if you have questions, contact support@stackrox.com.

Get a license

Beginning from the StackRox Kubernetes Security Platform version 3.0.58.0, we’ve removed all licensing restrictions.

The StackRox Kubernetes Security Platform enforces licensing restrictions for all versions between 2.4.20 and 3.0.57.

Contact your sales representative or StackRox support if you don’t have a license.

See Licensing and activation for more details.

Install StackRox Central

The StackRox Kubernetes Security Platform installs as a set of containers in your Kubernetes or OpenShift cluster and includes the multiple components. The main software component of the StackRox Kubernetes Security Platform is called Central. To learn about the components that make up the StackRox Kubernetes Security Platform, see StackRox architecture.

To install StackRox Central:

Download the roxctl CLI

The roxctl command-line interface (CLI) allows you to install and configure the StackRox Kubernetes Security Platform and its components. For more information, see Use the roxctl CLI topic.

  1. Download the roxctl CLI:

    1. By using your browser:

    2. Or by using curl and providing your stackrox.io credentials:

      • On Linux:
        Copy
        curl -O https://mirror.openshift.com/pub/rhacs/assets/3.0.59.1/bin/Linux/roxctl
      • On macOS:
        Copy
        curl -O https://mirror.openshift.com/pub/rhacs/assets/3.0.59.1/bin/Darwin/roxctl

After you download the roxctl CLI:

  1. Make the roxctl binary executable and add it to your PATH:

    Copy
    chmod +x roxctl
    sudo mv roxctl /usr/local/bin/roxctl

    If you prefer not to add the roxctl CLI to your PATH, use ./roxctl instead of roxctl for all commands.

  2. Verify that the roxctl version you installed is up-to-date. The most current version is 3.0.59.1:

    Copy
    roxctl version

Run the interactive installer

  1. Run the installer to generate the appropriate secrets and deployment configurations for your environment. During installation, the installer prompts you to provide additional information. Press Enter to accept the default value.

    • Run the interactive installer:

      Copy
      roxctl central generate interactive

      If you want to add a custom TLS certificate, provide the file paths for the PEM encoded certificate and the key files when answering the prompts. See Add a custom security certificate for more details.

    • Enter answers for the prompts:

      Copy
      Enter PEM cert bundle file (optional): cert.pem
      Enter PEM private key file (optional): key.pem
      Enter license data or filename (`-` for multiline input) (optional): <your key>
      Enter administrator password (default: autogenerated):
      Enter orchestrator (k8s, openshift): k8s
      Enter the directory to output the deployment bundle to (default: "central-bundle"):
      Enter Istio version when deploying into an Istio-enabled cluster (leave empty when not running Istio) (optional):
      Enter whether to enable telemetry (default: "true"):
      Enter the method of exposing Central (lb, np, none) (default: "none"): lb
      Enter main image to use (default: "stackrox.io/main:3.0.59.1"):
      Enter whether to run StackRox in offline mode, which avoids reaching out to the Internet (default: "false"): 
      Enter the deployment tool to use (kubectl, helm, helm-values) (default: "kubectl"):
      Enter Scanner DB image to use (default: "stackrox.io/scanner-db:2.13.0"):
      Enter Scanner image to use (default: "stackrox.io/scanner:2.13.0"):
      Enter Central volume type (hostpath, pvc): pvc
      Enter external volume name (default: "stackrox-db"):
      Enter external volume size in Gi (optional, defaults to 100Gi) (default: "100"):
      Enter storage class name (optional if you have a default StorageClass configured):
      
      Copy
      Enter PEM cert bundle file (optional): cert.pem
      Enter PEM private key file (optional): key.pem
      Enter license data or filename (`-` for multiline input) (optional): <your key>
      Enter administrator password (default: autogenerated):
      Enter orchestrator (k8s, openshift): openshift
      Enter the directory to output the deployment bundle to (default: "central-bundle"):
      Enter Istio version when deploying into an Istio-enabled cluster (leave empty when not running Istio) (optional):
      Enter whether to enable telemetry (default: "true"):
      Enter the method of exposing Central (route, lb, np, none) (default: 'none'): route
      Enter main image to use (default: "stackrox.io/main:3.0.59.1"):
      Enter whether to run StackRox in offline mode, which avoids reaching out to the Internet (default: "false"):
      Enter Scanner DB image to use (default: "stackrox.io/scanner-db:2.13.0"):
      Enter Scanner image to use (default: "stackrox.io/scanner:2.13.0"):
      Enter Central volume type (hostpath, none, pvc): hostpath
      Enter path on the host (default: "/var/lib/stackrox"):
      Enter node selector key (e.g. kubernetes.io/hostname): kubernetes.io/hostname
      Enter node selector value: <your node name with the host path created>
      

      If you plan to use OpenShift with a hostPath volume, you must modify the SELinux policy to allow access to the directory, which the host and the container share. It’s because SELinux blocks directory sharing by default. To modify the SELinux policy, run the following command:

      Copy
      sudo chcon -Rt svirt_sandbox_file_t <full-volume-path>

      However, we don’t recommend modifying the SELinux policy, instead use PVC when installing on OpenShift.

      • For entering the license data, don’t use the - option. Paste the license key directly.
      • We’ve removed all licencing restrictions from the StackRox Kubernetes Security Platform version 3.0.58. If you’re installing the StackRox Kubernetes Security Platform version 3.0.58 or newer there won’t be any license related prompts.
      • The Istio prompt only shows up if your are using the StackRox Kubernetes Security Platform version 3.0.49 or newer.

      On completion, the installer:

      • creates a folder named central-bundle, which contains the necessary YAML manifests and scripts to deploy StackRox Central.
      • shows on-screen instructions for the scripts you need to run to deploy additional trusted certificate authorities, Central, and Scanner.
      • shows authentication instructions for logging into the StackRox portal along with the autogenerated password (if you didn’t provide your own administrator password).
  2. Run the setup script to configure image registry access,

    Copy
    ./central-bundle/central/scripts/setup.sh
  3. Create the necessary resources:

    Copy
    kubectl create -R -f central-bundle/central
    Copy
    oc create -R -f central-bundle/central

    The cluster begins creating all required resources. To check deployment progress, use the following command:

    Copy
    kubectl get pod -n stackrox -w
    Copy
    oc get pod -n stackrox -w
  4. After StackRox Central is running, find the StackRox portal IP address and open it in your browser. Depending on the exposure method you selected when answering the prompts, use one of the following methods to get the IP address.

    Exposure MethodWhat to RunWhat to OpenExample
    Load Balancerkubectl -n stackrox get svc central-loadbalancerEXTERNAL-IP or hostname shown for the service, on port 443https://192.0.2.0
    Node Portkubectl get node -owide && kubectl -n stackrox get svc central-loadbalancerIP or hostname of any node, on the port shown for the servicehttps://198.51.100.0:31489
    Nonecentral-bundle/central/scripts/port-forward.sh 8443https://localhost:8443https://localhost:8443
    Exposure MethodWhat to RunWhat to OpenExample
    Routeoc -n stackrox get route centralThe address under the HOST/PORT column in the outputhttps://central-stackrox.example.route
    Node Portoc get node -owide && oc -n stackrox get svc central-loadbalancerIP or hostname of any node, on the port shown for the servicehttps://198.51.100.0:31489
    Nonecentral-bundle/central/scripts/port-forward.sh 8443https://localhost:8443https://localhost:8443
  5. To unlock the StackRox Kubernetes Security Platform, activate your license. Skip this,

    • if you are installing the StackRox Kubernetes Security Platform version 3.0.58 or newer,
    • or you’ve already added your license key when answering the prompts during the installation.

    Beginning from the StackRox Kubernetes Security Platform version 3.0.58.0, we’ve removed all licensing restrictions.

    Contact your sales representative or StackRox support if you don’t have a license.

    1. Open the StackRox portal.

    2. Select Upload New License Key, and upload your license file.

      See Licensing and activation for more details.

  6. Log in by using the password you set during the deployment process. The default username is admin. If you selected an autogenerated password, run the following command to get its value and use it to log in:

    Copy
    cat central-bundle/password

Configure vulnerability scanning

StackRox enriches deployments with image vulnerability information.

You can configure the StackRox Kubernetes Security Platform to obtain image data from a variety of open-source and commercial image scanners.

If you’ve already integrated one of these products into your DevOps workflow, configure a connection on the Integrations page.

The StackRox Kubernetes Security Platform also provides an image vulnerability scanner, the StackRox Scanner. We recommend deploying StackRox Scanner so that it can scan all images, including the images from public registries, for vulnerabilities. You can deploy the StackRox Scanner in the same cluster with StackRox Central.

To deploy StackRox Scanner:

  1. Return to the terminal where you first deployed StackRox, and run the following command to configure image registry access:

    Copy
    ./central-bundle/scanner/scripts/setup.sh
  2. After the script finishes, run the following command to create the scanner service:

    Copy
    kubectl create -R -f central-bundle/scanner
    Copy
    oc create -R -f central-bundle/scanner

For StackRox Scanner to download and scan an image, you must configure your image registry. See Image Registry integration for the details.

Usually, these integrations are created automatically.

Install a Sensor

To monitor a cluster, you must deploy a Sensor. The following steps describe adding a sensor by using the StackRox portal, see the Manage secured clusters section for details about doing this by using the roxctl CLI.

To add a new cluster:

  1. On the StackRox portal, navigate to Platform Configuration > Clusters.

  2. Select + New Cluster.

  3. Specify a name for the cluster.

    • If you’re deploying the sensor in the same cluster, accept the default values for all the fields.
    • If you’re deploying into a different cluster, replace central.stackrox:443 with a LoadBalancer, NodePort, or other address (including the port number) that’s accessible from the other cluster.
    • 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, wss://stackrox-central.example.com:443.
  4. Click Next to continue with Sensor Setup.

  5. Click Download YAML File and Keys.

  6. From a system that has access to the monitored cluster, unzip and run the sensor script:

    Copy
    unzip -d sensor sensor-[cluster-name].zip
    
    ./sensor/sensor.sh

    If you get a warning that you don’t have the required permissions to deploy the sensor, follow the on-screen instructions, or contact your cluster administrator for assistance.

    After the sensor is deployed, it contacts StackRox Central and provides cluster information.

  7. Return to the StackRox portal and check if the deployment is successful. If it’s successful, a green checkmark appears under section #2.

    • If you don’t see a green checkmark, use the following command to check for problems:

      Copy
      kubectl get pod -n stackrox -w
      Copy
      oc get pod -n stackrox -w
  8. Click Finish to close the window.

Your cluster is now reporting security information to the StackRox Kubernetes Security Platform.

Your Dashboard will begin to show deployments, images, and policy violations from the cluster.

The zip file includes unique configurations and keys for each cluster. Don’t reuse the same files in another cluster.

Verify installation

After you complete the installation and configure necessary integrations, run sample applications to evaluate the results of security assessments and policy violations.

The sample applications described below are specifically designed to verify the build and deploy-time assessment features of the StackRox Kubernetes Security Platform.

To run the sample application:

  1. Create a new namespace (or project).

    Copy
    kubectl create ns test
    Copy
    oc new-project test
  2. Start a few workloads with critical vulnerabilities:

    Copy
    kubectl run shell --labels=app=shellshock,team=test-team --image=vulnerables/cve-2014-6271 -n test
    kubectl run samba --labels=app=rce --image=vulnerables/cve-2017-7494 -n test
    Copy
    oc run shell --labels=app=shellshock,team=test-team --image=vulnerables/cve-2014-6271 -n test
    oc run samba --labels=app=rce --image=vulnerables/cve-2017-7494 -n test

    The StackRox Kubernetes Security Platform automatically scans these deployments for security risk and policy violations as soon as they’re submitted to the cluster.

Questions?

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

© 2021 StackRox Inc. All rights reserved.