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 risk 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 HTML report, 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.

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)
• 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 license	Site-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.

License as file path

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

License as string

• Convert the contents of your license file into a Base64-encoded string. On Linux-based systems, you can do this with the base64 command from the GNU coreutils package. On Windows, you can use either the certutil command or the ToBase64String() method. Save the encoded string for later use.

Example: using the base64 utility on Linux

$ base64 -w 0 /path/to/license-file

Example: using the ToBase64String method on Windows

[convert]::ToBase64String([IO.File]::ReadAllBytes("X:path\to\license-file"))

Then, use the encoded string in the installation command:

rl-deploy install /path/to/installation-directory --encoded-key=your-license-contents-as-Base64-encoded-string --no-tracking

Python workaround:

python3 -m rldeploy install /path/to/installation-directory --encoded-key=your-license-contents-as-Base64-encoded-string --no-tracking

Security best practices: Protect your keys

If your tools and workflows support it, you can use the environment variable to store the encoded key. Make sure to password-protect or encrypt it if possible and treat it as any other sensitive information.

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.

License as file path

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

License as string

• Convert the contents of your license file into a Base64-encoded string. On Linux-based systems, you can do this with the base64 command from the GNU coreutils package. On Windows, you can use either the certutil command or the ToBase64String() method. Save the encoded string for later use.

Example: using the base64 utility on Linux

$ base64 -w 0 /path/to/license-file

Example: using the ToBase64String method on Windows

[convert]::ToBase64String([IO.File]::ReadAllBytes("X:path\to\license-file"))

Then, use the encoded string in the installation command:

rl-deploy install /path/to/installation-directory --encoded-key=your-license-contents-as-Base64-encoded-string --site-key=your-site-key --no-tracking

Python workaround:

python3 -m rldeploy install /path/to/installation-directory --encoded-key=your-license-contents-as-Base64-encoded-string --site-key=your-site-key --no-tracking

Security best practices: Protect your keys

If your tools and workflows support it, you can use environment variables to store the encoded key and the site key. Make sure to password-protect or encrypt them if possible and treat them as any other sensitive information.

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.