This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

SBOM Generation and Management

A software bill of materials (SBOM) is a comprehensive inventory of the individual components from source repositories and container images. One or more SBOMs can be grouped together in higher-level applications to visualize related artifacts in applications by versions. Applications are the top-level building block in a hierarchical view, and can represent any project your teams deliver.

Security Engineers are often required to investigate security issues that stem from a source repository or from container images. The security team can use Anchore Enterprise to identify any open source security vulnerabilities or policy evaluation results which originate from a source code repository or image container. This helps them catch security issues earlier.

You can generate SBOMs using AnchoreCTL as part of a command line or CI/CD workflow, through pulling content from a registry, or by submitting an artifact to the Anchore API.

SBOMs can be managed using the command line, API or GUI, where contents can be grouped together, annotated, viewed or searched. Artifact metadata, vulnerability information, and policy evaluations can also be viewed and managed through the same interfaces.

All SBOMs can be downloaded into a variety of formats, either individually or collectively, to be sent to security teams, customers or end-users.

1 - Observe Applications in Enterprise

Observe Applications in Enterprise

You can use the Anchore Enterprise GUI to see a summary of the applications that have been collected into an application. From the application view, you can drill down into the source repositories or container images that make up the application, and browse their software bill of materials (SBOMs).

1.1 - View Applications from Image Containers

To work with image container data, you must first load the image container data into the Application view of Enterprise. Once your data is brought in, you can go to Applications to see the summary of the information. The information is categorized by applications, with sub-categories of application versions available from container images. For information about analyzing images, see Image Analysis. For information about adding Images, see Scanning Repositories.

Container Image Application summary

When you select an application version, you will see a list of artifacts associated with that application version.

Container Images

You can download a report for everything in the application or for an individual artifact. The application level download supports JSON format. Artifact level download supports JSON, SPDX, CycloneDX formats.

Container Images SBOM Report

When you select an artifact link, you will see the analysis options for that artifact. You can then view information about the artifact, such as the policies set up, the vulnerabilities, software bill of materials (SBOM) contents, image metadata information, build summary, and action workbench.

Container Images Analysis

If you want to set up policies, as well as mappings for an artifact, select *Policies to set them up there.

See Policies for more information. See Policy Mappings for more information.

Policies

1.2 - View Applications from Source Repositories

To work with source repository data, you must first use AnchoreCTL or the Anchore API to load the source repository into the Applications view of Enterprise.

Once your data is brought in, you can go to the Applications tab to see the summary of the information. The information is categorized by applications, with sub-categories of application versions available from source repositories.

Source Repository Application Summary

When you select an application version, you will see a list of artifacts associated with that application version.

Source Repository

You can download a report for everything in the application or for an individual artifact. The application level download supports JSON format. Artifact level download supports JSON, SPDX, CycloneDX formats.

Source Repository SBOM Report

When you select an artifact link, you will see the analysis options for that artifact. You can then view information about the artifact, such as the policies set up, the vulnerabilities, software bill of materials (SBOM) contents, and source metadata information.

Source Repositories Analysis

If you want to set up policies, as well as mappings for an artifact, select the Policies tab and set them up there.

For information about policies, see Policies. For information about adding policy mapping, see Policy Mappings.

Policies

1.3 - Work with Applications Generated from Image Containers

To work with image container data in Anchore Enterprise, you must first load the image container data into Enterprise. For more information, see Scanning Repositories.

Once the data is made available to Anchore Enterprise, you can then analyze it. An example workflow might be as follows.

  1. Start Anchore Enterprise. You will default to the dashboard view. The Dashboard is your configurable landing page where insights into the collective status of your container image environment. The summary information is displayed through various widgets. Utilizing the Enterprise Reporting Service, the widgets are hydrated with metrics which are generated and updated on a cycle, the duration of which is determined by application configuration. See Dashboard for more information about what you can view.

  2. Click Applications > Container Images to view a summary of the applications in your container images. The information is categorized by applications, with sub-categories of application versions available from image containers that you previously loaded. Notice the list of applications and application versions, as well as any artifacts in the applications.

Container Image Application summary

  1. Click SBOM Report Updated Application name to download a software bill of materials (SBOM) report in JSON format for everything in an application. Or, click SBOM Report to download a report for everything in an artifact.

  2. Click an artifact link under Repository Name to view the detailed information for the artifact.

Container Image Artifact Link

The Images analysis screen for an artifact shows you a summary of what is in that artifact.

