Skip to main content

inspect

Description​

Displays detailed analysis results for the selected package version.

Use this command to identify security and software quality issues discovered during analysis. Detected issues are associated with files they affect. Their remediation can be planned and prioritized by the issue type, priority, severity, or effort required to resolve them.

When used with its filtering options, inspect can show the following:

  • detected and suppressed software quality issues,
  • a comprehensive list of active and triaged vulnerabilities,
  • detected behaviors,
  • detected malicious and suspicious software components,
  • sensitive information and exposed secrets detected within packages.
Default output

When no option is specified, the --[show]-issues output is shown by default.

Depending on the issue type, a different person within the organization might be assigned to review or remediate. While this varies from one organization to another, general triage guidance is that the malware incidents get investigated by a security team. Container deployment issues should be handled by DevOps, letting the developers focus on vulnerabilities and other software quality issues.

If an organization has an application security team, its members can further review mitigation coverage gaps, software bill of materials, and vet third-party component behaviors.

To completely resolve a reported issue means to address it on each of the files reported in the violations list.

Status of reproducible build artifacts​

If a package version has a reproducible build artifact, you can view its status independently of the main artifact by appending the ?build=repro option to the package URL in the inspect command.

All supported inspect command options can be used together with this option to filter the information about the reproducible build artifact.

To view the status of reproducible build checks for a package version, use the checks command.

Usage​

rl-secure inspect <purl> [<options>]

rl-secure inspect --purl=<purl> [<options>]

Options​

