Skip to main content

Projects workflows

From the Portal Projects page, you can work with:

The availability of actions for each depends on the user role you were assigned.

Work with projects​

Who can do this: Org Admin, Group Owner, Maintainer

To begin working with projects, first you need to create a new project for your group by using the Create Project button in the sidebar. When no projects are created or open, this button is available in the middle of the page, as well.

In the dialog that opens, enter the required information (the project name) and, optionally, a short description of your project.

After creating a project, you can manage it from the Actions menu found next to each project name in the sidebar. This menu allows you to:

  • Create Package - create new packages in the selected project. Can also be done by clicking the Create package button below the project packages in the sidebar
  • Edit Project - change project details (name and short description)
  • Delete Project - remove the project, all packages and package versions inside it, and all project metadata from the Portal instance

Work with packages​

Who can do this: Org Admin, Group Owner, Maintainer

To work with packages, first you need to create a new package in the selected project. This is done by using the Create Package button found in the left-hand sidebar or above the Packages table when a project is selected.

In the dialog that opens, enter the required information (the package name) and, optionally, a short description of your package.

NOTE

You can create up to 10,000 packages in total across all projects in an organization.

After creating a package, you can manage it from the Actions menu. This menu is found next to each package name in the sidebar and at the end of each row of the Packages table.

From this menu, you can:

  • Edit Package - change package details (name and short description)
  • Delete Package - remove the package, all package versions, and all its metadata from the Portal instance

Work with main version artifacts (releases)​

Packages inside projects are populated with main version artifacts. The main version artifact is also referred to as a release.

To start working with main version artifacts, you first need to upload them.

Upload a version​

Who can do this: Org Admin, Group Owner, Maintainer

To upload main version artifacts to the selected package in a project, use the Upload Version button above the Releases table. In the dialog that opens, choose a file from your local storage and enter the required information about your artifact:

  • Product - the full name of the software package whose version you're uploading
  • Version - a unique identifier of the software package version
  • Derived - optionally choose an older version as the predecessor of the version you're currently uploading. When this is omitted, the Portal will not generate a diff report
  • Publisher - indicates the software publisher
  • Platform - a dropdown from which you can choose the system for which the software has been developed
  • Category - a dropdown from which you can choose the general purpose of the software package
  • License - a dropdown from which you can choose the type of license for the software package. All license types from the SPDX License List are supported
  • Is Released - a checkbox indicating whether the software package version is released. If marked as released, you'll be prompted to choose the release date

When uploaded, version artifacts are automatically analyzed and added to the Releases table. These uploads do not have to be sequential, as you can select any previous package version as the predecessor (referential version).

If a package already contains the older version that your new version is derived from, the Portal automatically generates a diff between these two versions. In this case, only the new version report contains the diff results.

NOTE

You can upload up to 12 software package versions to each package inside a project. Each version upload counts against your group capacity, unless you're moving a package version from the File Stream to a new or existing project of your choice.

View version summary​

Who can do this: All roles

You can view your package version summary by opening the Info dropdown menu found in the Releases table.


The Info dropdown is made up of three parts:

  • a risk analysis card showing the analysis summary per each risk category for your software package version, including its editable information. If your version has a reproducible build artifact, you can switch between their separate analysis summaries. If your version has a predecessor, you can find their summary diff in separate risk analysis cards shown side by side. This makes the changes between the two more clear-cut
  • the status of checks done against all artifacts in a version. You can also view the individual diff statuses generated between the current version and the version it's derived from, as well as between the version and its reproducible build artifact. Selecting Details for each check takes you to the appropriate part of the report
  • your reproducible build artifact for your software package version. If you have an appropriate user role, this is where you can upload a new reproducible build artifact or delete the existing one

Manage your releases​

After a package version has been analyzed, you can access its Actions menu from the right-hand side of the Releases table. From there, you can:

  1. View Report
  2. Mark as Released
  3. Reanalyze Package
  4. Download File
  5. Delete Version
  6. Approve/Reject

The availability of these actions depends on the user role you were assigned.

View a report​

Who can do this: All roles

You can view the SAFE report for a package version either from the Info dropdown or from the Actions menu at the end of each Releases table row. Another way to access the report is by selecting the name of the package version in the table.

To better understand all the available options for accessing the report, use this interactive visualization.

If the package version you want to view the report for contains an artifact with failed analysis, clicking View report opens the report for that artifact.

Users with the appropriate role will get the Share Report option on the report landing page.

Mark as released​

