Skip to main content

scan

Description​

Scans dependencies found in package manifest files and checks them for security risks by performing API lookups against Spectra Assure Community data. To successfully perform the scan, users must authenticate to the APIs with a token either for a Community account or a Portal account.

The rl-protect scan command supports scanning any of the following:

  • Single package by its package URL (PURL) (rl-protect scan pkg:npm/react@19.1.5)
  • Multiple packages by their PURLs (rl-protect scan pkg:pypi/requests,pkg:pypi/django)
  • Full manifest file (rl-protect scan package.json)

Scanning capabilities can be configured through a standardized JSON file called rl-profile. The configuration profile specifies which SAFE Assessment results should be ignored, enforced, and converted to a warning, as well as which packages are always allowed or blocked, and which policy rules to override. Configuration options min_package_age and min_version_age control the age threshold, so that packages and versions will only be allowed if they have been published for the specified number of days.

By default, rl-protect includes a set of configuration profiles created and approved by ReversingLabs:

  • 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 and most secure profile; used automatically when the scan profile is not specified in the scan command.

Users can also create their own configuration profiles to enforce package governance rules. Custom profiles must conform to the official rl-profile schema.

To specify which profile to use, add the --scan-profile parameter to the rl-protect scan command. If this parameter is not specified, hardened profile is used by default for Community accounts. For Enterprise (Portal) accounts, an existing profile is imported from the Portal.

Any failing condition is sufficient to fail the scan. By default, the command produces verbose results and each fail/warning is individually logged. To shorten the output, users can add the --concise and --fail-only parameters to the command. Full scan results can be exported as a JSON file with the --save-report parameter.

Log files can also be saved in the CEF format according to the following schema:

CEF:0|ReversingLabs|rl-protect|1.0.0|<PASS|(FAIL|WARN-CATEGORY)>
|<Log Label>|<Severity>|dvchost=hostname cs1Label="Dependency" cs1="PURL"

CEF severity mapping:

PASS --- N/A               0
PASS --- Other:            1
WARN --- Licenses:         1
WARN --- Secrets:          2
WARN --- Hardening:        3
WARN --- Vulnerabilities:  4
WARN --- Tampering:        5
WARN --- Malware:          5
WARN --- Repository:       6
WARN --- Governance:       6
FAIL --- Other:            6
FAIL --- Licenses:         6
FAIL --- Secrets:          7
FAIL --- Hardening:        7
FAIL --- Vulnerabilities:  8
FAIL --- Tampering:        9
FAIL --- Malware:          9
FAIL --- Repository:      10
FAIL --- Governance:      10

Usage​

rl-protect scan <path|purl> [<connection-id>][<options>]

rl-protect scan --scan-path=<file-path> [<connection-id>][<options>]

rl-protect scan --scan-purl=<csv-purl-list> [<connection-id>][<options>]

Options​

Scanning options​

OptionDescription
--scan-purl, --purlRequired. One or more comma-separated package URLs (PURLs) of open source software packages that you want to check for security risks before installing them. PURLs must be in the format [pkg:type/]<project></package><@version> (for example, pkg:npm/react@19.1.5). If the version part of the PURL is omitted, rl-protect retrieves information for the latest available package version matching the specified name. This parameter is mutually exclusive with --scan-path (they cannot be used in the same command).
--scan-path, --pathRequired. Path to a package manifest file that you want to scan with rl-protect. This parameter is mutually exclusive with --scan-purl (they cannot be used in the same command).
--scan-profile, --profileSpecify the name of a pre-configured profile or the path to a file that contains a custom rl-profile configuration. Pre-configured profile names are: minimum, baseline, hardened. If this parameter is not specified, hardened profile is used by default for Community accounts. For Enterprise (Portal) accounts, an existing profile is imported from the Portal.
--save-report, --reportSave scan results to an rl-protect.json analysis report. You can provide a custom filename for the report.
--check-deps, --check-dependenciesSpecify one or more dependency types that rl-protect should check when scanning. Types can be specified as comma-separated values. If using this parameter, at least one of the following values is required: release, develop. Values transitive and optional are not required, but if you want to specify them, one of the required values must be present in the command.
--transitive-depthSpecify how many levels deep should rl-protect scan transitive dependencies, as an integer value. The default value is 1. This parameter can only be used if --check-deps=transitive is specified in the command.
--concurrencySpecify the number of concurrent scan threads to use for looking up dependencies, as an integer value.
--return-statusReturn the scan result as an exit code. 0 = PASS, 1 = all other statuses.
--config-pathSpecify the path to a custom config.info file with connection settings that rl-protect should use for the scan.
-h, --helpDisplay usage information and exit.

Artifact options (Python)​

Option compatibility

Artifact options only work for Python (PyPI) dependencies. Trying to use them with other types of dependencies has no effect.

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

The --target-* options let you specify a target environment so that rl-protect selects and scans the specific artifact that would be installed there. In this way, artifact selection mirrors what pip would choose for the same environment.

If rl-protect cannot find a Python wheel compatible with the options you specified, it falls back to the version's source distribution when it exists. If the source distribution is not available, no artifact is selected.

Artifact selection is enabled as soon as you use any of the --target-* options with rl-protect. Because artifact selection is PyPI-specific, the --target-python option is required if you want to use any of the other options.

Specifying the platform

You can specify the target platform in two ways. Use whichever is more convenient — but not both at the same time. If you provide both formats, rl-protect selects artifacts matching either format (their union), rather than letting one override the other. This usually widens the selection more than intended, so it is more efficient to specify just one format to target a single platform.

