rl-protect by ReversingLabs ·

rl-protect is a CLI tool that scans manifest files for popular software package formats (npm, PyPI, RubyGems) to identify threats in open source dependencies before they are installed. It can also be used for quick security checks by providing a specific software package URL. In both cases, rl-protect connects to the Spectra Assure Community API to retrieve the latest information on analyzed open source software packages.

Spectra Assure is a software supply chain security platform created by ReversingLabs to help organizations develop and release software with confidence. To provide a shift-left solution for software producers who work with third-party open source packages, ReversingLabs developed rl-protect.

This guide explains how to use rl-protect. For more details, visit the official Spectra Assure documentation.

Installation

rl-protect requires Python 3.x.

It can be installed on the following systems and architectures:

• Windows 10 and later, 64-bit
• Linux x86 (all major distributions), 64-bit

To install the latest version of rl-protect from PyPI, run:

pip install rl-protect

To confirm rl-protect is successfully installed, run:

rl-protect --version

How to use rl-protect

After installing rl-protect to your system, set up the token required for authenticating to the Spectra Assure Community API.

There are two ways to obtain the token:

1. Create a free account on the Spectra Assure Community website. In your user profile, create an access token with a custom name and expiration date. Copy and save the token for later use. Community tokens have the prefix rlcmm.

After creating a token in your Spectra Assure Community profile, use the rl-protect server command to configure the connection with the Community API.

The following command will associate your token with the default connection and save it in the rl-protect configuration. As a result, you won't have to input the token every time you use rl-protect.

rl-protect server connect \
  --rl-token=<your-community-token>

2. If you're currently a Spectra Assure Portal user, create a token in your Portal user profile. Set a name and expiration date for the token. Copy the token and save it for later use. Portal tokens have the prefix rls3c.

After creating a token in your Spectra Assure Portal profile, use the rl-protect server command to configure the connection with the Portal API.

The following command will create a new connection with the custom name portal-connection and save your token in the rl-protect configuration. As a result, you won't have to input the token every time you use rl-protect.

rl-protect server connect \
  --connection-id=portal-connection \
  --rl-token=<your-community-token> \
  --rl-portal-server=my.secure.software/example \
  --rl-portal-org=MyOrg \
  --rl-portal-group=MyGroup

When the connection is correctly configured, you can use the rl-protect scan command to scan an individual manifest file:

rl-protect scan package.json \
  --check-deps=develop,release

or to check the status of one or more software packages by specifying their PURLs:

rl-protect scan \
  pkg:pypi/requests@2.31.0,pkg:pypi/flask@3.0.0,pkg:pypi/cryptography@41.0.0 \
  --check-deps=release

In both cases, you should specify which types of dependencies to check (develop or release (one type is required); optional, transitive).

If you don't specify the connection-id in the scan command, the default connection is used automatically.

For more details on other supported scanning options, use the rl-protect scan --help command.

Selecting a specific artifact

A single package version usually publishes many artifacts. For example, one release of a PyPI package can ship dozens of wheels (one per Python version, operating system, CPU architecture, and libc) alongside a source distribution. By default, rl-protect resolves a dependency to its version and leaves the artifact unspecified, so the report is not tied to the exact binary that would be installed in a particular environment.

The --target-* flags let you describe a target environment so that rl-protect selects and scans the specific artifact that would be installed there. Selection mirrors what pip would choose for the same environment. It currently applies to PyPI dependencies only; for dependencies in other ecosystems the flags have no effect, and rl-protect prints a warning when a scan includes such dependencies.

Artifact selection is enabled as soon as you pass any --target-* flag. Because selection is PyPI-specific, --target-python is required whenever you use any of these flags:

rl-protect scan pkg:pypi/numpy@2.2.0 \
  --check-deps=release \
  --target-python=3.12 \
  --target-platform=linux-x86_64

If you pass --target-python on its own, without naming a platform, rl-protect assumes the platform of the machine running the scan.

Naming a platform

There are two ways to specify the target platform. Use whichever is more convenient — but not both at once (see Combining flags below).

The first way is --target-platform, which accepts either a preset (a friendly name such as linux-x86_64, macos-arm64, or windows-x64) or an explicit platform tag (such as manylinux_2_28_x86_64, macosx_11_0_arm64, or win_amd64). Presets bake in sensible baselines (glibc 2.28, musl 1.2, macOS 11.0); pass an explicit tag when you need a different baseline. This flag is repeatable and also accepts comma-separated values, so --target-platform=linux-x86_64,macos-arm64 is equivalent to passing it twice:

The second way is to compose the platform from its parts with --target-os and --target-arch (which must be given together), optionally adding --target-libc on Linux. Both --target-os and --target-libc accept an optional :version suffix that acts as a floor — rl-protect accepts artifacts built for that version or newer:

rl-protect scan pkg:pypi/cryptography@42.0.0 \
  --check-deps=release \
  --target-python=3.12 \
  --target-os=linux \
  --target-arch=x86_64 \
  --target-libc=glibc:2.34

Choosing the interpreter and ABI

By default rl-protect targets CPython (cp) and derives the compatible ABIs from the Python version. Override these with --target-implementation (for example pp for PyPy) and --target-abi (for example abi3 for stable-ABI wheels). Like --target-platform, --target-abi is repeatable and accepts comma-separated values.

Combining flags

--target-platform and the --target-os/--target-arch/--target-libc axis are two ways of describing the same thing. If you supply both, rl-protect selects artifacts matching either form (their union) rather than letting one override the other, which usually widens selection more than intended. rl-protect prints a warning in this case; specify just one form to target a single platform.

Flags reference

If rl-protect cannot find a wheel compatible with the target, it falls back to the version's source distribution when one exists; otherwise no artifact is pinned.

Configuration

By default, rl-protect includes a set of configuration profiles (called rl-profiles) that have been created and approved by ReversingLabs.

Those profiles are JSON files with settings that instruct rl-protect on how to apply Spectra Assure policies, and define which scanning results should be treated as failures or warnings.

The following profiles are provided when you install rl-protect:

• minimum (rl-oss-minimum.json) - blocks only malicious dependencies that were vetted by ReversingLabs threat analysts. This is the most permissive profile.

• baseline (rl-oss-baseline.json) - blocks malware, tampering, and actively exploited vulnerabilities. This profile is suitable as a starting point for typical development use-cases.

• hardened (rl-oss-hardened.json) - the default profile; used automatically when the scan profile is not specified in the scan command. As the least permissive and most secure profile, it applies governance rules related to software package age to minimize end-user deployment risks. Configuration options min_package_age and min_version_age in this profile control the age threshold. Packages and versions will only be allowed if they have been published for the specified number of days.

You can specify which profile to use with the --scan-profile parameter:

rl-protect scan package.json \
  --check-deps=develop,release \
  --scan-profile=baseline

You can also create your own rl-profile configuration files in addition to the predefined set. The configuration files must conform to the official rl-profile schema.

Support

To share your feedback or report any issues with rl-protect, send an email to support@reversinglabs.com