Create Docker image for cached updates

ReversingLabs provides the official rl-scanner Docker image for easier automation and integration with CI/CD tools.

If you do not need the complete rl-scanner functionality, you can create a custom Docker image that fits your needs and allows for more flexibility regarding rl-secure maintenance and deployment.

This custom image first installs the latest version of rl-deploy. Afterwards, it simply downloads and stores rl-secure installation cache into a separate file with the rl-deploy cache command. After you build the image, you need to create a Docker container and then install rl-secure from the local cached installation file you've created with the Docker image.

To do this, run the rl-deploy install inside the instantiated Docker container that contains the cached updates. This is ideal for ephemeral configurations where the rl-secure installation process needs to be run repeatedly with each new version.

Without the cached installation file, the latest released rl-secure package is downloaded from ReversingLabs servers every time the rl-deploy install command is run. Therefore, running this command frequently in ephemeral environments increases bandwith usage and wastes more time.

In this guide, you will learn how to skip the entire download process by creating your own local cached installation file with the Docker image.

Prerequisites

To successfully create a cached Docker image, you need:

• A valid rl-secure license with a site key. You must convert your license file into a Base64-encoded string to use it with rl-deploy and the Docker image. If you don't already have a site-wide deployment license, follow the instructions in the rl-secure licensing guide to get it from ReversingLabs.
• A stable internet connection to verify your license by connecting to the ReversingLabs servers.
• A working Docker installation on the system where you want to use the image. Follow the official Docker installation instructions for your platform.

Environment variables

License information must be provided using the following environment variables:

Environment variable	Description
RLSECURE_ENCODED_LICENSE	Required. The rl-secure license file as a Base64-encoded string. Users must encode the contents of their license file and provide the resulting string with this variable.
RLSECURE_SITE_KEY	Required. The rl-secure license site key. The site key is a string generated by ReversingLabs and sent to users with the license file.

rl-deploy commands

rl-deploy cache

The rl-deploy cache command is used in our Docker image to create the cached installation file. It supports the following options:

Parameter	Description
--location	Required. Path to the cached rl-secure installation file you're creating. When specifying the path, make sure the current user has permissions to access and write into the specified directory.
--license-file	Path to the license file you received from ReversingLabs - an alternative to providing the license file as a Base64-encoded string. The license file must be on the local filesystem. This option can be used together with --site-key. It is mutually exclusive with --encoded-key.
--encoded-key	Base64-encoded contents of the license file - an alternative to providing the path to the license file. To use this option, you must first encode the contents of your license file, and provide the resulting string to this option. It can be used together with --site-key, and it's mutually exclusive with --license-file.
--site-key	Optional value to be used with the license when installing rl-secure on systems without a stable machine number. The site key is generated by ReversingLabs and sent to users with the license file. This option can be used with either --license-file or with --encoded-key.
--proxy-server	Use it to provide the server URL for local proxy. Only used during the cache download.
--proxy-port	Use it to provide the network port for local proxy. Only used during the cache download.
--proxy-user	Use it to provide the user name for proxy authentication. Must be used together with --proxy-password. Only used during the cache download.
--proxy-password	Use it to provide the password for proxy authentication. Must be used together with --proxy-user. Only used during the cache download.
--stream	Name of the release stream from which you want to pull the rl-secure installation package.
--no-tracking	Don't display progress bars.
-h, --help	Display usage information and exit.

rl-deploy install

The rl-deploy install command is used for installing rl-secure before each use of our generated Docker image. Check the command page for all available command options.

Create and use custom Docker image for cached updates

Workflow overview

• Generate a Docker image that installs rl-deploy and creates a cached rl-secure installation file with rl-deploy cache command
• Create a Docker container needed to run the rl-deploy install command
• Use the cached installation file to install the latest available version of rl-secure with rl-deploy install command
• Use rl-secure installed in the Docker container

info

For best results, it is essential to always use the latest version of the rl-secure tool. This means that every time a new version of rl-secure is available, you should regenerate the created Docker image to make sure the included installation cache is up-to-date.

1. Generate a Docker image

In this step, we're providing an example Dockerfile that can be used as a template for creating a Docker image that installs rl-deploy and then stores the rl-secure installation cache into a file with the rl-deploy cache command.

Usage

This Dockerfile first installs the latest rl-deploy Python package.