1) With --target-platform

This option accepts either a preset (a user-friendly name such as linux-x86_64 or windows-x64) or an explicit platform tag (such as manylinux_2_28_x86_64 or win_amd64).

Presets represent sensible baselines (glibc 2.28, musl 1.2, macOS 11.0), so when you need a different baseline, use an explicit tag.

PresetPlatform 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-x86win32
windows-arm64win_arm64
Example command with platform preset
rl-protect scan pkg:pypi/numpy@2.2.0 \
  --check-deps=release \
  --target-python=3.12 \
  --target-platform=linux-x86_64

2) With --target-os and --target-arch

You can compose the platform from its part with these two options. They must be used together, and it is not recommended to use them if --target-platform is already provided in the command.

Optionally, --target-libc can be added to further specify the platform for Linux use-cases. Both --target-os and --target-libc accept an optional :version suffix that defines the starting version for rl-protect, which then accepts artifacts built for that version or newer.

Example command with composed platform
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

Specifying the interpreter and ABI

By default, rl-protect targets CPython (cp) and derives the compatible ABIs from the Python version specified with --target-python. To override these defaults, use the --target-implementation (for example, pp for PyPy) and --target-abi (for example, abi3 for stable-ABI wheels) options.

OptionDescription
--target-pythonSpecify the Python version of the artifact you want to select (e.g. 3.12 or 312). This option is required if you want to use artifact selection. If you use --target-python without specifying a platform, rl-protect targets the same platform as on the machine running the scan.
--target-platformSpecify the platform tag (e.g. manylinux_2_28_x86_64) or preset (e.g. linux-x86_64) of the artifact you want to select. To specify multiple tags in one command, repeat the option.
--target-osSpecify the operating system of the artifact you want to select - linux, macos, or windows. This option must be used together with --target-arch. Optional :version can be used to specify the minimum version for macOS deployments (e.g. macos:12.0).
--target-archSpecify the CPU architecture of the artifact you want to select - x86_64, x86, or arm64. This option must be used together with --target-os.
--target-libcApplies to Linux only. Specify the libc variant used by the artifact you want to select - glibc, musl, or none (default on Linux: glibc). Optional :version can be used to specify the minimum version (e.g. glibc:2.34 or musl:1.2).
--target-implementationSpecify the interpreter of the artifact you want to select - cp (default), pp, jy, ip, or py.
--target-abiSpecify the ABI (Application Binary Interface) tag of the artifact you want to select (e.g. cp312, abi3, or none). To specify multiple tags in one command, repeat the option.

Output formatting options​

OptionDescription
--conciseDisplay summarized scanning results in the command output.
--fail-onlyShow only failing dependencies in the command output.
--show-errorsInclude package lookup errors (if there are any) in the command output.
--no-trackingDon't display progress bars.
--no-colorDon't add color to the output.

Connection options​

Community account

If you haven't previously saved the token to the default connection or created a new connection with the rl-protect server command, then the --rl-token parameter is required.

OptionDescription
--connection-id, --connect-idSpecify a connection name you previously configured with the rl-protect server command. If not specified, the default connection is used.
--rl-tokenProvide the token for your Spectra Assure Community account. Community tokens have the prefix rlcmm
--ca-pathPath to the directory where CA certificates are stored.

Enterprise (Portal) account

If you haven't previously saved your Portal details to the default connection or created a new connection with the rl-protect server command, then the following parameters are required: --rl-server, --rl-org, --rl-token.

OptionDescription
--connection-id, --connect-idSpecify a connection name you previously configured with the rl-protect server command. If not specified, the default connection is used.
--rl-portal-server, --rl-serverName of the Spectra Assure Portal instance associated with your account (example: my.secure.software/company).
--rl-portal-org, --rl-orgName of the Spectra Assure Portal organization. The organization must exist on the Portal instance specified with --rl-portal-server. The user account authenticated with the token must be a member of the specified organization and have the appropriate permissions. Organization names are case-sensitive.
--rl-portal-group, --rl-groupName of the Spectra Assure Portal group. The group must exist in the Portal organization specified with --rl-portal-org. Group names are case-sensitive.
--rl-tokenProvide the token for your Spectra Assure Portal account. Portal tokens have the prefix rls3c
--ca-pathPath to the directory where CA certificates are stored.

Proxy settings

OptionDescription
--proxy-serverUse this parameter to provide the server URL for optional local proxy configuration.
--proxy-portUse this parameter to provide the network port for optional local proxy configuration.
--proxy-userUse this parameter to provide the user name for optional local proxy authentication. Must be used together with --proxy-password.
--proxy-passwordUse this parameter to provide the password for optional local proxy authentication. Must be used together with --proxy-user.

Logging options​

OptionDescription
--log-fileSpecify the path where you want to store the log file. Logs are kept in the CEF format.
--log-labelSpecify a custom label to identify the logging source in SIEM (maximum 511 characters).
--log-levelSpecify the logging level as one of the following values: pass, warning, fail. The default value is fail (only failed events are logged).

Examples​

Scan multiple packages​

In this example, we're scanning two packages at the same time. Package names are comma-separated. Because we're not specifying the package version, the information is retrieved for the latest published version of each package.

In the output, the specified packages are represented first and marked as COMPONENT, followed by dependencies (if applicable). For scanned dependencies, the output indicates which of the specified packages is the dependent.

rl-protect scan pkg:npm/cli-color,pkg:npm/apexcharts --check-deps=release,develop --no-tracking