Skip to main content

list

Description​

Displays the contents of a package store as a nested list to showcase the project, package and version relationships.

Use this command to get a quick overview of the most pressing issues by leveraging various display options. You can get information for the whole package store at once, or focus on specific projects and packages.

You can change the output of the list command in the following ways:

  • filter out all passing or failing package versions
  • show the number of issues with their severity alongside the CI/CD status
  • display risk summary analysis per risk category for each package version

To get more information about a package version, use the rl-secure inspect command.

The difference between inspect and list is that list works with projects, packages, and package versions, while inspect works only with package versions. However, the output provided by inspect is much more detailed, and can be filtered by multiple criteria that are not available for the list command.

Risk assessment​

Software package analysis covers the most important software deployment risk categories. In the list command output, this information is represented as the risk assessment card when you use the --risks or --all options.

The risk assessment card is useful as a high-level, human-readable overview of the types of issues identified in your projects and packages.

In the command output, each risk category can have one of the following indicators:

  • x - the category caused the CI:FAIL status
  • ! - the category raised a warning
  • o - the category has no known issues and results in CI:PASS status
Example risk assessment card
rl-store: /home/armando/my-repository/
  / my-project
      / my-package
         @ [ L5:FAIL ] latest
           ----------------------------------------------------------------
           ( ISSUES: - <P0> [H] 20     [M] 47     [L] 210    [SUM] 277    )
           ----------------------------------------------------------------
           { L5:FAIL - Check (1/1) > Software package analysis            }
           ----------------------------------------------------------------
           [ Licenses        o No restricted license inclusions           ]
           [ Secrets         x 1 web service credentials found            ]
           [ Vulnerabilities x 2 patch mandated vulnerabilities           ]
           [ Hardening       o No vulnerability mitigation issues         ]
           [ Tampering       --- LICENSING: Entitlement restriction ---   ]
           [ Malware         o No evidence of malware inclusion           ]
           ----------------------------------------------------------------
           ( 10 policies were not evaluated during analysis               )
           ( 4 policy violations blocking attainment of L2                )
Risk categoryDescription
LicensesUse of restricted licenses within a project.
SecretsExposed private keys, certificates or source control.
VulnerabilitiesKnown software defects with an assigned CVE.
HardeningSoftware mitigation misconfigurations or inefficiencies.
TamperingCode, build system, or integrity validation tampering.
MalwareInclusion of malicious code behaviors or packages.

Any of these assessment categories can be disabled. This is determined by restrictions, also known as entitlements, put on your rl-secure license. When a category is disabled, its data is not included in the report and cannot be accessed in the terminal. For example, if Tampering is disabled, policy violations and raw tampering data is skipped during analysis.

RL-Levels and policy status​

While processing your packages, rl-secure uses a set of built-in policies to validate your software against a number of quality, behavior, and security criteria. If any of those policies have been disabled by the user or suppressed by RL-Levels settings, the list command output indicates that.

Read more about the RL-Levels feature in the conceptual documentation.

  / 7zip 
      / linux 
         @ [ L1:PASS ] 22            
           ----------------------------------------------------------------
           ( ISSUES: - <P4> [H] 0      [M] 0      [L] 1      [SUM] 1      )
           ----------------------------------------------------------------
           { L5:PASS - Check (1/1) > Software package analysis            }
           ----------------------------------------------------------------
           [ Licenses        o No restricted license inclusions           ]
           [ Secrets         o No sensitive information found             ]
           [ Vulnerabilities o No known vulnerabilities detected          ]
           [ Hardening       o No vulnerability mitigation issues         ]
           [ Tampering       o No evidence of software tampering          ]
           [ Malware         o No evidence of malware inclusion           ]
           ----------------------------------------------------------------
           ( 10 policies were not evaluated during analysis               )
           ( No policy violations blocking migration to L5                )

Policy status information and RL-Levels details are displayed below the risk categories in the risk assessment card.

Depending on your policy configuration and RL-Levels settings, the risk assessment card may include any of the following status messages.

Policy statusDescription
[N] policies were not evaluated during analysisIndicates that some policies were disabled when the package version was last analyzed. When a policy is disabled, it doesn't have any impact on the analysis result. Issues that would be detected by a disabled policy do not get reported at all.

A policy can be disabled for the whole package store, or only for specific projects and packages. You can check which exact policies are disabled in the *-policy.info configuration files in your package store.
[N] policies required for level attainment were disabledWarns the user that the level was attained artificially (by modifying policies). If a policy was modified in a way that relaxes the level requirements, L levels (RL-Levels) get converted to C levels (Custom Levels) in the rl-secure output.
[N] inhibited violations blocking upgrade to [L]Indicates issues that are inhibited at the current level, but will fail at the [L] level. You must resolve the reported issues to attain the level [L] specified in the message.
[N] policy violations blocking attainment of [L]Indicates issues that are causing your package version to fail at the specified level. The specified [L] level in the message can be lower or the same as your currently configured scan level. It means the package is only able to pass at a lower level, and that you must resolve the reported issues to attain the level [L] specified in the message.
No policy violations blocking migration to [L]Indicates the package version doesn't have any issues that would cause it to fail at the specified [L] level. The user is advised to upgrade to the suggested scan level.