Container Images Analysis

  1. From the analysis screen, you can perform the following actions.
  • Click Policy Compliance to view the policies set up for the artifact. You can see the policy rules that are set up as well.
  • Click Vulnerabilities to view the vulnerabilities associated with the artifact.
  • Click SBOM to view the contents of the SBOM(s) associated with the artifact.
  • Click Image Metadata to view the metadata information for the artifact.
  • Click Build Summary to see the Manifest, Dockerfile, and Docker History of your artifact.
  • Click Action Workbench to see the action plans and history for an image artifact.
  • You have the option to click SBOM Report to download a report for everything in the artifact.
  • You also have the option to click Compliance Report to download a report that shows the compliance information in the artifact.
  1. Click Policies to set up the rules for the analyzed container image.

See Policies for more information. See Policy Mappings for more information.

1.4 - Work with Applications Generated from Source Repositories

To work with source repository data in Anchore Enterprise, you must first use AnchoreCTL or the Anchore API to load the source repository into Enterprise.

Once the data is made available to Anchore Enterprise, you can then view and generate reports specific to an application version. An example workflow might be as follows.

  1. Start Anchore Enterprise. You will default to the dashboard view. The Dashboard is your configurable landing page where insights into the collective status of your source repository. The summary information is displayed through various widgets. Utilizing the Enterprise Reporting Service, the widgets are hydrated with metrics which are generated and updated on a cycle, the duration of which is determined by application configuration. See Dashboard for more information about what you can view.

  2. Click Applications > Source Repositories to view a summary of the applications in your source repository. The information is categorized by applications, with sub-categories of application versions available from source repositories that you previously loaded via AnchoreCTL or the Anchore API. Notice the list of applications and application versions, as well as any artifacts in the applications.

Source Repository Application Summary

  1. Click SBOM Report Updated Application name to download a software bill of materials (SBOM) report in JSON format for everything in an application. Or, click SBOM Report to download a report for everything in an artifact.

  2. Click an artifact link for a soure repository under Repository Name to view the detailed information for the artifact.

Source Repository Artifact Link

The Sources analysis screen for an artifact shows you a summary of what is in that artifact.

Source Repository Analysis

  1. From the analysis screen, you can perform the following actions.
  • Click Policy Compliance to view the policies set up for the artifact. You can see the policy rules that are set up as well.
  • Click Vulnerabilities to view the vulnerabilities associated with the artifact.
  • Click SBOM to view the contents of the SBOM(s) associated with the artifact.
  • Click Source Metadata to view the metadata information for the artifact.
  • You have the option to click SBOM Report to download a report for everything in the artifact.
  • You also have the option to click Compliance Report to download a report that shows the compliance information in the artifact.
  1. Click Policies to set up the rules for the analyzed source repository. The rules set up for an artifact source repository are different from what you apply to a container image.

See Policies for more information. See Policy Mappings for more information.

2 - Anchore Enterprise Application Groups

Anchore Enterprise lets you model your versioned applications to create a comprehensive view of the vulnerability and security health of the projects your teams are building across the breadth of your Software Delivery Lifecycle.

By grouping related components into applications, and updating those components across application versions as projects grow and change, you can get a holistic view of the current and historic security health of the applications from development through built image artifacts.

The typical flow is:

  • An application will be created for each project that you want to track.
  • Versions will be created both for the current in-development version and for previous versions.
  • Artifacts will be grouped together under those application versions.

Applications, application versions, and artifact associations can be managed via either the applications API or AnchoreCTL.

2.1 - Application Components

Applications

Applications are the top-level building block in this hierarchical view, containing artifacts like packages or image artifacts. Applications can represent any project your teams deliver. Applications have user-specified name and description fields to describe them. Applications are expected to be long-lived constructs, typically with multiple versions added over time.

Application Versions

Each application is associated with one or more application versions. Application versions track the specific grouping of artifacts that comprise a product version. They have one directly user-editable field called version_name which reflects the name of the product’s application version. This field has no special constraints on it, so you can use it to reflect the versioning scheme or schemes for your projects.

Each application, on creation, automatically has one application version created for it, named “HEAD”. “HEAD” is a special version meant to track the in-development version of your product through its release. A typical flow is that, as your CI jobs build new versions of your software, they will add new versions of your source and image artifacts to Anchore Enterprise and associate them with your HEAD application version. On release, you update your “HEAD” version to reflect the actual name of your release (for example, “v1.0.0”), and then create a new “HEAD” version to track development on the next version of your project. Any application version, including the “HEAD” version, can be deleted if needed.

Application versions, rather than applications, are directly associated with artifacts from sources and images. As your project grows and evolves, the packages and package versions associated with it will naturally change and advance over time. Associating them with application versions (rather than directly with applications) allows older application versions to maintain their associations with the older packages that compose them. This allows for historical review auditing and comparison across versions.

Associating Artifacts with Application Versions

