Edit the Bill of Materials (BOM) contents

During the analysis process, the Spectra Assure platform identifies components and dependencies of your software packages, and represents their relationships in the analysis reports. Spectra Assure can also detect the presence of machine learning (ML) models in your software packages.

All the relevant metadata collected during analysis then gets added to the Bill of Materials (BOM or SBOM, for Software Bill of Materials) to provide a complete inventory of your software artifact's contents. The SBOM is a key instrument in software supply chain security, providing software publishers, software consumers, and other stakeholders with a standardized way to communicate software risks, maintain audit trails, and comply with regulatory requirements.

In some cases, the automatically generated SBOM might not contain accurate information about your software's components and dependencies, or you might want to include additional details in the SBOM to make it more complete and transparent. For example, you may encounter the following situations:

Components missing from the SBOM because they were not identified during analysis
Dependencies missing from the SBOM because there is no static signature
Incorrect or missing information on components or dependencies in the SBOM
Components or dependencies not being identified as first-party

Spectra Assure supports BOM editing as a way for you to address such issues. To do that, you can create processing filters in your policy configuration that will modify the identity of specified components, dependencies, and ML models and add your custom metadata to the BOM.

A typical workflow for SBOM editing is the same as for other custom filters in policy configuration:

Scan your software with rl-secure and generate analysis reports.
In the reports, examine the SBOM and identify areas of concern you want to address with custom policy configuration.
Create the processing filters at the desired policy configuration level.
Scan your software again to apply the filters and recreate the reports to verify the SBOM has been modified correctly.

However, there are some specific guidelines for SBOM editing you should be aware of:

SBOM editing is typically done only on the package level (in the .package_policy.info file).
Every component needs to have its own filter. In other words, to modify multiple components, you need to add a separate processing.filter section for each component to your policy configuration file.
Multiple dependencies and ML models can go inside one filter. In other words, to modify multiple dependencies and ML models, you can add multiple identity objects to a single processing.filter section in your policy configuration file.
When you modify a component or dependency through policy configuration, its verified status in the SAFE report changes to Verified by User override.
Files that have their identity modified through policy configuration automatically become components, even if they were previously not identified as such. This can cause differences in the total component count when you compare the analysis reports of your software package versions.

Changes you make to component and dependency identity through policy configuration are visible in the Bill of Materials > Software section of the SAFE report. Your changes to machine learning models are visible in the Bill of Materials > ML Models section of the SAFE report.

Examples in this guide show how to modify the policy configuration for existing projects and packages in a previously created package store. If you haven't yet created any projects and packages, follow the instructions in the quick start guide.

Policy configuration fields

SBOM editing uses the following policy configuration objects and their fields:

processing.filter.identity.component
processing.filter.identity.dependency
processing.filter.identity.model_card

Consult the policy configuration schema for details on all supported options.

Edit an existing component

In this example, a software component is correctly identified and included in the analysis reports for a software package version. However, there are some metadata completeness issues with our example component:

By default, the component version has been identified as 'Generic', but we want to be specific about it.
The product name has been taken directly from the component file name, but we want it to be more representative of our software.
Additional software authors need to be declared on the component.

All these details can be observed in the Bill of Materials > Software section of the SAFE report.

We're going to edit the SBOM for this software component by modifying the policy configuration file for the software package (the .package_policy.info file) that contains the component. When changes are synchronized, the configuration will apply to all versions in that package.

In the configuration file, we're going to create one processing filter to modify the component version, name, and authors.

1. Modify package policy settings

1) In the rl-secure package store, navigate to the policy configuration file for the package and open it in a text editor. In this example, the full path to the file we're editing is /home/armando/my-repository/.rl-secure/projects/my-app/packages/my-app-windows/.package_policy.info.

2) In the .package_policy.info file, add a new processing filter.

To ensure that the filter is applied when analyzing files, set enabled to true.
With matches set to "file" and pattern set to the exact file name, the filter will target only the file(s) with that file name across package versions. We're using this because our example component is in that specific file.
In identity.component, we're specifying the metadata that we want to modify for the component. The fields product, version, publisher, and license are always required in the identity.component object. If you want to preserve the current value of any of those fields, you can copy it from the analysis report. In this case, we're preserving publisher and license, and overriding the other two.

