Skip to main content

Work with rl-secure licenses

The rl-secure license is a file generated by ReversingLabs for the purpose of controlling rl-secure usage.

To work with rl-secure, you must have a valid and activated rl-secure license. Two types of licenses exist:

  • Single machine license, intended for individual users. It's tied to the automatically generated serial number on the local machine. Because of this, it's ideal for everyday rl-secure usage on typical workstations.
  • Site-wide deployment license, intended for CI/CD and ephemeral deployments. It is tied to a site-wide key that allows you to install rl-secure on multiple systems with the same license.

You should request the most appropriate license for your use case from ReversingLabs during the initial rl-secure setup.

Workflow overview:

  • Choose the license type
  • Request license from ReversingLabs
  • Install rl-secure
  • Activate license

How does the rl-secure license work?​

Your license contains credentials for the ReversingLabs cloud services and determines how much analysis capacity you get.

This analysis capacity is always monthly and automatically resets to zero on the first day of any given month. If you're both a Portal and CLI user, this analysis capacity is divided between the two and can only be configured in the Portal interface.

Scanning a software package deducts its size (file size on disk) from the monthly analysis capacity. The following exceptions apply to all users:

  • Package reprocessing (using the sync command) does not count towards the monthly analysis capacity.
  • Reproducibility checks (using the ?build=repro option with the scan command) do not count towards the monthly analysis capacity.

Licensing also impacts the maximum allowed package size. Scanning will not start if the package size exceeds the analysis capacity and/or the maximum allowed individual file size.

The following example illustrates the error you would receive if you tried to scan a package larger than the allocated maximum while being close to exceeding your monthly analysis capacity. 

Preparing ...
License: Artifact size exceeds the maximum of 10.00 GB
License: Artifact size exceeds the monthly analysis limit (0.01 GB remaining)

In addition to the default analysis capacity that comes with your license, there is also Flex.

The Flex option is a promotional add-on to your license provided by ReversingLabs. It increases the analysis capacity allocated to your account for a limited time period. During this time, you get more capacity for processing your packages.

When Flex is enabled for your account, your default analysis capacity is used first. The Flex capacity is used only when you exceed your purchased analysis capacity.

Entitlement restrictions​

Your rl-secure license can have certain restrictions in place. These restrictions, also known as entitlements, are introduced on the SAFE assessment category and depend on the terms of your license.

When you first download the rl-secure tool, all assessment categories are enabled by default. Depending on which categories you have rights to use, some of them can be disabled upon license activation. This means that if you have a license with restrictions, the disabled category data is not included in the report and cannot be accessed in the terminal. Any policies in that category are also automatically disabled and not used during analysis. If you previously modified the policy configuration that affects these policies, it will not be applied.

Any potential restrictions are visible in the license status and list command outputs. In the rl-json, they are presented as a false value of the enabled field for each affected category, while in the SAFE report (rl-html), every disabled category is greyed out.

If you want to change any set restrictions, you can always contact your sales representative to acquire the license with desired modifications.

Commands requiring a valid license​

Even after your rl-secure license expires, you're considered an owner of all data in your package store. This is why you can still access that data even if you do not have a valid rl-secure license.

However, the actions you can perform with rl-secure on your existing package store are in this case limited. If your license expires, you can use only those commands that work with the existing data. For example, you can modify the rl-secure settings with the config command, but cannot rescan the existing package versions (or scan new package versions) with the updated configuration.

The following commands involve creating new information or changing the state in your package store. They can only be used with a valid license:

init
Set up a package store
list
Show specific or all items in a package store
report
Export analysis reports in multiple formats
scan
Analyzes software packages
sync
Reanalyze software packages to apply configuration changes
update
Upgrade your rl-secure installation to a new version
vault
Manage password vault for a package store
Restore full rl-secure functionality

If you want to regain access to all rl-secure features, get in touch with your sales representative to acquire a new license.

Check your license status​

You can check the status of your license at any time by using the license command:

rl-secure license status

With the status sub-command, you can get information about your serial number, the status of your license, any assessment restrictions, and information on Flex, if it exists for your account.

The license status can be one of the following:

  • unlicensed (not activated yet)
  • valid
  • invalid
  • expired
  • revoked

If you're running rl-secure license status for the first time, the status will be unlicensed and you will be prompted to send your machine serial number to ReversingLabs. This is the first step in the rl-secure installation process.

Activate your license​

The rl-secure tool requires activating a license key as the last step of the installation process.

The process of license activation depends on the product and the type of license you need for your particular purpose. You can use a license tied to a single machine or a license with a site-wide key that can be deployed on multiple machines.

The following table illustrates which rl-secure license can be used with which product.

Single machine licenseSite-wide deployment license
rl-secure✔️✔️
rl-deploy✔️✔️
rl-scanner Docker image❌✔️

Activate your Single machine license​

rl-secure​

  • After extracting and setting up rl-secure, run the following command:

    rl-secure license status

    The output of this command includes your machine key. Copy the machine key and store it in a safe place.

  • Send an email with your machine key to ReversingLabs Support. You can use the following template for the email contents:

    Subject: rl-secure license request

    Body:

    Hello,

    I am [your name] from [your company, organization or other affiliation] 
    and I would like to request a rl-secure license key.

    My machine key: [copy and paste your machine key here]

    Thanks,
    [your signature]

  • ReversingLabs Support will send you the license key as a single file named license.key.

  • Save the license file on your system. It's practical (but not required) to save it into the same directory where you extracted the rl-secure archive.

  • To activate your license, run the following command in the directory where you placed the license key file:

    rl-secure license install license.key

    The command displays the license activation process and informs you when it's successfully completed.