OptionDescription
-p, --purlRequired. Package URL for which to display analysis results, in the format [pkg:type/]<project></package><@version>
?build=reproInstead of showing detailed analysis results for the main package version artifact, show the results for the reproducible build artifact. The option must be appended to the package URL like in the following example: pkg:rl/my-project/my-package/version@1.0?build=repro. When this option is used for a package version that doesn't have any reproducible build artifacts, the command exits with an error.
--all, --show-allShow all available metrics. When used together with other options, it implicitly satisfies their usage conditions. For example, if an option can only be used together with --secrets, you can use it with --all instead, and it will work without having to specify --secrets.
--issues, --show-issuesShow issues. This option is used by default when no other option is specified.
--dsc-sortSpecify the criteria for sorting the output (priority, severity, effort, count) in descending order.
--asc-sortSpecify the criteria for sorting the output (priority, severity, effort, count) in ascending order.
-s, --rl-storePath to an initialized package store containing the package URL. If you don't specify the path, the current directory is used.
--diff-withUsed for creating diffs (comparisons) between two package versions (the version for which you're generating the report and another, usually preceding version). Both package versions must be in the same project and package. Specify a previously analyzed package version to include diff information in the report. Only the version part of the package URL needs to be specified. Does not work with reproducible builds.
--no-filesDon't show the list of files in which an issue was detected. Applies to all issue types, but cannot be used together with the --evidence option for secrets.
--no-colorDon't add color to the output.
-h, --helpDisplay usage information and exit.

Filter issues by status​

OptionDescription
--fail, --fail-onlyShow only components with FAIL status. Can't be used together with --pass. Must be used with --issues or --all to produce meaningful output.
--pass, --pass-onlyShow only components with PASS status. Can't be used together with --fail. Must be used with --issues or --all to produce meaningful output.
--blockers, --level-blockersShow only the issues that are preventing migration to the specified SAFE Level. Specify the level as an integer value from 1 to 5. For example, --blockers=4 indicates if there are any issues blocking the upgrade to SAFE Level 4.

Filter issues by type​

OptionDescription
--malware, --show-malwareShow malware.
--behaviors, --show-behaviorsShow behaviors. When package community information is available, behavior prevalence can be one of the following: Common, Uncommon, Anomalous, Important, Malicious.

Common = the detected behavior is often found in the community the component belongs to.

Uncommon = the detected behavior is rare within the community the component belongs to.

Anomalous = the detected behavior was never seen in the community the component belongs to.

Important = the detected behavior is not malicious but should be prioritized for code intent review.

Malicious = the detected behavior is seen only in malicious packages within the community the component belongs to.

If no prevalence information for a behavior is currently available, the CLI output will state that.
--cves,
--vulnerabilities,
--show-cves		Show vulnerabilities. Can only be sorted by severity.
--secrets, --show-secretsShow sensitive information and exposed secrets (such as service credentials, tokens, and private keys). The exposure status can be one of the following: Exposed, Suppressed, Unknown.

Exposed indicates when the secret was first recorded in the ReversingLabs cloud, and that it is newer than the configured leak threshold. The threshold is used to define the age after which secrets are no longer considered active (usually according to organization password policies).

Suppressed indicates when the secret was first recorded in the in the ReversingLabs cloud, and that it is older than the configured leak threshold. It is assumed the secrets older than the threshold have been rotated or revoked in the meantime. Therefore, they're no longer considered exposed.

Unknown indicates the secret has no records in the ReversingLabs cloud, and it's therefore not possible to calculate how long it has been exposed.

You can configure the secrets exposure time by modifying the policy configuration files.
--endpoints,
--with-endpoints		Must be used together with --secrets and --evidence. Shows the liveness status for a verified secret per endpoint.
--evidence, --with-evidenceMust be used together with --secrets. Shows secret exposure window time (if that information is available) and points to the evidence in specific files within a package. For text-based files, the output shows the exact line number where the secret was detected.

Examples​

Show SAFE Levels upgrade blockers​

This example shows how to use the --blockers option to identify issues in a package that prevent your software from reaching a higher level of maturity.

In this example, the scan level is set to 3 in the policy configuration for this specific project. That means we want all package versions in the project to pass level 3.

We also want to know if our packages would pass or fail on the next level, so we're looking for issues that are considered blockers in our upgrade path to level 4.

For threat hunting (TH) policies, the triggered behavior ID and its description are shown under the Root Cause part of the CLI output. This allows you to pinpoint the software behaviors preventing you from reaching the desired SAFE Level.

rl-secure inspect pkg:rl/my-project/my-package@1.0 --blockers=4

Show secrets with evidence and endpoint liveness​

This example shows how to use the inspect command to focus on and prevent sensitive information exposure in your packages.

The --secrets option filters the command output to display only the issues related to secrets. For example, if a file within a package contains AWS credentials or has embedded private keys, the output will include the file.

Adding the --evidence option makes the command output more informative. For every detected secret, it shows the exposure time window (if available) and points to the file contents that triggered the detection. This helps you understand the severity of the issue and address it more rapidly by locating the source of the problem.

Using the --endpoints option displays the liveness status (if supported) of every detected secret on each service endpoint. The time when the liveness check was last performed is displayed next to the liveness status. This allows you to pinpoint the secrets that are still used on specific services and can therefore be exploited.

In this example, there are two instances of secrets exposure in the analyzed package.

The first issue (starting at Line 2 in the Output tab) is categorized as "commonly distributed sensitive data". Technically, this type of sensitive information is not considered secret, and it usually indicates the presence of testing data that has already been shared in public. Therefore, this issue is assigned a lower priority (P4) by default. Liveness status is not supported for this secret type, as indicated by the Liveness line. The Evidence line shows where the secret appears in the file.

The second issue (starting at Line 11 in the Output tab) is assigned P0 priority. Presence of active web service access credentials has been detected in the package and it requires further investigation. Endpoints where this secret is considered active are indicated in the output under Evidence: [x] ACTIVE on.

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 (as shown in the "Extended input" tab).

rl-secure inspect pkg:rl/my-project/my-package@1.0 --secrets --with-evidence --with-endpoints

Show malicious components​

This example displays the malicious components contained within an NPM ua-parser-js package. More specifically, version 0.7.29 contains a known software supply chain attack.

Malicious components were detected by a few different threat detection technologies the ReversingLabs analysis engine relies on. The command output displays the most accurate result, which in this case is a hash-based detection that was vetted by our Threat Research team.

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 (as shown in the "Extended input" tab).

rl-secure inspect pkg:rl/npm/ua-parser-js@0.7.29 --malware

Display known vulnerabilities​

This example shows how to focus the analysis summary on CVEs with the --vulnerabilities option. This approach is ideal for quick failure triage and integration with CI systems.

We previously added Apache Solr 8.10.0 to the package store with the scan command. Version 8.10.0 contains a known vulnerability: CVE-2021-44228 (Log4Shell). Since this vulnerability can have a high impact, CISA issued a patching mandate to United States government agencies.

If you want to get a cleaner output without the list of files where each vulnerability was detected, use the --no-files option.

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 (as shown in the "Extended input" tab).

rl-secure inspect pkg:rl/apache/solr@8.10.0 --vulnerabilities --no-files

Show detected behaviors​

This example shows how to focus the analysis summary on detected behaviors with the --behaviors option. We're displaying behaviors based on their IDs, in ascending order.

For every detected behavior, you can see what possibly triggered it and in which file it was found. This helps you address the issue more rapidly by locating the source of the problem.

When available, the prevalence information can help you understand how common the behavior is in the package community.

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 (as shown in the "Extended input" tab).

rl-secure inspect pkg:rl/nupkg/winscphelper@1.0.13 --behaviors

Show failing issues ordered by effort​

This example shows how the inspect command can help with prioritization. We're displaying the highest priority issues sorted by the least effort required to remediate.

Combining the --fail-only option with --asc-sort to order issues by remediation effort (from lowest to highest) produces an actionable list of issues that are high-impact and easy to fix.

In this case, the presence of private certificates is one of the issues in the command output that require investigation. Given that the policy violation filenames imply testing-only usage, the next recommended step is to add them to the list of suppressed issues.

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 (as shown in the "Extended input" tab).

rl-secure inspect pkg:rl/apache/solr@8.10 --issues --fail-only --asc-sort=effort

Show diff analysis summary​

This example shows how to use the inspect command to display all issues introduced since the older version.

We previously scanned both the older (8.10) and the newer version (8.11.3). With the report command, we first generated separate reports for each version and then a diff report between them.

If all the conditions have been met, you can now display the diff analysis information in the CLI output. This allows you to view policies triggered on diff, as well as the issues that affect the newer (8.11.3) 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 (as shown in the "Extended input" tab).

rl-secure inspect pkg:rl/apache/solr@8.11.3 --diff-with=8.10