Skip to main content

scan

Active license required

Description​

Analyzes a software package for security and software quality issues.

Scanning is performed as a recursive static file decomposition operation. The goal is to explore and itemize included or referenced software components. Each discovered file is evaluated against enabled policy checks. Any policy violations are reported alongside the file that triggered them.

By default, the software package is automatically copied to the package store before performing the analysis. This is done to enable diffing (comparison) between package versions in case the rl-secure version or configuration changes. Consequently, the total size of your package store directory is expected to increase over time.

Referencing files instead of copying them

If you need to preserve disk space, you can link to a software package instead of creating a copy in the package store. This is done by creating symbolic links with the --keep-reference option.

Use this option carefully. Do not remove the linked software package files from their original location if you haven't first removed the packages from the package store. The package store may end up in an unrecoverable error state if symbolic links are broken.

The analyzed software package is added to the package store and assigned a unique identifier in the form of a package URL ([pkg:type/]<project></package><@version>). This special URL is used by rl-secure to associate the analyzed file with a project and package as a version, and to perform various actions on it with different commands.

Scanning will fail if the package version specified in the command is already present in the package store. Use the --replace option if you need to overwrite an existing package version.

Recovering from errors

If the scan command fails to analyze your software packages, make sure to run rl-secure clean after resolving the issue, and then attempt the scan again.

After you've successfully scanned a software package, you can:

Diffing​

You can use rl-secure to compare a package version against another, usually preceding, version in the same project. This is called diffing, and it creates the version diff - an overview of changes and differences between compared package versions.

However, diffing requires that both package versions are analyzed with the same rl-secure version and configuration.

To compare two package versions, use the --sync-with option to specify the older version (referential; the one you want to compare against) when scanning the newer package version:

rl-secure scan /home/armando/my-package.jar pkg:rl/my-project/my-package@1.0.2 --sync-with=1.0.1

That will check if synchronization is required and automatically reanalyze package versions when necessary.

Then, you can use rl-secure report to generate the SAFE report (rl-html) for the newer package version that will include the diff information.

Diff workflow

For more detailed instructions, check out the diff guide.

Reproducible build artifacts​

You can perform reproducibility checks for a previously analyzed package version by adding a reproducible build artifact to it.

In this use-case, the package version is treated as a collection of artifacts:

  • the main package version artifact (usually the "representative" file for a software version, or the build you intend to release at some point)
  • the reproducible build artifact (a build of the same software version created in a different environment or build system than the main artifact).

A reproducibility check is performed by analyzing the reproducible build artifact and comparing it to the main package version artifact. Specifically, rl-secure looks for behavioral and functional differences that may indicate tampering or other types of compromise in the build system.

Analyzing reproducible build artifacts does not use your analysis capacity.

To analyze a reproducible build artifact, append the ?build=repro option to the package URL of a previously analyzed package version, like in the following example:

rl-secure scan /home/armando/my-package-repro.jar pkg:rl/my-project/my-package@1.0.2?build=repro

Each package version in a package store can only have one reproducible build artifact at a time.

To add a different reproducible build artifact to a version that already has one, use the --replace option with the scan command. That will overwrite the existing reproducible build artifact and perform new reproducibility checks.

Diffing reproducible builds

Reproducible build artifacts cannot be diffed against other package versions. Diff-related options in rl-secure commands are incompatible with the ?build=repro option.

Password-protected files​

By default, rl-secure can scan password-protected files, but cannot decrypt them to extract their contents. This in turn produces incomplete analysis results.

To decrypt a password-protected file, you can use the --password option when scanning the file to provide its password.

If you prefer not to type the passwords directly into the terminal, you can provide the path to a file containing a list of passwords with the --password-list option.

If you do not want to disclose the path to a file containing a list of passwords, you can provide its Base64-encoded contents with the --encoded-password-list option.

Note that you can also use all three password options in the following ways:

  • --password with --password, --password-list and/or --encoded-password-list
  • --password-list with --password-list, --encoded-password-list and/or --password
  • --encoded-password-list with --encoded-password-list, --password and/or --password-list

When you specify either of those (or both), you need to provide the --vault-key value as well. That will save the passwords to your package store password vault and associate them with the package version you're scanning.

File format support

Decrypting password-protected files is supported only for a limited set of file formats.

In the list of supported formats, those with a checkmark in the "Password Support" column can be decrypted and extracted with passwords saved in the vault.

For each package version, you can save any number of passwords to the password vault. You can change the saved passwords at any time with the vault update command.

When reprocessing password-protected files with the sync command, you don't need to provide their passwords, but you must provide the vault key.

Performance​

General guidance on the time required to complete a scan is that it typically takes less than it takes to compile and build a package.

Analysis requires a temporary work directory, which is automatically created by the scan command. If you don't specify the work directory, the default one from the package store is used. This can cause a significant performance impact if a large package is being added to a remote storage directory. To speed up the analysis in such cases, you can specify a local work directory with the --work-dir option.

Scan analysis time directly correlates to the number of available IOPS (input/output operations per second). Keeping files local to the CLI, upgrading to a faster drive or using a RAM disk can improve performance. Check the CLI system recommendations page for more details on recommended hardware configurations.

