Skip to main content

report

Active license required

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.

Overwriting existing reports

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.

NameDescriptionSchemaDefault file name
cyclonedxOWASP Software Bill of Materials (SBOM).Official specificationreport.cyclonedx.json
rl-checksReversingLabs 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 schemareport.checks.json
rl-cveReversingLabs 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 schemareport.cve.csv
rl-htmlReversingLabs SAFE (Software Assurance Foundational Evaluation) report. Also referred to as the 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.-sdlc.html
rl-jsonReversingLabs 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 SAFE report (rl-html), but it includes the most important information.Report schemareport.rl.json
rl-uriReversingLabs URI report. The report is a CSV file providing detailed information on all networking strings found during analysis.Report schemareport.uri.csv
sarifStatic Analysis Results Interchange Format (quality issues).Official specificationreport.sarif.json
spdxSoftware Package Data Exchange (SBOM).Official specificationreport.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.

Diff workflow

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 <csv-format-list> --purl=<purl> [<options>]

Options​

OptionDescription
-p, --purlRequired. 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.
--formatRequired. A comma-separated list of report formats to generate. Supported values: cyclonedx, rl-checks, rl-cve, rl-html, rl-json, rl-uri, sarif, spdx, and all. The all option generates all report formats as individual files in the default or specified location. Should be used implicitly (without specifying the parameter itself) right after the report command.
--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. 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=reproGenerate 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-bundleBundle reports into a named archive.
--output-pathPath 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-vexExclude 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.
--forceTry 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, --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​

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.

rl-secure report all pkg:rl/my-project/my-package@1.0.1 --bundle=report.zip

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 SAFE report (rl-html) 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.

rl-secure report all pkg:rl/my-project/my-package@1.0.2 --diff-with=1.0.1