An artifact is a generic term that encompasses any SDLC artifact that can be associated with an application version. Currently, that includes sources and images. The application API has endpoints (and AnchoreCTL has subcommands) to manage the associations between application versions and artifacts.

One important distinction is that these endpoints and commands are operating on the association between artifacts and application versions, not on the artifacts themselves. A source or image must already be added to Anchore Enterprise before it can be associated with an application. Similarly, removing the association with an application version does not remove the artifact from Anchore Enterprise. It can later be re-associated with the application version, or another application version.

Application Version software bill of materials (SBOM)

Once an application version has artifacts associated with it, users can generate an application version SBOM, which aggregates the SBOMs for all of the artifacts associated with the application version.

Application Version Vulnerabilities

Users can generate a list of vulnerabilities within an application version. This will be an aggregate of all vulnerabilities found within the artifacts associated with the specific application version.

2.2 - Application Features with the Anchore Enterprise GUI

Anchore Enterprise lets you use the UI to see a summary of the applications available from source repositories. You can perform an analysis of the application and artifact data.

Additionally, you can set your policies and mappings for a source repository, similar to how you set them up for images.

2.3 - Application Management - Anchore API

Use the Anchore API to manage your applications. For more information about using Anchore APIs via Swagger, see: Using the Anchore API.

The API application workflow would be like the following.

Create an Application

Create an application by POSTing the JSON in the block below to http://<host:port>/v2/applications/.

{
   "name": "Application name",
   "description": "Application description"
}

Note: Creating an application will also create an application version named HEAD, used to track the in-development version.

GET the List of All Applications

GET the list of all applications from ​​http://<host:port>/v2/applications/.

Add the include_versions=true flag to include all application versions under each application in the API response.

GET a Single Application

GET a single application by adding the application_id to the GET command. For example: http://<host:port>/v2/applications/<application_id>/.

Add the include_versions=true flag to include all application versions under each application in the API response.

Update an Existing Application

PUT the following to http://<host:port>/v2/applications/<application_id>/ to update an existing application, such as changing the name and description.

{
   "name": "Updated application name",
   "description": "Updated application description"
}

Remove a Specified Application

Send a DELETE to http://<host:port>/v2/applications/<application_id>/ to remove the specified application.

2.3.1 - Application Version Management - Anchore API

Use the Anchore API to manage your application versions. For more information about using Anchore APIs via Swagger, see: Using the Anchore API.

The API application workflow would be like the following.

Create an Application Version

To use the Anchore API to create an application version that is associated with an already-existing application, POST the JSON in the block below to http://<host:port>/v2/applications/<application_id>/versions/.

{
   "version_name": "v1.0.0"
}

GET the List of All Application Versions

GET the list of all application versions for the application from http://<host:port>/v2/applications/<application_id>/ versions.

GET a Single Application Version

GET a specific application version from http://<host:port>/v2/applications/<application_id>/versions/<application_version_id>.

Update an Existing Application

To update the name of an existing application version, PUT the following to http://<host:port>/v2/applications/<application_id>/versions/<application_version_id>

{
    "version_name": "v1.0.1"
}

Remove a Specified Application Version

To delete an application version, Send a DELETE to http://<host:port>/v2/applications/<application_id>/versions/<application_version_id>.

2.3.2 - Associate Artifacts with Application Versions - Anchore API

Add an Artifact Association

The following commands require source or image artifacts to already be added to the Anchore Enterprise instance before they can be associated with the application version.

Note: Keep track of the uuid of the sources, and the digest of the images that you will add to the application version. These are the values used to associate each artifact with the application version.

The response body for each artifact association request will contain an artifact_association_metadata block with an association_id field in it. This field uniquely identifies the association between the artifact and the application version, and is used in requests to remove the association.

Associate a Source Artifact

To associate a source artifact, POST the following body to http://<host:port>/v2/applications/<application_id>/versions/<application_version_id>/artifacts.

Note the fields specific to source artifacts in contrast to the image artifact in the next example.

{
    "artifact_type": "source",
    "artifact_keys": {
        "uuid": "<source uuid>"
    }
}

Associate an Image Artifact

To associate an image artifact, POST the following body to http://<host:port>/v2/applications/<application_id>/versions/<application_version_id>/artifacts.

Note the fields specific to image artifacts in contrast to the source artifact in the previous example.

{
    "artifact_type": "image",
    "artifact_keys": {
        "image_digest": "<image_digest>"
    }
}

List All Associated Artifacts

Each artifact in the response body will contain an artifact_association_metadata block with an association_id field in it. This field uniquely identifies the association between the artifact and the application version, and is used in requests to remove the association.