When performing many scans at the same time, it is recommended to keep the number of threads per running scan instance evenly distributed. This ensures that each scanner instance is being used optimally. A user-configurable parameter that impacts performance of scans running in parallel is --concurrency. The intended use of this parameter is to limit performance per scanner instance to reduce the load.

By default, rl-secure is optimized for maximum resource utilization. In most cases, the concurrency parameter does not need to be specified, and the operating system will handle resource management.

Automatic updates

To detect the latest supply chain threats, rl-secure may perform a self-update before running the scan.

Licensing​

Scanning a software package deducts its size (file size on disk) from the monthly analysis capacity of the user's license.

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.

Shared capacity

Since CLI and Portal share a ReversingLabs cloud account, the monthly analysis capacity is split between them and can only be configured in the Portal interface.

The following example illustrates the error you would receive if you tried to scan a package larger than the allowed maximum file size 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)

Usage​

rl-secure scan <file-path> <purl> [<options>]

rl-secure scan --file-path=<file-path> --purl=<purl> [<options>]

Options​

OptionDescription
--file-pathRequired. Path to the package file you want to scan. The file path must be specified first in the command, before the package URL (and any other options).
-p, --purlRequired. Package URL to associate with the scanned file, in the format [pkg:type/]<project></package><@version>. If the project or package don't already exist in the store, they are automatically created.
--replaceReplace the package version if it already exists in the store.
?build=reproAnalyze a reproducible build artifact of the specified package version. This option must be appended to the package URL of the file that will be associated with an existing package version as one of its builds, in the format [pkg:type/]<project></package><@version?build=repro>. Analyzing reproducible build artifacts does not use your analysis capacity.
--sync-withEnsure two package versions are scanned with the same settings before performing a diff check. The diff is a comparison of two package versions. Use this option to specify the package version that will be used as the reference version (the version you want to compare against). This option automatically re-processes package versions if necessary.
--work-dirSpecify the path to a work directory for temporary files. If not specified, it is created in the store root.
--concurrencySpecify the number of concurrent scan threads to use when running multiple scans at the same time. When specified, this parameter limits performance per scanner instance to balance their load. Default value: max
--keep-reference        Instead of copying the file you want to analyze into the package store, create a symlink to it. Use this option carefully, as broken symlinks may cause the package store to end up in an unrecoverable error state.
--no-trackingDon't display progress bars.
--passwordSpecify the password that will be used to unpack password-protected files. You can provide multiple passwords at once as a comma-separated list: --password example1, Example2, exampl3. Note that these values are case-sensitive.
--password-listSpecify the path to a password list that will be used when trying to unpack password protected files. You can provide multiple password list files at once: --password-list path/to/file.txt --password-list ./another-file.txt.
--encoded-password-list, --encoded-listSpecify the Base64-encoded contents of a password list that will be used when trying to unpack password protected files. You can provide multiple Base64-encoded password list files at once: --encoded-password-list FirstBase64EncodedString --encoded-password-list SecondBase64EncodedString.
--vault-keyProvide the password vault key. Required if a password is provided. Note that this value is case-sensitive and can be changed at any time.
-h, --helpDisplay usage information and exit.
-s, --rl-storePath to an initialized package store containing the package URL to scan. If you don't specify the path, the current directory is used.

Examples​

Scan a software package​

This example scans the 1.0.2 version of an example package, and ensures that the scan is synchronized with the previously scanned 1.0.1 version. Since the older version was processed with a different scan configuration, both packages are reanalyzed.

This enables us to subsequently run rl-secure report and create a diff between the two package versions.

The command expects the package store to exist in the current directory. Use the -s or --rl-store options to provide an alternative path to the package store.

rl-secure scan /home/armando/my-package.jar pkg:rl/my-project/my-package@1.0.2 --sync-with=1.0.1

Replace a package version​

This example attempts to scan the 1.0.2 version of an example package while the same version already exists in the package store.

When rl-secure warns about the conflict, we run the scan command again with the --replace option to overwrite the existing version.

The command expects the package store to exist in the current directory. Use the -s or --rl-store options to provide an alternative path to the package store.

Input

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

Output

Fatal error: version my-project/my-package@1.0.2 already exists. To replace it, use --replace

Scan a password-protected file​

This example scans a password-protected file as the 1.0.3 version of an example package. When sending such files to analysis, you need to provide the password rl-secure will use to decrypt them and extract their contents.

There are 3 ways to provide the password for a package version:

  • as a literal password string with the --password parameter
  • as a path to the file containing a list of passwords (one on each line) with the --password-list parameter
  • as Base64-encoded contents of a password list file in a string format with the --encoded-password-list parameter

To store these passwords in the password vault for your package store, you need to provide the vault key with --vault-key, as well.

The command expects the package store to exist in the current directory. Use the -s or --rl-store options to provide an alternative path to the package store.

rl-secure scan ~/test_file.zip pkg:rl/my-project/my-package@1.0.3 --password TESTPASS --vault-key SECRETKEY -s /home/armando/my_repository/

To check that the password has been saved to the vault and confirm the package version has been decrypted successfully, use the rl-secure list command.

rl-secure list pkg:rl/my-project/my-package@1.0.3 --all

The output should indicate that the password vault is in use, and contain the analysis summary for your package version.