Metadata-Version: 2.1
Name: rl-protect
Version: 1.1.1.0
Summary: Software package scanner tool by ReversingLabs.
Author: ReversingLabs
Author-email: secure.software@reversinglabs.com
Requires-Python: >=2.7
Description-Content-Type: text/markdown
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Topic :: Security

# rl-protect by ReversingLabs &middot; [![RL Status Badge](https://secure.software/pypi/badge/rl-protect)](https://secure.software/pypi/packages/rl-protect)

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](https://docs.secure.software/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](https://docs.secure.software/).


## 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](https://secure.software/). 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](https://docs.secure.software/api/generate-api-token). 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:

| Preset | Platform tag |
| --- | --- |
| `linux-x86_64` (aliases: `linux-x64`, `linux-amd64`) | `manylinux_2_28_x86_64` |
| `linux-aarch64` (alias: `linux-arm64`) | `manylinux_2_28_aarch64` |
| `linux-musl-x86_64` (alias: `linux-musl-x64`) | `musllinux_1_2_x86_64` |
| `linux-musl-aarch64` (alias: `linux-musl-arm64`) | `musllinux_1_2_aarch64` |
| `macos-arm64` (aliases: `macos-aarch64`) | `macosx_11_0_arm64` |
| `macos-x86_64` (aliases: `macos-x64`, `macos-intel`) | `macosx_11_0_x86_64` |
| `windows-x64` (aliases: `windows-amd64`, `win64`) | `win_amd64` |
| `windows-x86` | `win32` |
| `windows-arm64` | `win_arm64` |

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

| Flag | Meaning |
| --- | --- |
| `--target-python` | Target Python version, e.g. `3.12` or `312`. Required to enable artifact selection. |
| `--target-platform` | Platform tag (e.g. `manylinux_2_28_x86_64`) or preset (e.g. `linux-x86_64`). Repeatable and comma-separated. |
| `--target-os` | Target OS: `linux`, `macos`, or `windows` (must be given with `--target-arch`). Optional `:version` as a macOS deployment-target floor, e.g. `macos:12.0`. |
| `--target-arch` | Target CPU architecture: `x86_64`, `x86`, or `arm64` (must be given with `--target-os`). |
| `--target-libc` | Target Linux libc: `glibc`, `musl`, or `none` (default on Linux: `glibc`). Optional `:version` as a floor, e.g. `glibc:2.34` or `musl:1.2`. |
| `--target-implementation` | Target interpreter: `cp` (default), `pp`, `jy`, `ip`, or `py`. |
| `--target-abi` | Target ABI tag, e.g. `cp312`, `abi3`, or `none`. Repeatable and comma-separated. |

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](https://docs.secure.software/concepts/basic-concepts#policy), 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](https://docs.secure.software/cli/rl-profile-schema).


## Support

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