To create cached installation package, you need to use the rl-deploy cache command inside your Docker image. rl-deploy connects to the ReversingLabs servers with the provided license information and prepares a cached installation package. This installation package is stored as a file named rl-secure.cache and can be found in the tmp/ folder inside the generated image.

You can then build the image with the assigned rl-deploy-cached tag by using the correctly set environment variables.

Install rl-deploy and save cached installation file

# syntax=docker/dockerfile:1

ARG CACHE_PATH=/tmp/rl-secure.cache

FROM rockylinux:9-minimal
ARG CACHE_PATH
RUN --mount=type=secret,id=rlsecure_license --mount=type=secret,id=rlsecure_sitekey <<EORUN
    set -e
    microdnf upgrade -y
    microdnf install -y --nodocs python3-pip
    pip3 install --no-cache-dir rl-deploy
    microdnf clean all
    rl-deploy cache --no-tracking --location=$CACHE_PATH --encoded-key=$(cat /run/secrets/rlsecure_license) --site-key=$(cat /run/secrets/rlsecure_sitekey)
EORUN

Docker options

We use the following options with Docker to install rl-deploy.

Option	Description
--mount=type=secret,id=rlsecure_license	Mounts your rl-secure license file into the build.
--mount=type=secret,id=rlsecure_sitekey	Mounts your rl-secure license site key into the build.

Build the cached image

docker buildx build . \
    --no-cache \
    --secret id=rlsecure_license,env=RLSECURE_ENCODED_LICENSE \
    --secret id=rlsecure_sitekey,env=RLSECURE_SITE_KEY \
    -t rl-deploy-cached

Docker options

We use the following options with Docker to build the image.

Option	Description
--no-cache	Builds the image without using cache.
--secret id=rlsecure_license,env=RLSECURE_ENCODED_LICENSE	Provides your rl-secure license file as a Base64-encoded string stored inside the RLSECURE_ENCODED_LICENSE environment variable.
--secret id=rlsecure_sitekey,env=RLSECURE_SITE_KEY	Provides your rl-secure license site key as a string stored inside the RLSECURE_SITE_KEY environment variable.
-t rl-deploy-cached	Docker tag assigned to the generated image.

2. Create a Docker container

The image we built in the previous step only contains the prerequisites needed to perform the cached installation. Every time a new rl-secure version is available, you'd need to rerun the image generation process to make sure that your Docker image contains the latest rl-secure installation cache.
This will allow your Docker image to create a cached installation file with the latest rl-secure installation cache.

To run the rl-secure installation process, create a Docker container from the image we generated in the previous step and run the rl-deploy install command inside it.

A container can be created in multiple ways. The command you'll use to achieve this heavily depends on your use case, so it's best to follow the official Docker instructions.

3. Install rl-secure with cached installation file

To install rl-secure by using the locally stored cache file we created in the first step, use the rl-deploy install command with a --from-cache parameter. This command should be performed inside the generated Docker container that contains the cached updates.

rl-deploy install \
    --from-cache=/tmp/rl-secure.cache \
    --location=/opt/rl-secure \
    --encoded-key=<Base64 encoded licence key> \
    --site-key=<site key> \

This command installs the rl-secure tool into the /opt/rl-secure directory of the current container. It skips the package download from ReversingLabs server because we told it to use the cache stored in the /tmp/rl-secure.cache file.

info

You need to run the rl-secure installation process every time you want to use the custom image generated in the first step of this guide for cached rl-secure updates.

4. Execute rl-secure

Now that rl-secure is installed inside your container, you can use it to scan your package or perform any other supported actions.

/opt/rl-secure/rl-secure scan /home/armando/my-package.jar pkg:rl/my-project/my-package@1.0.2

Use the official rl-scanner Docker image

Recommended action

Depending on your needs, you can still use the official rl-scanner Docker image regardless of any custom images you've created.

The rl-scanner Docker image contains helper scanner scripts and uses the cache mechanism to avoid downloading the latest version of rl-secure from the servers whenever you use the image.

Every time a new version of rl-secure is released, the compatible Docker image version is also published. To get the most out of the cached install mechanism, always use the latest rl-scanner image tagged as reversinglabs/rl-scanner:latest.

Best way to make sure that the image is up to date is to execute the docker pull reversinglabs/rl-scanner:latest command before each scan.