Projects

Projects are one of the main features of the Spectra Assure Portal. With Projects, you can manage your software releases and organize software packages by a shared feature of your choice (typically by the product name). Each project consists of one or more software packages, which serve as the basis for package version tracking.

On the Projects page, you can view and manage all projects, packages, and package versions added by your groups. For each package version, you can access its report after the analysis. You can learn more about the contents of Spectra Assure analysis reports on the Report page.

Depending on your Portal user role, the Projects page lets you:

• create projects
• add packages to your projects
• version track your packages
• modify projects and packages created by you or the members of your groups
• manage software package versions and their artifacts uploaded by you or the members of your groups

Differences between File Stream and Projects

When you start using the Portal, you'll typically work with the File Stream first, and gradually move to the Projects. The following table lists the key differences between these two Portal features to help you understand their advantages and workflows.

Feature	File Stream	Projects
File organization Work with multiple versions of a software package and group them into projects	❌	✔️
Unlimited file retention Analyzed files and their reports aren't automatically removed from the Portal	❌	✔️
Version diff Compare two versions of a software package to view their differences	❌	✔️
View report Access the SAFE report for a successfully analyzed file	✔️	✔️
Share report Send the link to a SAFE report to anyone in or outside your organization	❌	✔️
Export report Download sections of the SAFE report and the SBOM for a file	✔️	✔️
Export PDF Download the Summary page of the SAFE report in the PDF format	❌	✔️
Mark file as released Differentiate released software versions from unreleased ones	❌	✔️
Reanalyze file Scan a previously analyzed file again to refresh the SAFE report	✔️	✔️
Delete file Remove an analyzed file, its metadata and report from the Portal	✔️	✔️
Approve or reject file Mark an analyzed file as (un)acceptable for use in your organization	✔️	✔️
Download file Download the analyzed software binary from the Portal to your local system	✔️	✔️
File filtering Display analyzed files that match specific criteria	✔️	❌
Reproducible builds Analyze a reproducible build artifact of a software version	❌	✔️
Get RL-SAFE archive Download the complete SAFE report for a software version	❌	✔️

Navigating the Projects page

