Skip to main content

Compare package versions

What is a diff?​

Diff can be defined as a comparison of two versions of the same software that highlights the changes between them.

In terms of the Spectra Assure platform, this comparison is focused on software quality issues, behaviors, file contents, and analysis tags. The diff information provided in the analysis report is useful for recognizing whether your software has been tampered with and how.

Only the SAFE report (rl-html format) can include the diff information.

In this guide, you will learn how to compare package versions with rl-secure.

Prerequisites​

Diffing (comparison) of two package versions is possible under the following conditions:

  1. Package versions must exist in the package store.

  2. Package versions must be processed with the same configuration and the same rl-secure version.

Commands to use​

scan​

To enable diffing (comparison) between package versions, first you need to add the software packages to the package store with the rl-secure scan command.

To ensure both versions of a software package you want to compare are analyzed with the same rl-secure version and configuration, use the --sync-with option when scanning the newer package version. With this option, specify the package version you intend to diff against. The option checks if synchronization is required and reanalyzes packages if necessary.

In case the package version you're trying to add is already present in the package store, use the --replace option to overwrite it.

report​

After you've scanned the packages and confirmed that two versions you want to compare are in sync, use the rl-secure report command on the newer package version with the following options:

  • the --diff-with option to specify the referential package version (the one you want to compare against)
  • the --format option to specify the analysis report format. This must be set to either rl-html or all, because rl-html is the only report format that can display diff information. It should be used implicitly (by listing one or more formats without specifying the parameter itself) right after the report command.

On any mismatch between versions, rl-secure warns you that reanalysis is required. If package versions are not reanalyzed, the requested reports will still be generated, but without the diff.

Creating multiple diffs for a package version

It's possible to compare a package version against multiple other versions. To do this, run the rl-secure report command with the --diff-with option multiple times, each time specifying a different version to diff against. Every comparison (diff) is saved as an individual report file.

inspect​

After you've generated the diff report between versions 1.0.2 and 1.0.1, use the rl-secure inspect command on the newer package version with the --diff-with option. With this option, specify the package version you intend to diff against. The option displays the differential analysis results in the CLI output.

If any of the previous steps is skipped, this command will result in an error.

How to create a diff​

Workflow overview:

  • Scan a package version (V1)
  • Scan another package version (V2)
  • Make sure V2 and V1 are scanned with the same configuration
  • Generate a SAFE report for V2 that includes the diff against V1
  • Display the diff analysis results in the CLI output

1. Scan a package version​

In this example, you've previously scanned the 1.0.1 version of an example software package.

You're using the rl-secure scan command to scan the 1.0.2 version, and you want to inspect how it's different from the 1.0.1 version. In this case, 1.0.1 is your referential version.

The --sync-with option ensures that the new package version scan is synchronized with the previous (referential) version.

Since the 1.0.1 version was processed with a different scan configuration, both packages are reanalyzed. This enables the subsequent command rl-secure report to create a diff between the two package versions.

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.

If the 1.0.2 version is already in the package store, rl-secure warns you about the conflict. In that case, you need to repeat the scan in a subsequent command and specify that you want to overwrite the existing version with --replace.

Input

rl-secure scan /home/armando/my-package.jar pkg:rl/my-project/my-package@1.0.2 --sync-with=1.0.1

Output

Preparing ...
Copying  [=============================================] 100% [00m:00s] 1447178/1447178 bytes
Software my-project/my-package@1.0.1
Scanning [=============================================] 100% [00m:01s] 363/363 files
Merging  [=============================================] 100% [00m:01s] 363/363 files
Software my-project/my-package@1.0.2
Scanning [=============================================] 100% [00m:01s] 371/371 files
Merging  [=============================================] 100% [00m:01s] 371/371 files
Analysis finished!

2. Compare versions​

After scanning successfully completes, you can use the rl-secure report command to generate a diff report between the version 1.0.2 and the version 1.0.1.

More specifically, you're creating the report for the version 1.0.2 and setting 1.0.1 as the referential version by using the --diff-with option.

Since both versions have been processed with the same rl-secure version and configuration, the rl-html report is enriched by diff information on software quality issues, behaviors, file contents and analysis tags.

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 report all pkg:rl/my-project/my-package@1.0.2 --diff-with=1.0.1
SUCCESS

Your diff report should now be ready for viewing.

3. Find the diff analysis results​

You can find the diff results in two places:

Find diff in the SAFE report​

If the previous steps have been successfully completed, you'll find the report with the diff information in the reports/rl-html-diff-with folder of the version for which you generated the report. In this example, it's the version 1.0.2.

In the SAFE report, the differences between the two analyzed packages are shown in the Version diff section accessed from the sidebar on the left-hand side.

The Version diff > Issues page displays all issues that were either resolved or introduced since the last version. You can filter the issues by category and expand every issue to show more details about it, including the files newly impacted by introduced issues.

The Version diff > Files page displays all files that were modified between versions. You can filter the files by name and change type, and expand each file to show additional information, including a detailed list of changes. This makes it easier to pinpoint the exact elements of your software that have been modified.

Once you have the diff report, you can use the information provided there to prevent potentially unsafe software from being released. Additionally, based on this report, you can decide which version of the software you can safely use. All of this in turn contributes to overall security of your system and helps you remediate issues in the newer versions of your software.

Find diff in the CLI output​

If you want to get the diff analysis results directly in the terminal, you can use the inspect command paired with the --diff-with option.

Setting the 1.0.1 version as the referential version allows you to get a comprehensive list of issues introduced in the newer (1.0.2) version. This CLI output is a more concise and straightforward version of the Diff page in the report.

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 inspect pkg:rl/apache/solr@8.11.3 --diff-with=8.10