Checks overview​

While processing your packages, rl-secure performs different types of checks depending on your configuration and the CLI options you use in your commands. In the list command output, this information is represented as the checks overview when you use the --checks or --all options.

The following check types can be displayed in the command output:

  • Software package analysis - standard scan of the main package version artifact
  • Software package analysis: repro - standard scan of the reproducible build artifact
  • Diff with: repro - comparison of the main package version artifact and its reproducible build artifact
  • Diff with: <version> - comparison of the main package version artifact with another package version
  • Reproducible build check - functional and behavioral similarity check between the main and the reproducible build artifacts

The first check (Software package analysis) is the default and always present for all analyzed package versions. Other checks are displayed only if they have actually been performed for a package version.

Note how in the following example, the my-package@1.0.2 version has multiple types of checks (including the reproducibility check), while the my-package@1.0.1 version only has the default one.

Example checks overview
rl-store: /home/armando/my-repository/
 / my-project 
      / my-package 
         @ [ RB:FAIL ] 1.0.2 (repro)                                           
           ----------------------------------------------------------------
           { L5:PASS - Check (1/4) > Software package analysis            }
           { L5:PASS - Check (2/4) > Software package analysis: repro     }
           { DF:PASS - Check (3/4) > Diff with: repro                     }
           { RB:FAIL - Check (4/4) > Reproducible build check             }
         @ [ L5:PASS ] 1.0.1                                                
           ----------------------------------------------------------------
           { L5:PASS - Check (1/1) > Software package analysis            }

Every check type is assigned a label that shows the status information (pass or fail) for the check. The first two characters in the label are used to distinguish between check types:

  • L(n) - software package analysis with RL-Levels enabled
  • CI - software package analysis with RL-Levels disabled
  • DF - comparison (diff) between package version artifacts
  • RB - reproducible build check

The overall status for the package version displays the check with the highest security risk. When all checks pass, the overall status displays the software package analysis check (L(n):STATUS or CI:STATUS).

You can use the rl-secure checks command to display similar information about all checks, but only for a specific package version.

Usage​

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

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

Options​

OptionDescription
-p, --purlPackage URL for which you want to list details, in the format [pkg:type/]<project>[/<package>[@<version>]]. If you don't specify a package URL, the command shows information for the whole package store.
--fail, --fail-onlyShow only versions with CI:FAIL status. Can't be used together with --pass.
--pass, --pass-onlyShow only versions with CI:PASS status. Can't be used together with --fail.
--counts, --show-countsShow total count of packages and versions.
--issues, --show-issuesShow total count of issues by severity (high, medium, low).
--risks, --show-risksShow risk assessment card.
--checks, --show-checksDisplay all performed software analysis checks.
--usage, --show-usageDisplay total disk usage instead of version count for packages.
--vault, --show-vaultShow where password vault is in use (which package versions have passwords stored in the password vault). For security reasons, it is not possible to see the list of passwords stored in the vault.
--all, --show-allShow all metrics. The equivalent of using --risks, --counts, --vault, and --issues together.
--no-colorDon't color the output.
-h, --helpDisplay usage information and exit.
-s, --rl-storePath to an initialized package store containing the package URL. If you don't specify the path, the current directory is used.

Examples​

Show only failing package versions​

This example shows all package versions with the CI/CD FAIL status in the package store.

We're using the RL-Levels feature, so the default CI:PASS/FAIL indicator is replaced by LX:PASS/FAIL, where X corresponds to the RL-Level used to scan the package. In this example, one of the packages is using a different RL-Level setting than the other packages.

Projects and packages that don't have any versions with the FAIL status are listed in the output as empty.

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.

rl-secure list --fail-only

List all package store contents​

This example shows all projects, packages, and package versions in a previously initialized package store with their CI/CD status.

With the --counts option, we're showing the total count of packages per projects, and the total count of versions per package.

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.

rl-secure list --counts

Show issue counts for all versions of a package​

This example shows the distribution of issues by severity (high, medium, low) across all versions of a specific package, and the total sum of all issues.

The priority indicator (P0-P4) shows the highest priority across all issues (for example, if only one of the issues is P0, the indicator will show P0). If there are no issues detected, the priority indicator displays OK instead.

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.

rl-secure list pkg:rl/my-project/my-package --issues

Show risk assessment card for a package version​

This example shows detected risks per category and the distribution of issues by severity for a specific package version. Each risk assessment category is marked with a CI:PASS (o), warning (!), or CI:FAIL (x).

The --vault option indicates if the package version has any passwords saved to the vault, and shows when the password vault was last modified. If the package store doesn't have a password vault, this information is omitted from the output.

A quicker way to get the information on detected risks and issues, executed checks, and password vault activity is to use the --all option. It returns the same output as if you're using --risks, --counts, --vault, and --issues options together.

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.

rl-secure list pkg:rl/my-project/my-package@1.0.1 --issues --risks --vault