List All Artifacts Associated with an Application Version

To list all artifacts associated with an application version, GET http://<host:port>/v2/applications/<application_id>/versions/<application_version_id>/artifacts.

Filter the Results by Artifact Type

To filter the results by artifact type, add the artifact_types=<source,image> query parameter.

Remove an Artifact Association

Send a DELETE request to http://<host:port>/v2/applications/<application_id>/versions/<application_version_id>/artifacts/<association_id>.

2.3.3 - Application Version Operations - Anchore API

Users can perform queries against specific versions of an application.

SBOM for a specific Application Version

Using the application API to generate a combined software bill of materials (SBOM) for all artifacts within an application version. This lets you easily archive the components, or provide them to others for verification process compliance requirements. The data structure metadata for the application and application version, along with the SBOMs for each artifact associated with the application version.

Download a Combined SBOM

To download a combined SBOM, GET the application version SBOM from http://<host:port>/v2/applications/<application_id>/versions/<application_version_id>/sboms/native-json.

To filter the results by artifact type, add the artifact_types=<source,image> query parameter.

Vulnerabilities for a specific Application Version

Using the application API, a user can generate a combined list of vulnerabilities found among all artifacts within an application version. This allows easier vulnerability management for any Application Version.

Get a Combined Vulnerabilities List

http://<host:port>/v2/applications/<application_id>/versions/<application_version_id>/vulnerabilities.

Optional query parameter of will_not_fix=<true | false> is provided. When true, the results will include any vulnerabilities that the vendor of an image distribution either disagrees with or does not intend to prioritize for remediation

2.4 - Application Management - AnchoreCTL

Use AnchoreCTL to manage your applications. The AnchoreCTL application workflow would be like the following.

Create a Named Application

Use AnchoreCTL to create a named application. For example: anchorectl application add <name> --description <description>

Note: Creating an application will also create an application version named HEAD, used to track the in-development version.

List All Applications

Use the AnchoreCTL to list all applications. For example: anchorectl application list.

Request an Individual Application

Request an individual application from Anchore via AnchoreCTL to view details about it. For example: anchorectl application get <application_name>.

Update and Change Properties of an Existing Application

Update and change the properties of an existing application via AnchoreCTL.

For example, change the application name and description as follows: anchorectl application update <application_name> --name <new_name> --description <new_description>.

Remove an Application

Use AnchoreCTL to delete applications. This lets you remove applications that are no longer useful or important to you. For example: anchorectl application delete <application_name>

2.4.1 - Application Version management - AnchoreCTL

Use AnchoreCTL to manage your application versions.

The AnchoreCTL application workflow would be like the following.

Create and Store Versions of your Application

Use AnchoreCTL to create and store versions of your applications. Versioning is useful for audit compliance and reporting. Use the following AnchoreCTL command to create a version:

anchorectl application version add <application-name>@<version-name>

List All Application Versions

Use AnchoreCTL to list all application versions that are associated with an application.

anchorectl application version list <application_name>

Update Application Version Properties

Use AnchoreCTL to update application version properties for an existing application in Anchore.

anchorectl application version update <application-name>@<version-name> --name <new_version_name>

Request a Specific Application Version

Use AnchoreCTL to request a specific version of an application to view its details. The following example shows the AnchoreCTL command to request a version:

anchorectl application version get <application-name>@<version-name>

Remove Application Version

Use AnchoreCTL to delete application versions. This lets you remove application versions that are no longer useful or important to you.

anchorectl application version delete <application-name>@<version-name>

2.4.2 - Get an Application Version SBOM - AnchoreCTL

Run the anchorectl application version sbom <application_id> <application_version_id> -o json command to download a combined software bill of materials (SBOM) for all components and supply-chain elements of an application. This lets you easily archive the components, or provide them to others for verification process compliance requirements. The data structure includes the version and version metadata for the application version, along with the SBOMs for each associated artifact.

To filter the results by artifact type, add the argument –-type <source,image> to the end of the command.

2.4.3 - Associate Artifacts with Application Versions - AnchoreCTL

Add an Artifact Association

The following commands require source or image artifacts to already be added to the Anchore Enterprise instance before they can be associated with the application version.

Note: Keep track of the uuid of the sources, and the digest of the images that you will add to the application version. These are the values used to associate each artifact with the application version.

The response body for each artifact association request will contain an artifact_association_metadata block with an association_id field in it. This field uniquely identifies the association between the artifact and the application version.

Associate a Source Artifact

To associate a source artifact: anchorectl application artifact add <application-name>@<version-name> source <source_uuid>

Associate an Image Artifact

To associate an image artifact: anchorectl application artifact add <application-name>@<version-name> image <image_digest>

