Skip to main content

How to share a SAFE 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 do not 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 report links 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.

For each package version, you can generate multiple report links, depending on the use case.

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 generation or 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 report link generation. For each software package version, you can generate multiple report links with different share options depending on the use case.

For every analyzed package version, its latest complete report is being shared. When a package version with a shared report link gets deleted, all the generated links are invalidated and its report can no longer be accessed. If any of the report links is password-protected, its 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, Maintainer
  • 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 five steps:

  1. Link Name
  2. Restrictions
  3. Recipients
  4. Review
  5. Share 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 report link.

After closing the dialog window, you'll see the generated report link in the Shared Links table.

In this step, you give your shared report link a name.

To get a generic link name, select the role of the person receiving the link. The name will be shown in the field at the bottom of the dialog window. You can then edit the name or delete it completely to create a unique link name.

A unique name can also be written in the empty field at the bottom of the dialog window without first choosing the recipient role.

2. Set the restrictions​

This is where you can select when the link will expire. The following options are available: 1 day, 7 days, 14 days, 30 days, 60 days, or 90 days. By default, all links expire in 30 days.

From here, you can also control what users with the link can do with the report and whether they need a password to access it. You can enable the following: Package Download, CycloneDX Export, Sarif Export, SPDX Export, RL-CVE Export, RL-URI Export, and Protect with Auto-Generated Password. The report export options are enabled by default, while password protection and package download are not.

Before enabling package download, note that this action uses up the download capacity every time it's run.

3. Choose the link recipients​

If you want to send the report link to specific people, you can can write a comma-separated list of their email addresses here. When at least one recipient exists, you can write a custom message that will show up as a part of an email with the shared link and a password (if it's configured). If you want to, you can also select to receive a copy of the email.

Choosing recipients of the report link is not required for generating the link. You can skip it by selecting the Skip This Step button.

The report link can be copied from the last step of the link generation process or from the Shared links table, after the link is generated. If you do not want to copy the link and send it manually to the recipients of your choice, choose the Send Link from the Actions menu of the Shared links table.

4. Review your choices​

In this step, you can go over everything you selected up to that point. When you're satisfied with your choices, generate the link by clicking on the Generate Link button. If you chose at least one recipient in the previous step, you can see how many people will receive a notification email with the report link.

5. Share the report link​

This is where you get 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 the link) and store them or send them manually to the recipients of your choice, if you skipped the third step.

Check the report sharing statistics​

Once the first report link for a specific software package version is generated, the Share Report button in the report banner turns into the Shared Links expand button.

Clicking on it shows the statistics related to the usage of report links generated for that software package version. Here, you can see the following:

  • How many report links were generated
  • How many times were the shared reports viewed
  • When was any of the shared links first shared
  • When was any of the shared links last viewed
  • How many times was the SBOM downloaded with the Export button in the report banner
  • How many times was the version file downloaded with the Export button in the report banner
info

Unsharing or resharing a shared link or reprocessing the software package version does not affect the report sharing statistics.

Below the statistics, there's a table showing all shared links for that version and the following information:

  • Link Name - indicates the link name either provided by the user or automatically generated in the first step of the link generation process. Clicking on the link name allows you to resend the report to the existing recipients
  • Shared By - indicates which account generated the link
  • Link - indicates a copiable link to the report. It's available to anyone with access to the Portal instance and group where the software package version is found. If the link is expired or invalidated, this field will show -
  • Password - if a password is required for unlocking the report link and seeing the report contents, you'll be able to copy it from here. If a password is not required, the field will show N/A. If the link is expired or invalidated, the field will show -
  • Expiration - indicates the time left before the report link becomes unavailable. If the link expired or was invalidated, this field will show how long ago this happened
  • Recipients - indicates the number of recipients that viewed the report from the shared link. If the report was not sent to anyone, the field will show N/A
  • Actions - the menu from which you can invalidate the report link (Stop Sharing), change the link name (Rename Link), and send an email with the report link to the specified email addresses (Send Link)