Example processing filter
policies 
{
    profile "package_profile" 
    {
        inherit_rules "project_profile"

        processing 
        {
            filter 
            {
                enabled true
                matches "file"
                pattern "exampleLib.dll"
                
                author    "Spectra Assure"
                timestamp "2025-03-27T08:38:14+00:00"
                reason    "Edit software component identity"

                identity 
                {
                    component 
                    {
                        product   "Example Library"
                        version   "1.1.2"
                        publisher "ExampleCo"
                        license   "MIT"
                        authors {
                            author {
                                name "Additional Author"
                                email "author@email.com"
                            }
                        }               
                    }
                }
            }
        }
    }
}

3) Save changes to the file and close it.

2. Apply and verify configuration changes

1) To apply your policy configuration changes, run the following command in your package store:

rl-secure sync

The command automatically detects which packages in the package store require synchronization. Using the sync command does not count towards the monthly analysis capacity.

2) To make sure the new policy configuration is reflected in analysis reports, you have to regenerate them for all applicable package versions:

rl-secure report all --purl=pkg:rl/my-app/my-app-windows@1.0 --bundle=report.zip

3) To confirm that the policy configuration change has been successfully applied, check the SAFE report (rl-html) for details about the modified software component.

In the SAFE report, select Bill of Materials > Software from the left sidebar.
Search for the component by name or use filters to narrow down the list of displayed items.
Expand the component you modified to view its Software Identity and confirm that the information there matches your policy configuration.
In the expanded component view, there should be an Edit Record with audit information about the author of the policy configuration change, and Original Identity information with original values assigned to the component prior to your modification.

Add a new dependency

In this example, a dependency of a specific file is missing from the analysis reports. As a software publisher, we need our SBOM to be accurate and complete, so we want to include this dependency.

To do this, we're modifying the policy configuration file for the software package (the .package_policy.info file). When changes are synchronized, the configuration will apply to all versions in that package.

In the configuration file, we're going to create a processing filter to add all the relevant details about our new dependency.

1. Modify package policy settings

2) In the .package_policy.info file, add a new processing filter.

To ensure that the filter is applied when analyzing files, set enabled to true.
With matches set to "file" and pattern set to the exact file name, the filter will target only the file(s) with that file name across package versions. We're using this because a specific file depends on our example dependency.
In identity.dependency, we're specifying the metadata that describes the new dependency. The fields linking, product, version, publisher, and license are always required in the identity.dependency object.

Example processing filter
policies 
{
    profile "package_profile" 
    {
        inherit_rules "project_profile"

        processing 
        {
            filter 
            {
                enabled true
                matches "file"
                pattern "exampleWebService.dll"
                
                author    "Spectra Assure"
                timestamp "2025-03-27T08:38:14+00:00"
                reason    "Add a dependency to SBOM"

                identity 
                {
                    dependency 
                    {
                        product   "examplel2"
                        category  "Productivity"
                        community "Windows"                     
                        version   "12.1"
                        publisher "ExampleCo"
                        license   "Apache-2.0"
                        linking   "dynamic"
                        homepage  "www.example.com/our-software"
                        authors {
                            author {
                                name "Amazing Developer"
                                email "dev@example.com"
                            }
                        }
                    }
                }
            }
        }
    }
}

3) Save changes to the file and close it.

2. Apply and verify configuration changes

1) To apply your policy configuration changes, run the following command in your package store:

rl-secure sync

The command automatically detects which packages in the package store require synchronization. Using the sync command does not count towards the monthly analysis capacity.

2) To make sure the new policy configuration is reflected in analysis reports, you have to regenerate them for all applicable package versions:

rl-secure report all --purl=pkg:rl/my-app/my-app-windows@1.0 --bundle=report.zip

3) To confirm that the policy configuration change has been successfully applied, check the SAFE report (rl-html) for details about the new dependency.

In the SAFE report, select Bill of Materials > Software from the left sidebar.
Search for the dependency by name or use filters to narrow down the list of displayed items.
Expand the dependency you modified to view its Software Identity and confirm that the information there matches your policy configuration.
In the expanded dependency view, there should be an Edit Record with audit information about the author of the policy configuration change. Original Identity information should be empty because this is a new dependency added through policy configuration, and does not have any previous metadata.