List All Associated Artifacts

To list all artifacts associated with an application version: anchorectl application artifact list <application-name>@<version-name>

To filter the results by artifact type, add the argument --type <source,image> to the end of the command.

Remove an Artifact Association

Get the association_id of one of the associated artifacts and run the following command: anchorectl application artifact remove <application-name>@<version-name> <artifact_id>

3 - Generating SBOMs for a Source Repository using AnchoreCTL

Use anchorectl to generate a software bill of materials (SBOM) and import a source repository artifact from a file location on disk. You can also get information about the source repository, investigate vulnerability packages by requesting vulnerabilities for a single analyzed source repository, or get any policy evaluations. The workflow would generally be as follows.

  1. Generate an SBOM. The format is similar to the following: syft <path> -o json > <resulting filename>.json For example:
$ syft dir:/path/to/your/source/code -o json > my_sbom.json
  1. Import the SBOM from a source with metadata. This would normally occur as part of a CI/CD pipeline, and the various metadata would be programmatically added via environment variables. The response from anchorectl includes the new ID of the Source in Anchore Enterprise. For example:
# anchorectl source add github.com/my-project@12345 --branch test --author [email protected] --workflow-name default --workflow-timestamp 2002-10-02T15:00:00Z --from ./my_sbom.json
 ✔ Added Source                                                                          github.com/my-project@12345
 ✔ Imported SBOM                                                                                         /tmp/s.json
Source:
  status:           not-analyzed (active)
  uuid:             fa416998-59fa-44f7-8672-dc267385e799
  source:           github.com/my-project@12345
  vcs:              git
  branch:           test
  workflow:         default
  author:           [email protected]
  1. List the source repositories that you have sent to Anchore Enterprise. This command will allow the operator to list all available source repositories within the system and their current status.
# anchorectl source list
 ✔ Fetched sources
┌──────────────────────────────────────┬────────────┬─────────────────────┬──────────────────────────────────────────┬─────────────────┬───────────────┐
│ UUID                                 │ HOST       │ REPOSITORY          │ REVISION                                 │ ANALYSIS STATUS │ SOURCE STATUS │
├──────────────────────────────────────┼────────────┼─────────────────────┼──────────────────────────────────────────┼─────────────────┼───────────────┤
│ fa416998-59fa-44f7-8672-dc267385e799 │ github.com │ my-project          │ 12345                                    │ analyzed        │ active        │
└──────────────────────────────────────┴────────────┴─────────────────────┴──────────────────────────────────────────┴─────────────────┴───────────────┘
  1. Fetch the uploaded SBOM for a source repository from Anchore Enterprise. The for this command is taken from the UUID(s) of the listed source repositories.
# anchorectl source sbom fa416998-59fa-44f7-8672-dc267385e799 -f /tmp/sbom.json
 ✔ Fetched SBOM
  1. Get detailed information about a source. For example:
# anchorectl source get fa416998-59fa-44f7-8672-dc267385e799
 ✔ Fetched source
Uuid: fa416998-59fa-44f7-8672-dc267385e799
Host: github.com
Repository: my-project
Revision: 12345
Vcs Type: git
Metadata Records:
  - branchName: test
    changeAuthor: [email protected]
    ciWorkflowExecutionTime: "2002-10-02T15:00:00Z"
    ciWorkflowName: default
    uuid: ae5f6617-5ad5-47dd-81ca-8fcb10391fed
Analysis Status: analyzed
Source Status: active
  1. Use anchorectl to investigate vulnerability packages by requesting vulnerabilities for a single analyzed source repository. You can choose os, non-os, or all. For example:
# anchorectl source vulnerabilities fa416998-59fa-44f7-8672-dc267385e799
 ✔ Fetched vulnerabilities                   [48 vulnerabilities]                                                                                                                                                             fa416998-59fa-44f7-8672-dc267385e799
┌─────────────────────┬──────────┬────────────┬─────────┬────────┬──────────────┬──────┬─────────────┬───────────────────────────────────────────────────┐
│ ID                  │ SEVERITY │ NAME       │ VERSION │ FIX    │ WILL NOT FIX │ TYPE │ FEED GROUP  │ URL                                               │
├─────────────────────┼──────────┼────────────┼─────────┼────────┼──────────────┼──────┼─────────────┼───────────────────────────────────────────────────┤
│ GHSA-p6xc-xr62-6r2g │ High     │ log4j-core │ 2.14.1  │ 2.17.0 │ false        │ java │ github:java │ https://github.com/advisories/GHSA-p6xc-xr62-6r2g │
│ GHSA-7rjr-3q55-vv33 │ Critical │ log4j-core │ 2.14.1  │ 2.16.0 │ false        │ java │ github:java │ https://github.com/advisories/GHSA-7rjr-3q55-vv33 │
│ GHSA-8489-44mv-ggj8 │ Medium   │ log4j-core │ 2.14.1  │ 2.17.1 │ false        │ java │ github:java │ https://github.com/advisories/GHSA-8489-44mv-ggj8 │
│ CVE-2021-45105      │ Medium   │ log4j-api  │ 2.14.1  │ None   │ false        │ java │ nvd         │ https://nvd.nist.gov/vuln/detail/CVE-2021-45105   │
...
  1. Use anchorectl to compute a policy evaluation for a source. For example:
# anchorectl source check fa416998-59fa-44f7-8672-dc267385e799
 ✔ Evaluated against policy                  [failed]                                                                                                                                                                         fa416998-59fa-44f7-8672-dc267385e799
Evaluation ID: 3e490750b404eb1b09baf019a4df3942
Source ID: fa416998-59fa-44f7-8672-dc267385e799
Host: github.com
Repository: my-project
Policy ID: 2c53a13c-1765-11e8-82ef-23527761d060
Updated: 2022-08-30T15:58:24Z
Evaluation: fail

(Use -o json option to get more detailed output)

  1. Use anchorectl to delete any individual source repository artifacts from Anchore Enterprise. For example:
# anchorectl source delete fa416998-59fa-44f7-8672-dc267385e799
 ✔ Deleted source
Uuid: fa416998-59fa-44f7-8672-dc267385e799
Host: github.com
Repository: my-project
Revision: 12345
Vcs Type: git
Metadata Records:
  - branchName: test
    changeAuthor: [email protected]
    ciWorkflowExecutionTime: "2002-10-02T15:00:00Z"
    ciWorkflowName: default
    uuid: ae5f6617-5ad5-47dd-81ca-8fcb10391fed
Analysis Status: analyzed
Source Status: deleting

4 - Generating SBOMs for a Source Repository using the API

Use the Anchore API to import a source repository artifact from a software bill of materials (SBOM) file on disk. You can also get information about the source repository, investigate vulnerability packages by requesting vulnerabilities for a single analyzed source repository, or get any policy evaluations.

For more information about using Anchore APIs via Swagger, see: Using the Anchore API.

The SBOM management API workflow would generally be as follows.

Note: Reference the API endpoints in Swagger for the latest information.

  1. Once you have generated a SBOM using anchorectl, you can use the API to import that SBOM as a source artifact. For example, to create the import “operation” (job) for importing a source.
curl -u admin:foobar -X 'POST' 'http://localhost:8228/v2/imports/sources'

{
    "created_at": "2023-10-27T16:26:33Z",
    "expires_at": "2023-10-28T16:26:33Z",
    "last_updated": "2023-10-27T16:26:33Z",
    "status": "pending",
    "uuid": "b78cda3b-eff7-4e2e-a1ed-e3f8433435cf"
}
  1. Add the SBOM to the import operation. For example:
curl -u admin:foobar -X POST http://localhost:8228/v2/imports/sources/767c77fe-8f93-4e7e-a9ff-f0f39e2a80ba/sbom -d @/absolute/path/to/your/sbom.json -H "Content-Type: application/json"

{
    "created_at": "2022-02-28T20:36:32Z", 
    "digest": "6778145cdda7a3443abc9650683c6d5bf8a87e3e6b4b3c8868224e7755680446"
}
  1. Finalize the import. For example:
curl -X 'POST' 'http://localhost:8228/v2/imports/sources/767c77fe-8f93-4e7e-a9ff-f0f39e2a80ba/finalize'
  -H 'accept: application/json'
  -H 'Content-Type: application/json’
  -d '{
  "branch_name": "main",
  "change_author": "[email protected]",
  "ci_workflow_execution_time": "2022-02-28T20:38:13.117Z",
  "ci_workflow_name": "default",
  "contents": {
    "sbom": "6778145cdda7a3443abc9650683c6d5bf8a87e3e6b4b3c8868224e7755680446"
  },
  "host": "http://github.com",
  "repository_name": "anchore-engine",
  "revision": "8f7e4afb9bc9a284e24b69e529863a0b99373bf7"
}'