All pages on the Portal share a header from which you can switch between various groups you belong to, and the tabs for each Portal page you can alternate between: File Stream, Projects, Members, and Settings (Figure 1, #1).

Figure 1 - Navigating the Projects page

When you first open the Projects page, you need to either create a new project or choose an existing project to view. If your group already has some projects, they are listed in the sidebar on the left (Figure 1, #2).

This sidebar is always visible when switching between projects, packages, and versions, and it includes the following:

• the progress bar, showing the current status of the analysis capacity for your group. This eliminates the need to check the Analysis Capacity page before or after each new upload
• the Create Project button, used to create new projects in your currently selected group
• the search bar, used to find projects and packages created in your currently selected group
• group projects - dropdowns from which you can access your group's projects and their packages

Every project and package in the sidebar has an Actions menu, with different options for projects and packages.

If you want more space for your data, you can collapse the sidebar at any time by clicking on the arrow button at the bottom. When collapsed, you can see only the progress bar, the Create Project button, and the search bar.

View packages in a project

Selecting a project in the sidebar opens the list of all packages inside the project.

Figure 2 - Navigating the Packages view

Packages are displayed in the Packages table containing the following fields (Figure 2, #2):

• Status - indicates the overall CI status of the latest package version (pass or fail). It can also be none if no versions exist inside this package
• Package - indicates the package name. You can set this up when creating a package, and change it at any time with the Edit Package option. Selecting the package name opens the Releases view
• # Versions - indicates the total number of software package versions inside a package
• SAFE Assessment/Issues - the only column with an interchangeable heading and related information. When SAFE Assessment is selected, it shows whether any issues with Compliance or Security were found, or if any Threats were detected. Any of these can be disabled for each user. In that case, they will not affect the overall CI status. When Issues is selected, the column displays the total number of detected issues of high, medium or low severity. This information refers to the latest released package version
• Last Scan - indicates when the package was last scanned. This timestamp changes whenever a version inside the package is reanalyzed
• Approval - indicates if the latest released package version was approved or rejected for use in your organization, if its approval was revoked, or if it's still awaiting approval
• Actions - the menu containing everything you can do with the selected software package

Above the table, you can see the name of the currently selected project and how many packages it contains (Figure 2, #1). You can create packages either from the sidebar or by clicking the Create Package button above the Packages table. An organization can have up to 10,000 packages in total across all projects.

All packages in the Packages table can be sorted by the following column header values:

• the package name (Package)
• the number of versions they contain (# Versions)
• the time of the last scan (Last Scan)

View versions in a package

Selecting a package opens the list of all versions inside the package. In the Portal interface, package versions are also referred to as "releases" and are considered as collections of artifacts.

Figure 3 - Navigating the Releases view

All uploaded software package versions are displayed in the Releases table containing the following fields (Figure 3, #2):

• Info - a dropdown menu containing a package version summary
• Status - indicates the overall CI status (pass or fail) of the package version
• Version - indicates the number or other unique identifier of the package version. You can set this only when uploading the package version, and it cannot be modified later. If a package version was derived from another version, this information is displayed below the version identifier. You can specify if a package version is derived when uploading it to the Portal. Selecting the version identifier opens the SAFE report in a new Portal tab
• Upload Next Version - the cloud-shaped upload button that serves as a shortcut for uploading another package version. When uploading a new package and choosing a version it is derived from, a version diff will be automatically generated and included in the SAFE report
• Usage - indicates the total file size and how much of your group capacity was used when the version was added to your package
• Components - indicates the total number of components in the SBOM and how many of them are verified
• SAFE Assessment/Issues - the only column with an interchangeable heading and related information. When SAFE Assessment is selected, it shows whether any issues with Compliance or Security were found, or if any Threats were detected. Any of these can be disabled for each user. In that case, they will not affect the overall CI status. When Issues is selected, the column displays the total number of detected issues of high, medium or low severity. This column also shows when the package version was uploaded to the Portal
• Released - indicates the release date of a package version
• Approval - indicates if the package version was approved or rejected for use in your organization, if its approval was revoked, or if it's still awaiting approval
• Actions - the menu containing everything you can do with the selected software package version

This table cannot be sorted or filtered in any way.

Above the table, you can see the name of the currently selected package and how many versions it contains (Figure 3, #1). Next to this, on the far right, you can check the time of the last scan. This timestamp changes whenever a version is reanalyzed.

You can upload package versions by clicking the Upload Version button above the Releases table. You can also move the existing software package versions from the File Stream page into a project and package of your choice. A package can contain 12 versions, which are automatically ordered by the time of their uploads.

This section (Figure 3, #1) also contains the CI/CD graphic and the summary for the latest released version with the following information:

• whether any issues with Compliance or Security were found, or if any Threats were detected. Any of these can be disabled for each user. In that case, they will not affect the overall CI status
• the total number of detected issues of high, medium or low severity
• details on the version, such as version number, release date, product name, and approval status

NOTE

If no released versions exist for your package, this summary is not available.

Work with projects

Create a project

To create a new project for your group, use the Create Project button in the sidebar. When no projects are created or open, this button is available in the middle of the page, too.

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 create packages inside it.

Manage your projects

You can manage projects from the Actions menu found next to each project name in the sidebar.

This menu allows you to do the following:

• Create Package - create new packages in the selected project. Can also be done by clicking the Create package button below the project's 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

Create a package

To create a new package in the selected project, use the Create Package button either in the left-hand sidebar or above the Packages table when a project is open.

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.

Manage your packages

You can manage packages from the Actions menu. Access it next to each package name in the sidebar and in each row of the Packages table. This menu allows you to do the following:

• 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 package versions (releases)

Upload a version

To upload versions to the selected software 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 software package:

• Product - the full name of the software package
• 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 is released. If marked as released, you'll be prompted to choose the release date

When uploaded, files 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.

View version summary

You can view your package version summary by opening the Info dropdown menu found in the Releases table. This dropdown is made up of three parts:

• a risk analysis card showing the analysis summary per each enabled risk category for your software package version, including its editable information. If your version includes a reproducible build artifact, you can switch between their separate analysis summaries. If your version is derived from some other version, 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 run on your software package version and its artifact. You can also view the individual diff statuses generated between the current version and the version it's derived from, as well as its artifact. Selecting Details for each check takes you to the appropriate 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 at the right end of the Releases table. From the Actions menu, you can do the following:

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

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 clicking the package version in the table.

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

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

You can reanalyze your package versions at any time from the Actions menu. This action automatically sends all versions inside a package to reanalysis (including their 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 artifact.

NOTE

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

Download a file

To download approved packages in their original file format, select the Download File button in the Actions menu. In the pop-up that opens, you can do the following:

• 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 roles that allow file approval can download any file regardless of its approval status.

Delete a package version

You 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

All Portal users can see the version approval status, but only users with the Organization Administrator, Organization Security, and Group Owner 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

Each software package version has two artifacts - release and reproducible build - which are in fact different builds of the same package produced in separate build environments. Reproducible builds 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.

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

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.

Reproducibility check

The reproducible build check is sensitive to any differences between a version and its reproducible build artifact. This means that this check will fail if any behavioral changes, hash changes for script languages, format and classification changes, new issues/vulnerabilities, and more are found.

For example, if the package version and its artifact have the same behaviors, but the artifact was recompiled at some point, the only differences between the two are in their timestamps and hashes. In this case, the reproducibility check passes as no critical differences are found between the package version and its artifact.

The reproducible build check also passes when the package version and its artifact are identical.

You can find this information under the Reproducibility page of the artifact report, which is organized in the following way:

• reproducibility check status and the comparison of two builds
• a list of changes causing the reproducibility check to fail that can be filtered by the type of a detected problem; if the check passes, this part is omitted
• a list of modified files between versions (if any)