rl-deploy​

To install rl-secure with rl-deploy, you need to provide your license in the installation command.

During the installation, rl-deploy will automatically activate your license if it's valid and correctly provided.

The license can be provided in any of the following formats:

  • as a path to the license file
  • as a string representing Base64-encoded contents of the license file

For CI/CD and similar automated deployments, it's usually more convenient to provide the license as a string directly in the command.

Workflow:

  • After extracting and setting up rl-secure, run the following command:

    rl-secure license status

    The output of this command includes your machine key. Copy the machine key and store it in a safe place.

  • Send an email with your machine key to ReversingLabs Support. You can use the following template for the email contents:

    Subject: rl-secure license request

    Body:

    Hello,

    I am [your name] from [your company, organization or other affiliation] 
    and I would like to request a rl-secure license key.

    My machine key: [copy and paste your machine key here]

    Thanks,
    [your signature]

  • ReversingLabs Support will send you the license key as a single file named license.key.

  • Save the license file on your system. It's practical (but not required) to save it into the same directory where you extracted the rl-secure archive.

  • Install rl-secure to the specified directory. Make sure to run the installation commands with the same permissions that will be used to run rl-secure later.
rl-deploy install /path/to/installation-directory --license-file=/path/to/license-file --no-tracking

Python workaround:

python3 -m rldeploy install /path/to/installation-directory --license-file=/path/to/license-file --no-tracking
Notes and workarounds

The optional --no-tracking parameter hides progress bars in the output to prevent potential issues with CI/CD tools and logs.

In some cases, the rl-deploy command may not work correctly when installed from PyPI. If you encounter this issue, replace rl-deploy with python3 -m rldeploy in your installation command as a workaround.

If you installed rl-deploy from PyPI and it refuses to install rl-secure because it's outdated, run pip install --upgrade rl-deploy to update it to the latest version.

  • Confirm that rl-secure is successfully installed.

    rl-secure --version

  • Verify the license is successfully activated.

    rl-secure license status

Activate your Site-wide deployment license​

rl-secure​

  • Send an email to ReversingLabs Support and request a license to be used with a site key. You can use the following template for the email contents:

    Subject: rl-secure site-wide license request

    Body:

    Hello,

    I am [your name] from [your company, organization or other affiliation] 
    and I would like to request a rl-secure license and a site key.

    Thanks,
    [your signature]

  • ReversingLabs Support will send you the license key as a single file and the site key as a plaintext string.

  • Save the license file on your system and note down the site key for later use. You will need it on all machines where you plan to install rl-secure with that license.

    It's practical (but not required) to save the license file into the same directory where you extracted the rl-secure archive. If you plan to deploy rl-secure in CI/CD, the site key needs to be used for each ephemeral run, and your DevOps teams will need access to it.

  • To activate your license, run the following command in the directory where you placed the license file:

    rl-secure license install license.file --site-key=your-site-key

    The command displays the license activation process and informs you when it's successfully completed.

rl-deploy​

  • Send an email to ReversingLabs Support and request a license to be used with a site key. You can use the following template for the email contents:

    Subject: rl-secure site-wide license request

    Body:

    Hello,

    I am [your name] from [your company, organization or other affiliation] 
    and I would like to request a rl-secure license and a site key.

    Thanks,
    [your signature]

  • ReversingLabs Support will send you the license key as a single file and the site key as a plaintext string.

  • Save the license file on your system and note down the site key for later use. You will need it on all machines where you plan to install rl-secure with that license.

    It's practical (but not required) to save the license file into the same directory where you extracted the rl-secure archive. If you plan to deploy rl-secure in CI/CD, the site key needs to be used for each ephemeral run, and your DevOps teams will need access to it.

  • Install rl-secure to the specified directory. Make sure to run the installation commands with the same permissions that will be used to run rl-secure later.
rl-deploy install /path/to/installation-directory --license-file=/path/to/license-file --site-key=your-site-key --no-tracking

Python workaround:

python3 -m rldeploy install /path/to/installation-directory --license-file=/path/to/license-file --site-key=your-site-key --no-tracking
Notes and workarounds

The optional --no-tracking parameter hides progress bars in the output to prevent potential issues with CI/CD tools and logs.

In some cases, the rl-deploy command may not work correctly when installed from PyPI. If you encounter this issue, replace rl-deploy with python3 -m rldeploy in your installation command as a workaround.

If you installed rl-deploy from PyPI and it refuses to install rl-secure because it's outdated, run pip install --upgrade rl-deploy to update it to the latest version.

  • Confirm that rl-secure is successfully installed.

    rl-secure --version

  • Verify the license is successfully activated.

    rl-secure license status

rl-scanner​

The rl-scanner Docker image can be used with an existing site-wide license that was previously activated with either rl-secure or rl-deploy.

If you're a new user or you simply haven't activated your license yet, you can do so by storing your encoded license and site key into environment variables. This way, rl-deploy can access them from the Docker container and activate the license during the rl-secure installation.