{
  "account_name": "admin",
  "analysis_status": "not_analyzed",
  "created_at": "2022-02-28T20:43:58Z",
  "host": "http://github.com",
  "last_updated": "2022-02-28T20:43:58Z",
  "metadata_records": [
    {
      "branch_name": "main",
      "change_author": "[email protected]",
      "ci_workflow_execution_time": "2022-02-28T20:38:13Z",
      "ci_workflow_name": "default",
      "uuid": "8b97a668-2044-4f24-a5af-6010e7957ac3"
    }
  ],
  "repository_name": "anchore-engine",
  "revision": "8f7e4afb9bc9a284e24b69e529863a0b99373bf7",
  "source_status": "active",
  "uuid": "a0eb87e2-61ef-4721-bb16-9682ad528bbe",
  "vcs_type": "git"
}
  1. List all sources that you’ve imported. For example:
curl -u admin:foobar -X 'GET' 'http://localhost:8228/v2/sources'
{
    "items" : [
      {
        "account_name": "admin",
        "analysis_status": "analyzed",
        "created_at": "2022-02-28T20:43:58Z",
        "host": "http://github.com",
        "last_updated": "2022-02-28T20:43:58Z",
        "repository_name": "anchore-engine",
        "revision": "8f7e4afb9bc9a284e24b69e529863a0b99373bf7",
        "source_status": "active",
        "uuid": "a0eb87e2-61ef-4721-bb16-9682ad528bbe"
      },
      …
    ]
}
  1. Get information about a single source that you’ve imported. For example:
curl -u admin:foobar -X 'GET' 'http://localhost:8228/v2/sources/a0eb87e2-61ef-4721-bb16-9682ad528bbe'

{
  "account_name": "admin",
  "analysis_status": "analyzed",
  "created_at": "2022-02-28T20:43:58Z",
  "host": "http://github.com",
  "last_updated": "2022-02-28T20:43:58Z",
  "metadata_records": [
    {
      "branch_name": "main",
      "change_author": "[email protected]",
      "ci_workflow_execution_time": "2022-02-28T20:38:13Z",
      "ci_workflow_name": "default",
      "uuid": "8b97a668-2044-4f24-a5af-6010e7957ac3"
    }
  ],
  "repository_name": "anchore-engine",
  "revision": "8f7e4afb9bc9a284e24b69e529863a0b99373bf7",
  "source_status": "active",
  "uuid": "a0eb87e2-61ef-4721-bb16-9682ad528bbe",
  "vcs_type": "git"
}
  1. Fetch a gzip compressed copy of the sbom for a specific type. For example:
curl -X 'GET' -u admin:foobar 'http://localhost:8228/v2/sources/a0eb87e2-61ef-4721-bb16-9682ad528bbe/sbom/native-json'
curl -X 'GET' -u admin:foobar 'http://localhost:8228/v2/sources/a0eb87e2-61ef-4721-bb16-9682ad528bbe/sbom/cyclonedx-json'
curl -X 'GET' -u admin:foobar 'http://localhost:8228/v2/sources/a0eb87e2-61ef-4721-bb16-9682ad528bbe/sbom/spdx-json'
  1. Get the types of vulnerabilities that you may fetch with respect to a source. For example:
curl -X 'GET'  -u admin:foobar 'http://localhost:8228/v2/sources/a0eb87e2-61ef-4721-bb16-9682ad528bbe/vuln'


[
  "os",
  "non-os",
  "all"
]
  1. Get the vulnerabilities for a source. For example:
curl -X 'GET' -u admin:foobar 'http://localhost:8228/v2/sources/a0eb87e2-61ef-4721-bb16-9682ad528bbe/vuln/all'

{
  "source_id": "a0eb87e2-61ef-4721-bb16-9682ad528bbe",
  "vulnerabilities": [
    {
        "feed": "vulnerabilities",
        "feed_group": "nvd",
        "fix": "None",
        "nvd_data": [
            {
            "cvss_v2": {
                "base_score": 5,
                "exploitability_score": 10,
                "impact_score": 2.9
            },
            "cvss_v3": {
                "base_score": 7.5,
                "exploitability_score": 3.9,
                "impact_score": 3.6
            },
            "id": "CVE-2019-13509"
            }
        ],
        "package": "docker-4.3.1",
        "package_cpe": "None",
        "package_cpe23": "cpe:2.3:a:docker:docker:4.3.1:*:*:*:*:*:*:*",
        "package_name": "docker",
        "package_path": "/Users/vijay/Documents/enterprise/requirements-test.txt",
        "package_type": "python",
        "package_version": "4.3.1",
        "severity": "High",
        "url": "https://nvd.nist.gov/vuln/detail/CVE-2019-13509",
        "vendor_data": [],
        "vuln": "CVE-2019-13509",
        "will_not_fix": false
        },
    …
  ],
  "vulnerability_type": "all"
}
  1. Get the policy evaluation for a source. For example:
curl -X 'GET' -u admin:foobar 'http://localhost:8228/v2/sources/a0eb87e2-61ef-4721-bb16-9682ad528bbe/check'