All links in the Shared links table can be sorted by the following column header values:

  • the name of the shared link (Link Name)
  • the person who generated the shared link (Shared By)
  • how long until the link expires (Expiration)

From the expanded row, you can generate new report links with the Share Report button.

Generating new shared links

By default, every time you generate a new shared report link, its position in the table depends on the expiry time.

Sharing the report with users​

You can share the report with anyone inside or outside your organization either manually or directly through the Portal.

To share the report link manually, copy the link and the password (if enabled) from the last step of the link generation process or from the Shared links table, after the link is generated.

If you want to automatically share the report link directly through the Portal, without taking any additional steps, choose the recipients during the link generation process. Once the link is generated, you can resend the link to the existing recipients (if any) by either clicking on the link name in the Shared links table or by selecting the Send Link option in the Actions menu. The Send Link option also allows you to add new recipients.

After opening the shared report link and typing in the password (if it exists), users can do the following from the shared report banner:

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

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 how many times the report has been shared
  • from the report banner, download the analyzed file even if download is disabled in the share options; this action affects the Download capacity
  • from the report banner, export the shared report in the CycloneDX, Sarif, SPDX, RL-CVE, and RL-URI formats, even if the export is disabled in the share options
  • generate multiple links with different sharing options (requires the appropriate user role)
  • expand the report banner to see all generated shared report links for that version, their sharing options, as well as their share statistics
  • regenerate any expired or unshared links (requires the appropriate user role)
  • copy the auto-generated password (if enabled)
  • reprocess the version and generate a new report
  • fetch the latest report when the report becomes outdated
  • rename the generated link
  • resend the report link to previous recipients or send the link to people who have not received it yet
  • unshare the report (requires 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 Shared Links button to expand the table with all shared report links for the software package version.
  3. Go to the Actions menu for the report link you want to stop sharing.
  4. Click on the Stop Sharing button. This action invalidates the report link and the report cannot be accessed anymore.

Once you stop sharing the desired link, you can either Delete it from the table or Regenerate it from the Actions menu.

Regenerating the report link can be done only when the report link for a specific package version is no longer valid and the report cannot be accessed.

Navigate to the report banner and click on the Share Link button to expand the table with all shared report links for the software package version. Go to the Actions menu for the report link you want to regenerate and select Regenerate.

In the dialog that opens, all pre-selected options correspond to the sharing options generated for the expired or invalidated report. To regenerate the report link with new or existing options, you have to complete the following six steps:

  1. Link Name, where you can change the name of the shared report link. To choose a generic name, select the role of the person receiving the link. The name will be shown in the field at the bottom of the dialog window. You can then edit the name or delete it completely to create a unique link name. You can also replace the previous link name with a unique one without first choosing the recipient role.

  2. Restrictions, where you can change the number of days after which the link expires. The following options are available: 1 day, 7 days, 14 days, 30 days, 60 days, or 90 days. The default is 30 days. From here, you can also control what users with the link can do with the report and whether they need a password to access it. You can enable the following: Package Download, CycloneDX Export, Sarif Export, SPDX Export, RL-CVE Export, RL-URI Export, and Protect with Auto-Generated Password. Upon each package download, the download capacity is used.

  3. Previous Recipients, where you can choose the recipients you want to resend the report link to, if any exist. You can select them all or you can search them by email. A filter can be applied to see only those recipients that have received the report link but have not yet viewed it. This entire step is optional and can be skipped.

  4. Recipients, where you can write a comma-separated list of all email addresses you want to send the report link to. If in the last step you chose to resend the link to someone, their email address will automatically show up here. When at least one recipient exists, you can write a custom message that will show up as a part of an email with the shared link. If you want to, you can also select to receive a copy of the email. This entire step is optional and can be skipped.

  5. 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. If you chose at least one recipient in the previous two steps, you can see how many people will receive a notification email with the report link.

  6. Share Report, where you can see the summary of your report options. At this point, a new 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 regenerate the report link.

Regenerated links

Every time you regenerate a specific link, a unique URL is created and a new shared link is added to the Shared links. For password-protected reports, you can either generate a new password or remove it completely.

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