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

Option	Description
--scan-purl, --purl	Required. 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, --path	Required. 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, --profile	Specify 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, --report	Save scan results to an rl-protect.json analysis report. You can provide a custom filename for the report.
--check-deps, --check-dependencies	Specify 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-depth	Specify 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.
--concurrency	Specify the number of concurrent scan threads to use for looking up dependencies, as an integer value.
--return-status	Return the scan result as an exit code. 0 = PASS, 1 = all other statuses.
--config-path	Specify the path to a custom config.info file with connection settings that rl-protect should use for the scan.
-h, --help	Display usage information and exit.

Output formatting options

Option	Description
--concise	Display summarized scanning results in the command output.
--fail-only	Show only failing dependencies in the command output.
--show-errors	Include package lookup errors (if there are any) in the command output.
--no-tracking	Don't display progress bars.
--no-color	Don'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.

Option	Description
--connection-id, --connect-id	Specify a connection name you previously configured with the rl-protect server command. If not specified, the default connection is used.
--rl-token	Provide the token for your Spectra Assure Community account. Community tokens have the prefix rlcmm
--ca-path	Path 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.

Option	Description
--connection-id, --connect-id	Specify a connection name you previously configured with the rl-protect server command. If not specified, the default connection is used.
--rl-portal-server, --rl-server	Name of the Spectra Assure Portal instance associated with your account (example: my.secure.software/company).
--rl-portal-org, --rl-org	Name 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-group	Name 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-token	Provide the token for your Spectra Assure Portal account. Portal tokens have the prefix rls3c
--ca-path	Path to the directory where CA certificates are stored.

Proxy settings

Option	Description
--proxy-server	Use this parameter to provide the server URL for optional local proxy configuration.
--proxy-port	Use this parameter to provide the network port for optional local proxy configuration.
--proxy-user	Use this parameter to provide the user name for optional local proxy authentication. Must be used together with --proxy-password.
--proxy-password	Use this parameter to provide the password for optional local proxy authentication. Must be used together with --proxy-user.

Logging options

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