Who can do this: Org Admin, Group Owner, Maintainer


You can unrelease a released version of your software (and vice versa) at any time from the Actions menu in the Releases table, regardless of its specified release date. This is useful for keeping track of all released (or unreleased) package versions. With this feature, you can also cancel your releases in case of any critical issues.

Reanalyze a package​

Who can do this: Org Admin, Group Owner, Maintainer

You can reanalyze your package versions at any time from the Actions menu.


Initiating this action automatically sends all versions inside a package to reanalysis (including their reproducible build artifacts, if any exist) to ensure that all reports are up to date. However, the Portal will prompt you to reanalyze a version if its report is outdated when you try to view it.

Reports can be outdated for the following reasons:

  • the Portal analysis engine has been updated since you uploaded your package version
  • the organization policy profile has changed since you uploaded your package version
  • the group policy profile has changed since you uploaded your package version

An up-to-date report is mandatory for generating a diff between two consecutive versions and between a version and its reproducible build artifact.

NOTE

Sending a file to reanalysis does not affect the group capacity in any way.

Download a file​

Who can do this: All roles

To download approved files in their original file formats, select the Export button in the banner of their report page.

If you want to download the approved file directly from the Projects page, select the Download File button in the Actions menu. In the pop-up that opens, you can:

  • click the filename to complete the download action
  • view and copy the SHA256 file hash
  • select Close to cancel the download action

If the analysis capacity is exceeded, if a file is not approved, or if you do not have the permission to approve files, selecting the Download File button results in an error. Only users with Organization Administrator, Orgnization Security, and Group Owner roles, which allow file approval, can download any file regardless of its approval status.

Delete a package version​

Who can do this: Org Admin, Group Owner, Maintainer

Users with the appropriate role can delete any package version from the Actions menu of the Releases table.


Remember that deleting a software package version removes all its metadata from the Portal, including its reproducible build artifact and all information connected to it. Therefore, if you want to keep the reports of your package versions, you need to export them first.

NOTE

From the Report page, you can export the following:

  • the report summary, in the PDF format
  • the complete report, in the RL-SAFE archive format
  • SBOM, in either the CycloneDX or SPDX format
  • Issues, in the SARIF format
  • Vulnerabilities, in the RL-CVE format
  • Networking, in the RL-URI format

Approve or reject a package version​

Who can do this: Org Admin, Org Security, Group Owner

All Portal users can see the version approval status, but only users with the appropriate roles can approve, reject, or revoke approval for package versions.


By default, all package versions await approval when uploaded to the Portal Projects page.
If you have the appropriate role and have thoroughly reviewed your software report after a scan, you can assign one of the following approval statuses to your package version:

  1. Approved, when no policies have failed during analysis or when some policies did fail but you subsequently either accepted the potential risk or manually suppressed those policies
  2. Approval Rejected, when the package version should be restricted from deployment since it poses a considerable risk to your organization even after all possible actions have been taken
  3. Approval Revoked, when:
    • the package version has been incorrectly or inadvertently approved,
    • the package version can be replaced by an alternate version (e.g. a later version) posing a lower security risk,
    • the policy configuration has been modified, or
    • a new threat impacting components of the software has been identified

From the Actions menu, you can approve only the package versions tagged as "Requires Approval" or "Approval Rejected". Once you update the approval status for the package version, you cannot change it back to "Requires Approval". Any change in approval status requires you to state a valid reason to support your choice.

When you approve a package version, it can be downloaded by any Portal user and its approval can be revoked at any moment. If you revoked the version approval, Portal users can neither reapprove it nor download it. This kind of package version should be removed from the production environment to avoid future use.

You can only reject the software that has not been approved yet. If you already rejected the software but you want to change the rejection reason, you need to reject it again with a new reason.

Work with reproducible builds artifacts​

Who can do this: Org Admin, Group Owner, Maintainer

Each software package version can have a main version artifact ("release") and a reproducible build artifact. They are different builds of the same package produced in separate build environments. Reproducible build artifacts enable you to verify that your build systems have not been tampered with.

Each package version can have only one reproducible build artifact uploaded from the Info field of the Releases table.

NOTE

Uploading a reproducible build artifact does not affect the group capacity in any way.

If you want to scan another reproducible build, you can do that only by deleting an existing reproducible build artifact and uploading a new one.

When a reproducible build artifact is uploaded, a diff between this artifact and the main version artifact is automatically generated. Any significant functional differences between the two will fail the reproducibility check.