[
  {
    "account_name": "admin",
    "created_at": "2022-02-28T21:11:37Z",
    "evaluation_id": "7a4611f2fa26d80bd680782eb379081f",
    "evaluation_url": "policy_evaluations/7a4611f2fa26d80bd680782eb379081f",
    "final_action": "fail",
    "final_action_reason": "policy_evaluation",
    "findings": [
        {
            "action": "warn",
            "allowlist_match": null,
            "allowlisted": false,
            "gate": "vulnerabilities",
            "message": "MEDIUM Vulnerability found in non-os package type (gem) - /syft/pkg/cataloger/ruby/test-fixtures/Gemfile.lock (fixed in: 4.1.11)(GHSA-vxvp-4xwc-jpp6 - https://github.com/advisories/GHSA-vxvp-4xwc-jpp6)",
            "policy_id": "f2dbc082-7d10-432a-9f62-02ea8f1e5dbf",
            "recommendation": "",
            "rule_id": "24c7ec4f-d795-4ee3-93e7-4d603560ddb3",
            "trigger": "package",
            "trigger_id": "GHSA-vxvp-4xwc-jpp6+Gemfile.lock"
        },
        ...
    ]
    "host": "http://github.com",
    "matched_mapping_rule": {
        "host": "*",
        "id": "9a899100-6e4c-4038-93ba-12f6d8ab97b3",
        "name": "default-source-mapping",
        "policy_id": "f2dbc082-7d10-432a-9f62-02ea8f1e5dbf",
        "repository": "*",
        "allowlist_ids": [
          "37fd763e-1765-11e8-add4-3b16c029ac5c"
        ]
    },
    "number_of_findings": 149,
    "last_updated": "2022-02-28T21:11:37Z",
    "policy_id": "2c53a13c-1765-11e8-82ef-23527761d060",
    "policy": {
        "allowlisted_images": [],
        "allowlists": [
            {
                "description": "Default global allowlist",
                "id": "37fd763e-1765-11e8-add4-3b16c029ac5c",
                "items": [],
                "name": "Global Allowlist",
                "version": "2"
            }
        ],
        "denylisted_images": [],
        "description": "Default bundle",
        "id": "2c53a13c-1765-11e8-82ef-23527761d060",
        ...
    },
    "repository_name": "anchore-engine",
    "revision": "8f7e4afb9bc9a284e24b69e529863a0b99373bf7",
    "source_id": "a0eb87e2-61ef-4721-bb16-9682ad528bbe",
     "source_mapped_to_rule": true,
     "status": "fail"
  }
]
  1. Delete any individual source repository SBOM artifact from Anchore Enterprise. For example:
curl -X 'DELETE' -u admin:foobar  'http://localhost:8228/v2/sources/a0eb87e2-61ef-4721-bb16-9682ad528bbe'

5 - SBOM Drift

Software bill of materials (SBOM) drift is understanding how SBOMs change over time, and is a key part of managing your SBOMs. The nature of changes themselves may give early warning into unexpected behavior or intrusion into the build system that a review without context from previous builds would not easily be able to identify.

To do this, you set triggers for policy violations on changes in the SBOM between images with the same tag so that it can detect drift over time between builds of your images.

Gate: tag_drift

The triggers are:

  • packages_added
  • packages_removed
  • packages_modified

The “tag_drift” gate compares the SBOMs from the image being evaluated as input, and the SBOM of the image that precedes the input image with the requested tag provided for policy evaluation. The triggers in this gate evaluate the result to determine if packages were added, removed, or modified.

Trigger: packages_added

This trigger warns if a package was added to the SBOM.

Parameters

Optional parameter: “package_type”

Example

Raise a warning if packages were added.

  {
   "action": "WARN",
   "gate": "tag_drift",
   "trigger": "packages_added",
   "params": [],
   "id": "1ba3461f-b9db-4a6c-ac88-329d38e08df5"
  }

Trigger: packages_removed

This trigger warns if a package was deleted from the SBOM.

Parameters

Optional parameter: “package_type”

Example

Raise a warning if packages were deleted.

  {
   "action": "WARN",
   "gate": "tag_drift",
   "trigger": "packages_removed",
   "params": [],
   "id": "de05d77b-1f93-4df4-a65d-57d9042b1f3a"
  }

Trigger: packages_modified

This trigger warns if a package was changed in the SBOM.

Parameters

Optional parameter: “package_type”

Example

Raise a warning if packages were changed.

  {
   "action": "WARN",
   "gate": "tag_drift",
   "trigger": "packages_modified",
   "params": [],
   "id": "1168b0ac-df6c-4715-8077-2cb3e016cf63"
  }