Skip to main content

How to share a report

Report sharing is a Portal feature that allows users with appropriate roles to generate unique links exclusively for package versions uploaded to the Projects page. These links can then be used to share analysis reports with people who do not necessarily have a Portal account.

Benefits of sharing reports​

The report sharing feature allows you to collaborate with people inside and outside your organization more seamlessly. With this feature, you can share analysis reports for your package versions with anyone, even if they don't have a Portal account. This reduces the amount of effort required from both parties and contributes to a more polished workflow.

With a few clicks and the appropriate user role, you can get a unique link to share with others. The reports you're sharing give the selected external parties direct insight into your software. This accelerates the processes of risk assessment and remediation, which can enhance the security of your SDLC and the overall quality of your software.

Additional layer of security can be set up by password-protecting the reports you're sharing. By limiting access to your reports, you're ensuring that only users with the correct password can read the report contents.

Access restrictions

The access to the report shared with you is automatically denied after providing an invalid report password 10 times in a row. This lockout is automatically cleared after 1 hour.

Another way of protecting your data is by configuring the share options, which determine what users that have the link can do with the report. This guarantees that users cannot locally store the data you shared with them unless you allow them.

Some common scenarios where report sharing can help you:

  • As a software producer, you can share reports with a vendor to identify issues for resolution
  • As a software buyer, you can share reports with an auditor for visibility into specific analysis results

How does report sharing work?​

Reports for all files uploaded to the Portal have a permanent URL. This type of URL is an invariable web location where you can always find the report for that particular package version.

Permanent URL vs. shareable URL

Permanent URLs and shareable URLs generated for each report are separate concepts. While permanent URLs are updated only when renaming a project, package, or package version, shareable URLs generated for report sharing change with each regeneration due to security reasons.

For package versions on the Portal Projects page, permanent URLs are in the following format:

{portal-instance}/reports/group/{group-id}/report/{project-name}/{package-name}/{version}/?build=(version|repro)

  • portal-instance indicates the Portal instance to which the package version is uploaded
  • group-id indicates the ID of the group the package version belongs to
  • project-name and package-name indicate the name of the project and the package to which the package version belongs
  • version indicates the package version or the release of a particular package
  • build indicates whether the report belongs to the release artifact or the reproducible build artifact (if it exists)

For example:

test.secure.software/reports/group/1aa622ac-3359-4b95-86dd-59bbf9ba56f6/report/test-project/test-package/v1/?build=version

On the other hand, shareable URLs are in the format {portal-instance}/shareable-reports/{unique-report-id} and are not accessible unless explicitly shared.

The reports you decide to share are still considered private to some extent since every unauthenticated user that wants to access or view the shared report needs to have a valid link. Links are considered valid until they're either revoked or expired.

If you want to further protect your report with a password or limit user actions with the report, you can do so during the share link generation.

For every analyzed package version, its latest complete report is being shared. When a package version with a shared report link gets deleted, its link are invalidated and its report can no longer be accessed. If the report is password-protected, the password expires as well.

The shared report includes a diff when the version has a predecessor, detailing changes made from the previous version. Additionally, reports for reproducible build artifacts can be shared separately from release artifacts they're associated with.

Prerequisites​

To manage report links, you need to:

  • have the appropriate user role: Organization Administrator, Organization Security, Group Owner
  • open the Report page for the desired package version from the Projects page

When a report link for a specific package version has not been generated yet, navigate to the report banner and click on the Share Report button. In the dialog that opens, you have to complete the following four steps:

  1. Expiration, where you can choose the number of days after which the link expires. The following options are available: 1 day, 7 days, 14 days, and 30 days. The default is 30 days.
  2. Restrictions, where you can control what users with the link can do with the report and whether they need a password to access it. Here you can enable the following: Package Download, CycloneDX Export, Sarif Export, SPDX Export, and RL-CVE Export. The report export options are enabled by default. Upon each package download, the download capacity is used.
  3. Review, where you can go over everything you selected up to that point. If you're satisfied with your choices, generate the link by clicking on the Generate Link button.
  4. Share Report, where you can see the summary of your report options. At this point, the report link is generated. Now all you can do is copy both the link and the auto-generated password, if you chose to protect your report.

You can return to the previous steps using either the Previous button or the checkmarks at the top of the dialog. This allows you to change any of your choices up until you generate the share link.

After closing the dialog window, send the link along with the password (if it exists) to anyone you want to share the report with.

Sharing the report with users​

After opening the shared report link, users can do the following:

  • see from which instance the report was shared and when its link expires from the report banner
  • if enabled, export the shared report from its banner in either of the following formats: CycloneDX, Sarif, SPDX, RL-CVE
  • if enabled, download the analyzed file from the shared report banner
  • log in from the shared report banner

If they're an authenticated user, clicking on the Log in button redirects them to the Portal report page. On the other hand, unauthenticated users are redirected to the Portal login page.

Sharing with unauthenticated users

Unauthenticated users can view only the report that was shared with them, without having access to any other files or reports. If they want to use the Portal in its entirety, they need to have a valid user account.

Sharing with authenticated users​

After login, authenticated users can use the Portal as they typically would. Specifically:

  • from the report banner, see who shared the report and when its link expires
  • download the analyzed file from the shared report banner, even if download is disabled in the share options; this action affects the Download capacity
  • export the shared report from its banner in the CycloneDX, Sarif, SPDX, and RL-CVE formats, even if export is disabled in the share options
  • reprocess the version and generate a new report
  • fetch the latest report when the report becomes outdated
  • see the shared report link and the configured share options, including the auto-generated password (if enabled)
  • unshare the report, if they have the appropriate user role

Stop sharing the generated link​

When a report link for a specific package version has been generated, but has not yet expired, you can do the following:

  1. Navigate to the report banner.
  2. Click on the Stop Sharing button. This action invalidates the report link and the report cannot be accessed anymore.

Regenerating the report link is neccessary in the following situations:

  • when you want to update the sharing options after already creating the link
  • when the report link for a specific package version is no longer valid and the report cannot be accessed
  • when you want to update the auto-generated password for the shared report, provided the password protection is in place

In any case, navigate to the report banner and click on the Regenerate Link button. In the dialog that opens, you have to complete the following four steps:

  1. Expiration, where you can choose the number of days after which the link expires. The following options are available: 1 day, 7 days, 14 days, and 30 days. The default is 30 days.
  2. Restrictions, where you can control what users with the link can do with the report and whether they need a password to access it. Here you can enable the following: Package Download, CycloneDX Export, Sarif Export, SPDX Export, and RL-CVE Export. The report export options are enabled by default. Upon each package download, the download capacity is used.
  3. Review, where you can go over everything you selected up to that point. If you're satisfied with your choices, generate the link by clicking on the Generate Link button.
  4. Share Report, where you can see the summary of your report options. At this point, the report link is generated. Now all you can do is copy both the link and the auto-generated password, if you chose to protect your report.

You can return to the previous steps using either the Previous button or the checkmarks at the top of the dialog. This allows you to change any of your choices up until you generate the share link.

After closing the dialog window, send the link along with the password (if it exists) to anyone you want to share the report with.

Regenerated links

Every time you regenerate a link for a specific report, a unique URL is created and the old link is invalidated. For password-protected reports, a new password is also generated.

This means that users with an old link and password can no longer access the report, so the new link and password need to be reshared with them.