report
Description
Creates a report for a processed package version in one or more supported formats.
By default, the reports are saved to the package-name/versions/package-version-number/reports directory in the specified package store.
To save them elsewhere (outside of the package store), specify a different directory with the --output-path option.
If the directory you specified with --output-path already contains any reports for a package version, they will not be automatically overwritten unless rl-secure detects they are outdated.
You can work around this by emptying the directory before regenerating reports.
Alternatively, you can use the --bundle option with --output-path to specify different names for archive files containing the reports.
When you create reports in the default location in the package store (without using --output-path), they are always automatically overwritten.
Supported report formats
To create reports in all supported formats at once, use the all option instead of specifying the format name.
| Name | Description | Schema | Default file name |
|---|---|---|---|
cyclonedx | OWASP Software Bill of Materials (SBOM). | Official specification | report.cyclonedx.json |
rl-checks | ReversingLabs checks report. This report format is convenient for automated workflows where multiple package version artifacts need to be analyzed and compared. The rl-checks report is similar to rl-json, but instead of showing detailed file metadata, it provides a status summary of all types of checks performed during analysis. This report format cannot be exported for reproducible build artifacts. | Report schema | report.checks.json |
rl-cve | ReversingLabs CVE report. The report is a CSV file containing all known vulnerabilities found during analysis. This report format is convenient for prioritizing the order of resolving known vulnerabilities. | Report schema | report.cve.csv |
rl-html | ReversingLabs HTML report. This report format is identical to the reports generated by the Portal. It's the only report format that can contain diff information. | Example reports | sdlc.html |
rl-json | ReversingLabs JSON report. This report format is intended for use in integration workflows. It's also convenient for users who want to parse the report data with their own tools. The JSON report is less detailed than the HTML report, but it includes the most important information. | Report schema | report.rl.json |
sarif | Static Analysis Results Interchange Format (quality issues). | Official specification | report.sarif.json |
spdx | Software Package Data Exchange (SBOM). | Official specification | report.spdx.json |
When creating reports, rl-secure can bundle them into a ZIP archive.
You can specify the archive name with the --bundle option.
Like the non-bundled reports, the archive is saved to the package store by default.
Diffs
The report command can optionally enrich the rl-html report with diff information.
This is done by comparing a package version against another, usually preceding, version with the --diff-with option.
By default, the rl-html report with diff information is created in the package-name/versions/package-version-number/reports/rl-html-diff-with-{version-number} directory in the package store.
To compare two package versions, they must both be in the same project and package, and must be processed with the same rl-secure version and configuration.
On any mismatch, rl-secure warns you that reprocessing is required.
If you don't reprocess the requested package versions, the reports will be generated without any diff information.
For more detailed instructions, check out the diff guide.
Reproducible build artifacts
If you have previously analyzed a reproducible build artifact for a package version, you can create reports for the artifact by appending the ?build=repro option to the package URL.
These reports will be separate from the main artifact reports. By default, they are created in the package-name/repros/package-version-number/reports/ directory in the package store.
When the ?build=repro option is used, the rl-html report contains the Reproducibility page with details on performed reproducible build checks and differences between the main version artifact and the reproducible build artifact.
All report formats except rl-checks are supported for reproducible build artifacts.
You can create the rl-checks report for the main package version artifact, and it will include a summary of the reproducible build check.
Usage
rl-secure report <csv-format-list> <purl> [<options>]
rl-secure report --format=<csv-format-list> --purl=<purl> [<options>]
Options
| Option | Description |
|---|---|
| -p, --purl | Required. Package URL for which you want to generate the report, in the format [pkg:type/]<project></package><@version>. The selected package must exist in the store. |
| --format | Required. A comma-separated list of report formats to generate. Supported values: cyclonedx, rl-checks, rl-cve, rl-html, rl-json, sarif, spdx, and all. The all option generates all report formats as individual files in the default or specified location. |
| --diff-with | Used 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. Diff information can only be included in the rl-html report, so this option works only when the report format is set to rl-html or all. |
| ?build=repro | Generate reports for a previously analyzed reproducible build artifact of the specified package version. This option must be appended to the package URL of the selected package version, in the format [pkg:type/]<project></package><@version?build=repro>. When this option is used, the reports are saved into the package-name/repros/package-version-number/reports/ directory in the package store. Note that these reports are different from the main version artifact reports, because the reproducible build artifact is treated as a standalone file with its own analysis results. |
| --bundle, --pack-bundle | Bundle reports into a named archive. |
| --output-path | Path to a directory where reports should be saved. If not provided, reports are saved to the specified version's subdirectory in the package store. |
| --no-vex | Exclude VEX (Vulnerability Exploitability eXchange) information from the generated report. Applies only to the cyclonedx report format. VEX is an industry-standard, machine-readable artifact used to embed additional details about known vulnerabilities into the SBOM, including information on triaged vulnerabilities. |
| --force | Try to create a report even if some information is missing. Used with the --diff-with option when the specified version does not exist. This then generates a report with no diff information. |
| -h, --help | Display usage information and exit. |
| -s, --rl-store | Path to an initialized package store containing the package URL. If you don't specify the path, the current directory is used. |
Examples
Bundle all report formats
This example creates a single ZIP archive containing all supported report formats.
Because we're not specifying a custom output directory, the archive is saved into the default location (the reports subdirectory for the selected version in the package store).
You can check the exact location of the archive in the Exporting results to: line in the output.
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.
- Simplified input
- Extended input
- Output
rl-secure report all pkg:rl/my-project/my-package@1.0.1 --bundle=report.zip
rl-secure report --format=all --purl=pkg:rl/my-project/my-package@1.0.1 --bundle=report.zip --rl-store=/home/armando/my-repository/
Software my-project/my-package@1.0.1
Exporting results to: /home/armando/my-repository/.rl-secure/projects/my-project/packages/my-package/versions/1.0.1/reports
CycloneDX JSON ... done
rl-checks report ... done
rl-cve report ... done
rl-html report ... done
rl-json report ... done
SARIF JSON ... done
SPDX JSON ... done
Bundling [==================================================] 100% [00m:00s] 28/28 files
Compare two package versions
This example creates a diff between version 1.0.2 and version 1.0.1 that preceded it.
Since both versions have been processed with the same rl-secure version and configuration, the rl-html report can display diff information about any changes in software quality issues, behaviors, file contents and analysis tags between the compared versions.
We're using the all format option, but only the rl-html report will contain the diff information because it's the only report format that supports it.
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.
- Simplified input
- Extended input
- Output
rl-secure report all pkg:rl/my-project/my-package@1.0.2 --diff-with=1.0.1
rl-secure report --format=all --purl=pkg:rl/my-project/my-package@1.0.2 --diff-with=1.0.1 --rl-store=/home/armando/my-repository/
Software my-project/my-package@1.0.2
Snapshot [===========================================] 100% [00m:00s] 2/2 snapshots
Diffing [===========================================] 100% [00m:00s] 856/856 files
Exporting results to: /home/armando/my-repository/.rl-secure/projects/my-project/packages/my-package/versions/1.0.2/reports
CycloneDX JSON ... done
rl-checks report ... done
rl-cve report ... done
rl-html diff-report ... done
rl-json report ... done
SARIF JSON ... done
SPDX JSON ... done