Using Package Labels

Overview

Package Labels are a powerful way to annotate your dependencies with additional information, enabling better reporting, filtering, and (in future releases) automated issue management. Labels provide context about how a package is used within your projects or organization, helping your team make informed decisions about licensing obligations and compliance.

Key Concepts

Labels: Labels are a string limited to 50 characters that can be applied to a package using various scopes

Scope: Defines the where a label is applied

Project Scope: The label is only applied within the project

Global Scope: The label is applied globally, across all projects within your organization

Revision Scope: The label is only applied within the current revision of the project

Use Cases

Package Labels are designed to be flexible and support a variety of scenarios, including:

Usage-Based Labeling:

• Marking dependencies as "Modified" or "Unmodified" to track changes that might affect license compliance.
• Indicating the linkage type ("Statically Linked" or "Dynamically Linked") to determine how licensing rules apply.
• Tagging dependencies as "Dev", "Test" or "Production" to differentiate their usage context.

Attribute-Based Labeling:

• Adding Export Control Classification Numbers (ECCN) for export compliance reporting.
• Tracking FIPS compliance status

Creating a Package Label via the FOSSA web app

Package labels can be created via the organization settings page. Here are the steps to create a package label:

1. Navigate to the settings page within the menu under your user account
2. Click on the 'Organization' tab
3. Navigate to the Package Label section
4. Click on the 'Add Label' button to create a label
5. Created labels are available across the organization

Please note the following criteria for creating a package label:

• 1-50 Characters
• Alpha-numeric
• Dashes, Underscores and Spaces are supported special characters

Editing a Package Label via the FOSSA web app

1. Navigate to the settings page within the menu under your user account
2. Click on the 'Organization' tab
3. Navigate to the Package Label section
4. Click on the edit icon beside a package label to edit the label name

Deleting a Package Label via the FOSSA web app

1. Navigate to the settings page within the menu under your user account
2. Click on the 'Organization' tab
3. Navigate to the Package Label section
4. Click on the 'x' icon to delete a Package Label

Adding a Package Label to a Package

1. Navigate to the list of dependencies within a project
2. Click on the 3-dot menu to the right of any package
3. Click on 'Manage Labels'
4. In the model, select the label(s) that you would like to have applied to the package

• Package labels can also be applied to a package via the Package Index

Generating Reports with Package Labels

• Package Labels are supported in reports by clicking on the 'Package Labels' box when generating a report via the UI, or using the ?includePackageLabels=true parameter when using the API
  • Package Labels will appear in-line with each package in the report
• Packages can also be excluded from a report based on a Package Label(s) by selecting the Package Labels to exclude from the dropdown in the UI when generating a report

Filtering Packages by Package Label

• Dependencies across the product can be filter using applied Package Label(s) by selecting the label(s) in the filter dropdown provided

Permissions

• Creating and Deleting Labels: Org Admins have permission to create and delete labels by default. This uses the existing Project labels permission.
• Assigning Project Scoped Labels: Team Admins have permission to assign project scoped labels by default.
• Assigning Org Scoped Labels: Admins have permission to assign org scoped labels by default.

Managing Package Labels via the FOSSA API

The API reference for Package Labels is available here

Managing Package Labels via FOSSA CLI

Package Labels are supported when using a fossa-deps file. See documentation here