Skip to main content

Best practices for working with projects

This guide covers best naming practices, as well as all important information on the projects hierarchy and feature usage on Spectra Assure Portal. It also compares Portal projects to projects in other Spectra Assure products.

What are projects?​

In Spectra Assure, projects are considered the main unit of organization for software releases. They can be regarded as a collection of packages, where each package contains one or more versions.

It's important to differentiate between packages and "software packages". Software packages are actual individual files you upload to the Portal. In the context of Spectra Assure Projects, they are referred to as versions.

On the other hand, projects and packages are logical units that allow you to keep track of all versions of a specific product. You can think of projects as types of folders that contain sub-folders (packages). Inside those sub-folders, you can find actual files (versions).

Each version uploaded to Portal projects 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. For example, on the Portal, you can upload the officially released v1 version in .exe format as a main version artifact, while the development v1 version in the same format could be uploaded as its reproducible build artifact.

To clearly illustrate the relationship between projects, packages, and versions, look at the following example:

└── 7-Zip  1️⃣
    ├── Windows  2️⃣
        ├── 24.09  3️⃣ ── 24.09-repro 4️⃣
        └── 23.01 
    ├── Linux 
        ├── 24.09 
        └── 23.01 
    └── MacOS 
        ├── 24.09 
        └── 23.01

The project structure on the Portal consists of the following levels:

  • 1️⃣ Project - projects are typically products whose releases you want to track
  • 2️⃣ Package - packages are typically architectures or platforms for which the software has been developed
  • 3️⃣ Version - versions are typically release artifacts
  • 4️⃣ Reproducible build - reproducible builds are typically reproducible build artifacts; they're on the same level as release artifacts

When sorted into packages and projects, your versions and any reproducible build artifacts tied to them are permanently stored on the Portal. You do not need to worry about the retention period, which is imposed on the Portal File Stream.

It is crucial not to treat different release artifacts for different platforms as versions of the same package. Mixing them interferes with differential analysis and makes it produce invalid results, since diffing is done on the package level. This is why it is suggested to upload different versions created for the same platform to one package.

└── 7-Zip 
    ├── Windows 
        └── 24.09 
    ├── Linux 
        └── 24.09 
    └── MacOS  
        └── 24.09

Package URLs vs permanent URLs​

Package URLs are unique identifiers that register your packages in the rl-secure package store. This special URL is in the following format: [pkg:type/]<project></package><@version>. It is used by rl-secure to perform various actions on a version with different commands.

On the Spectra Assure Portal, package URLs are represented as permanent URLs assigned to analyzed files (versions). The permanent URL is used by Spectra Assure Portal and Portal API to associate the version with a project and a package. It contains all information on the exact position of the file in the Portal UI, making the file and its report easier to find.

On the Portal, this URL for packages on the Projects page is in the following format: {portal-instance}/projects/group/{group-id}/project/{project-id}/package/{package-id}.

For the version report, the purl looks like {portal-instance}/reports/group/{group-id}/report/{project-name}/{package-name}/{version}/?build=(version|repro). This URL can be copied from the address bar on your Portal instance or obtained with the Portal APIs, by using the Show analysis status endpoint.

When using the API, the URL field in the response (report.info.portal.reference) contains all information on the exact position of the file in the Portal UI. You can then use the Portal to open the report or share it with others.

Why should you use a projects-based approach?​

Software publishers typically organize their releases by platform, architecture, or distribution. The project-based approach in Spectra Assure products aligns with this workflow by allowing software publishers to keep their releases organized the same way. In Spectra Assure, it is recommended to use software name as a Spectra Assure project name, the platform or architecture as a package name, and a release artifact as a version name.

The hierarchical nature of projects makes it ideal for version tracking and organizing your releases. Thanks to this feature, you can work with multiple versions at the same time and keep all releases of your software in one place, which makes their reports easier to find and share with others. At all times, you and your colleagues know where they are located, which in turn saves time and other resources, as well as promotes collaboration and reduces confusion.

The analysis reports for your package versions can be shared with anyone, even to those without a Portal account or a CLI license. 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.

The complete SAFE report for a package version can be also be obtained either from the Portal UI, API, or rl-secure. To open the report, you need the SAFE Viewer application that can be downloaded from the docs.

Naming projects and packages​

When naming new projects and packages, you should bear the following recommendations in mind:

  • Create projects for each unique software vendor product. Make sure all names are meaningful for ease of reference. It's best to keep the original product names whenever possible to avoid confusion.
  • Avoid using articles, file extensions, spaces, and special characters such as \/:*?"<>|@#%.
  • Names are case-sensitive. Avoid random capitalization (e.g. sOLr). Start all names with an uppercase letter and capitalize the first letter of subsequent words.
  • Make sure all names are unique. If a project, package, or a version with the same name already exists in the group, an error is thrown since Portal assumes they're identical and are assigned the same permanent URL.
  • Stay consistent. Follow the same naming pattern for all projects and packages to ensure users can locate them more easily. It's suggested to apply the following scheme:
    • Project name = product name (e.g. Apache_Solr, 7-Zip)
    • Package name = OS platform (e.g. Windows, Linux)
    • Version name = release number (e.g. 8.11.4, 16.04)