Declare ML models in policy configuration

Machine learning models are deployed in a number of data formats (both standard and solution-specific). During analysis, Spectra Assure identifies those formats by their signature, allowing discovery of integrated ML models and improving risk visibility through understanding how machine learning services are deployed and used. Once identified, ML models are displayed in the ML-BOM as components. This information is visible in the Bill of Materials > ML Models section of the SAFE report.

In addition to automatically identifying thousands of publicly available ML models, Spectra Assure lets users declare their own models. It's also possible to extend the information about detected models by editing the ML-BOM.

Override generic models

In this example, an ML model is detected as generic and does not have a lot of useful information in the ML-BOM. As a software publisher, we need our BOM to be accurate and complete, so we want to override the generic model description with more details.

In the configuration file, we're going to create a processing filter to add all the relevant details about our ML model. Because ML models are identified as components, our processing filter can modify both the component-related metadata and the specific machine learning model metadata.

1. Modify package policy settings

2) In the .package_policy.info file, add a new processing filter.

To ensure that the filter is applied when analyzing files, set enabled to true.
With matches set to "file" and pattern set to the exact file name, the filter will target only the file(s) with that file name across package versions. We're using this because the specified file contains our example ML model.
In identity.component, we're specifying the component metadata that we want to modify for the ML model. The fields product, version, publisher, and license are always required in the identity.component object. If you want to preserve the current value of any of those fields, you can copy it from the analysis report. In this case, we're modifying all required fields except license.
In identity.model_card, we're specifying the metadata that describes the ML model. The fields type, family, and approach are always required in the identity.model_card object.

Example processing filter
policies 
{
    profile "package_profile" 
    {
        inherit_rules "project_profile"

        processing 
        {
            filter 
            {
                enabled true
                matches "file"
                pattern "model.data"

                author    "Spectra Assure"
                timestamp "2025-03-27T08:38:14+00:00"
                reason    "Override generic ML model"

                identity 
                {
                    component
                    {
                        product    "Example ML model"
                        version    "1.0"
                        category   "database"
                        publisher  "ExampleCo"
                        homepage  "www.example.com/our-software"
                        license    "MIT"
                    }
                
                    model_card 
                    {
                        type "LlamaForCausalLM"
                        family "transformers"
                        task "text-generation"
                        approach "unsupervised"
                        inputs "text"
                        outputs "text"
                    }                    
                }
            }
        }
    }
}

3) Save changes to the file and close it.

2. Apply and verify configuration changes

1) To apply your policy configuration changes, run the following command in your package store:

rl-secure sync

The command automatically detects which packages in the package store require synchronization. Using the sync command does not count towards the monthly analysis capacity.

2) To make sure the new policy configuration is reflected in analysis reports, you have to regenerate them for all applicable package versions:

rl-secure report all --purl=pkg:rl/my-app/my-app-windows@1.0 --bundle=report.zip

3) To confirm that the policy configuration change has been successfully applied, check the SAFE report (rl-html) for details about the ML model.

In the SAFE report, select Bill of Materials > ML Models from the left sidebar.
Find the model in the list and expand it to confirm that the information in the Model Card matches your policy configuration.
In the expanded model view, there should be an Edit Record with audit information about the author of the policy configuration change.
The file(s) listed as components that contain the machine learning model should match the file name pattern specified in your policy configuration.

Edit the Bill of Materials (BOM) contents

Edit an existing component​

1. Modify package policy settings​

2. Apply and verify configuration changes​

Add a new dependency​

1. Modify package policy settings​

2. Apply and verify configuration changes​

Declare ML models in policy configuration​

Override generic models​

1. Modify package policy settings​

2. Apply and verify configuration changes​

Edit an existing component

1. Modify package policy settings

2. Apply and verify configuration changes

Add a new dependency

1. Modify package policy settings

2. Apply and verify configuration changes

Declare ML models in policy configuration

Override generic models

1. Modify package policy settings

2. Apply and verify configuration changes