Disclaimer

This section contains only naming recommendations. You might not be able to apply the same naming pattern to every project, package, or version because the software you analyze may come from different sources.

Projects across Spectra Assure products​

Projects as a feature slightly differ across Spectra Assure products. This section offers you all important product-specific information that can help you understand how the feature works on the Portal UI and API, as opposed to rl-secure.

While in rl-secure, projects are tied to a package store, on the Portal, they reside on the Projects page. On this 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.

Creating projects​

PortalOn the Portal, projects are created on the Projects page by selecting the Create project button. There is no limit to the number of projects. However, you can create up to 10,000 packages in total across all projects in an organization and upload up to 12 package versions to each package inside a project. In reality, the remaining organization analysis capacity and configured group limits dictate how much space you actually have for your version uploads. This is why it's recommended to make space for new uploads by periodically cleaning up your projects, packages, and versions. Make sure you back up all version files and their reports before deleting them.
APIThe Portal API has separate endpoints for creating projects and packages, and uploading and scanning versions. Since all changes made via API are reflected on the Portal, the same limitations are enforced on both.
CLIIn rl-secure, projects are created simultaneously with packages, when a version is sent to analysis with the scan command. But first, you need to initialize a package store. A package store has no limit enforced when it comes to the total number of projects or packages inside it. This depends solely on the free space on your system, as well as on the remaining analysis capacity shared with Portal. However, you can upload up to 12 package versions to each package inside a project, but each version must be smaller than the maximum allowed package size determined by your license.

Modifying projects​

When you modify (or, more precisely, rename) projects or any of the packages or versions they contain, their permanent URL is changed.

Keep in mind that every project/package name combination must be unique on the level of each Portal group or rl-secure package store. New project and package names should not clash with any of the existing name combinations. In other words, you can't rename my-project/package-one into my-project/package-two if the latter already exists.

PortalModifying projects is possible from the Actions menu of the selected project on the Portal.
APIModifying projects is possible via the Modify project details API. For packages and versions, there are separate API endpoints available.
CLIWith rl-secure, you can simultaneously rename a project, package, and a version with the rl-secure rename command.

Deleting projects​

Deleting a project removes the project and all packages and package versions inside it, including the project metadata.

PortalDeleting projects is possible from the Actions menu of the selected project on the Portal or If you want to keep the reports of your package versions, you need to export them first. On the Portal, this is done from the banner found on the Summary page of the version report.
APIDeleting projects is possible via the Delete a project API. For packages and versions, there are separate API endpoints available. If you want to keep the reports of your package versions, you need to export them first. Separate endpoints are used for exporting the entire report in the RL-SAFE archive format and parts of the report in other supported formats.
CLIWith rl-secure, you can delete a project, package, or a version with the rl-secure remove command.

Diffing​

PortalOn the Portal, a diff between two consecutive versions is automatically generated when you choose a predecessor for the version you're in the process of uploading to a project of your choice. This is done by filling the Derived field in the version upload dialog. Since you can choose only one predecessor for a version, only a single diff can be created for each version.
APIDiffing is possible with the Upload and scan a version API. The diff_with optional parameter lets you specify a previous package version against which you want to compare (diff) the version you're uploading. The specified version must exist in the package.
CLIThe CLI allows you to create multiple diffs for each package version, but you need to initiate each process manually. To do this, run the rl-secure report command with the --diff-with option multiple times, each time specifying a different version to diff against. Every comparison (diff) is saved as an individual report file.

Overwriting versions​

PortalOn the Portal, you cannot upload the same version with the same name to a package where it already exists. If you try to do that, Portal will throw an error. Overwriting a version is not possible - you need to delete and re-upload the version to the same package if you want to replace it.
APIOverwriting versions is possible with the Upload and scan a version API. If the package version specified in the request already exists in the package, this API returns the 409 error response. You can repeat the request with the replace parameter in the query to overwrite the existing version.
CLIIn the CLI, when you try to scan the same version that already exists in the package store, rl-secure will warn you about the conflict. This can be resolved by running the scan command again with the --replace option to overwrite the existing version.

(Un)releasing versions​

PortalWith Portal Projects, you can unrelease a released version of your software (and vice versa) at any time, regardless of its specified release date. This is useful for keeping track of all released (or unreleased) package versions and differentiating released from unreleased versions. With this feature, you can also cancel your releases in case of any critical issues.
APIWith API, you can release or unrelease versions through the Modify a version endpoint.
CLIrl-secure does not have this functionality.