Amazon Inspector SBOM Generator

A Software Bill of Materials (SBOM) is a formally structured list of components, libraries, and modules required to build a piece of software. The Amazon Inspector SBOM Generator (Sbomgen) is a tool that produces an SBOM for archives, container images, directories, local systems, and compiled Go and Rust binaries. Sbomgen scans for files that contain information about installed packages. When Sbomgen finds a relevant file, it extracts package names, versions, and other metadata. Sbomgen then transforms package metadata into a CycloneDX SBOM. You can use Sbomgen to generate the CycloneDX SBOM as a file or in STDOUT and send SBOMs to Amazon Inspector for vulnerability detection. You can also use Sbomgen as part of the CI/CD integration, which scans container images automatically as part of your deployment pipeline.

Supported packages types

Sbomgen collects inventory for the following package types:

Supported container image configuration checks

Sbomgen can scan standalone Dockerfiles and build history from exisiting images for security issues. For more information, see Amazon Inspector Dockerfile checks.

Installing Sbomgen

Sbomgen is only available for Linux operating systems.

You must have Docker installed if you want Sbomgen to analyze locally cached images. Docker isn't required to analyze images exported as .tar files or images hosted in remote container registries.

Amazon Inspector recommends that you run Sbomgen from a system with at least the following hardware specs:

Using Sbomgen

This section describes different ways you can use Sbomgen. You can learn more about how to use Sbomgen through built-in examples. To view these examples, run the list-examples command:

./inspector-sbomgen list-examples

Generate an SBOM for a container image and output the result

You can use Sbomgen to generate SBOMs for container images and output the result to a file. This capability can be enabled using the container subcommand.

Example command

In the following snippet, you can replace image:tag with the ID of your image and output_path.json with the path to the output you want to save.

# generate SBOM for container image
./inspector-sbomgen container --image image:tag -o output_path.json

When using Sbomgen with ScanSbom, the Amazon Inspector Scan API won't process SBOMs that contain more than 5,000 packages. In this scenario, the Amazon Inspector Scan API returns an HTTP 400 response.

If an image includes bulk media files or directories, consider excluding them from Sbomgen using the --skip-files argument.

Example: Common error cases

Container image scanning can fail due to the following errors:

Amazon Inspector does not support the application/vnd.docker.distribution.manifest.list.v2+json media type. However, Amazon Inspector does support manifest lists. When scanning images that use manifest lists, you can explicitly specify which platform to use with the --platform argument. If the --platform argument is not specified, the Amazon Inspector SBOM Generator automatically selects the manifest based on the platform where its running.

Generate an SBOM from directories and archives

You can use Sbomgen to generate SBOMs from directories and archives. This capability can be enabled using the directory or archive subcommands. Amazon Inspector recommends using this feature when you want to generate an SBOM from a project folder, such as a downloaded git repository.

Example command 1

The following snippet shows a subcommand that generates an SBOM from a directory file.

# generate SBOM from directory
./inspector-sbomgen directory --path /path/to/dir -o /tmp/sbom.json

Example command 2

The following snippet shows a subcommand that generates an SBOM from an archive file. The only supported archive formats are .zip, .tar, and .tar.gz.

# generate SBOM from archive file (tar, tar.gz, and zip formats only)
./inspector-sbomgen archive --path testData.zip -o /tmp/sbom.json

Generate an SBOM from Go or Rust compiled binaries

You can use Sbomgen to generate SBOMs from compiled Go and Rust binaries. You can enable this cabapility through the binary subcommand:

./inspector-sbomgen binary --path /path/to/your/binary

Generate an SBOM from mounted volumes

You can use Amazon Inspector SBOM Generator to generate SBOMs from mounted volumes. This capability can be enabled using the volume subcommand. We recommend using this feature when you want to analyze storage volumes, such as Amazon EBS volumes that have been mounted to your system. Unlike the directory subcommand, mounted volume scanning detects OS packages and OS information.

You can scan an Amazon EBS volume by attaching it to an Amazon EC2 instance where Amazon Inspector SBOM Generator is installed and mounting it on that instance. For Amazon EBS volumes that are currently in use by other Amazon EC2 instances, you can create an Amazon EBS snapshot of the volume and then create a new Amazon EBS volume from that snapshot for scanning purposes. For more information about Amazon EBS, see What is Amazon EBS? in the Amazon Elastic Block Store User Guide.

Example command

The following snippet shows a subcommand that generates an SBOM from a mounted volume. The --path argument should specify the root directory where the volume is mounted.

# generate SBOM from mounted volume
./inspector-sbomgen volume --path /mount/point/of/volume/root

Example command

The following snippet shows a subcommand that generates an SBOM from a mounted volume while excluding specific file paths with the --exclude-suffix argument. The --exclude-suffix argument is particularly useful when a volume contains bulk files (such as log files or media files). Files and directories whose paths end with the specified suffixes will be excluded from scanning, which can reduce scan time and memory usage.

# generate SBOM from mounted volume with exclusions
./inspector-sbomgen volume --path /mount/point/of/volume/root \
--exclude-suffix .log \
--exclude-suffix cache

All file paths in the target volume are normalized to their original paths. For example, when scanning a volume mounted at /mnt/volume that contains a file at /mnt/volume/var/lib/rpm/rpmdb.sqlite, the path will be normalized to /var/lib/rpm/rpmdb.sqlite in the generated SBOM.

Send an SBOM to Amazon Inspector for vulnerability identification

In addition to generating an SBOM, you can send an SBOM for scanning with a single command from the Amazon Inspector Scan API. Amazon Inspector evaluates the contents of the SBOM for vulnerabilites before returning findings to Sbomgen. Depending on your input, the findings can be displayed or written to a file.

To enable this capability, you pass the --scan-sbom argument to the Sbomgen CLI. You can also pass the --scan-sbom argument to any of the following Sbomgen subcommands: archive, binary, container, directory, localhost.

You can authenticate to Amazon Inspector through an AWS profile or an IAM role with the following AWS CLI arguments:

--aws-profile profile
--aws-region region
--aws-iam-role-arn role_arn 
            

You can also authenticate to Amazon Inspector by providing the following environment variables to Sbomgen.

AWS_ACCESS_KEY_ID=$access_key \
AWS_SECRET_ACCESS_KEY=$secret_key \
AWS_DEFAULT_REGION=$region \
./inspector-sbomgen arguments
            

To specify the response format, use the --scan-sbom-output-format cyclonedx argument or --scan-sbom-output-format inspector argument.

Example command 1

This command creates an SBOM for the latest Alpine Linux release, scans the SBOM, and writes the vulnerability results to a JSON file.

./inspector-sbomgen container --image alpine:latest \
                          --scan-sbom \
                          --aws-profile your_profile \
                          --aws-region your_region \
                          --scan-sbom-output-format cyclonedx \
                          --outfile /tmp/inspector_scan.json

Example command 2

This command authenticates to Amazon Inspector using AWS credentials as environment variables.

AWS_ACCESS_KEY_ID=$your_access_key \
AWS_SECRET_ACCESS_KEY=$your_secret_key \
AWS_DEFAULT_REGION=$your_region \
./inspector-sbomgen container --image alpine:latest \
                          -o /tmp/sbom.json \
                          --scan-sbom \
                          --scan-sbom-output-format inspector

Example command 3

This command authenticates to Amazon Inspector using the ARN for an IAM role.

./inspector-sbomgen container --image alpine:latest \
                          --scan-sbom \
                          --aws-profile your_profile \
                          --aws-region your_region \
                          --outfile /tmp/inspector_scan.json
                          --aws-iam-role-arn arn:aws:iam::123456789012:role/your_role

Use additional scanners to enhance detection capabilities

The Amazon Inspector SBOM Generator applies predefined scanners based on the command being used.

Default scanner groups

Each Amazon Inspector SBOM Generator subcommand applies the following default scanner groups automatically.

Special scanners

To include scanners beyond the default scanner groups, use the --additional-scanners option followed by the name of the scanner to be added. The following is an example command showing how to do this.

# Add WordPress installation scanner to directory scan
./inspector-sbomgen directory --path /path/to/directory/ --additional-scanners wordpress-installation -o output.json
            

The following is an example command showing how to add multiple scanners with a comma-separated list.

./inspector-sbomgen container --image image:tag --additional-scanners scanner1,scanner2 -o output.json
            

Optimize container scans by adjusting maximum file size to scan

When you analyze and process a container image, Sbomgen scans files that are 200 MB or less by default. Files larger than 200 MB rarely contain package metadata. You can encounter misses when you inventory a Go or Rust binary that exceeds 200MB. To adjust the size limit, use the --max-file-size argument. This allows you to increase the limit to include large files and decrease the limit to reduce resource usage by excluding large files.

Example

The following example shows how to use the --max-file-size argument to increase the file size.

# Increase the file size limit to scan files up to 300 MB
./inspector-sbomgen container --image alpine:latest \
--outfile /tmp/sbom.json \
--max-file-size 300000000
            

Adjusting this setting helps control disk usage, memory consumption, and overall scan duration.

Disable progress indicator

Sbomgen displays a spinning progress indicator that can result in excessive slash characters in CI/CD environments.

INFO[2024-02-01 14:58:46]coreV1.go:53: analyzing artifact
|
\
/
|
\
/
INFO[2024-02-01 14:58:46]coreV1.go:62: executing post-processors

You can disable the progress indicator using the --disable-progress-bar arguement:

./inspector-sbomgen container --image alpine:latest \
--outfile /tmp/sbom.json \
--disable-progress-bar

Authenticating to private registries with Sbomgen

By providing your private registry authentication credentials, you can generate SBOMs from containers that are hosted in private registries. You can provide these credentials through the following methods:

Authenticate using cached credentials (recommended)

For this method, you authenticate to your container registry. For example, if using Docker, you can authenticate to your container registry using the Docker loging command: docker login.

./inspector-sbomgen container --image image:tag

Authenticate using the interactive method

For this method, provide your username as a parameter, and Sbomgen will prompt you for secure password entry when needed.

To use the following example, replace image:tag with the name of the image that you want to scan and your_username with a username that has access to the image:

./inspector-sbomgen container --image image:tag --username your_username

Authenticate using the non-interactive method

For this method, store your password or registry token in a .txt file.

To use the following example, replace your_username with your username, password.txt with the .txt file that includes your password or token on a single line, and image:tag with the name of the image to scan:

INSPECTOR_SBOMGEN_USERNAME=your_username \
INSPECTOR_SBOMGEN_PASSWORD=`cat password.txt` \
./inspector-sbomgen container --image image:tag

Example outputs from Sbomgen

The following is an example of an SBOM for a container image inventoried using Sbomgen.

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.5",
  "serialNumber": "urn:uuid:828875ef-8c32-4777-b688-0af96f3cf619",
  "version": 1,
  "metadata": {
    "timestamp": "2023-11-17T21:36:38Z",
    "tools": [
      {
        "vendor": "Amazon Web Services, Inc. (AWS)",
        "name": "Amazon Inspector SBOM Generator",
        "version": "1.0.0",
        "hashes": [
          {
            "alg": "SHA-256",
            "content": "10ab669cfc99774786301a745165b5957c92ed9562d19972fbf344d4393b5eb1"
          }
        ]
      }
    ],
    "component": {
      "bom-ref": "comp-1",
      "type": "container",
      "name": "fedora:latest",
      "properties": [
        {
          "name": "amazon:inspector:sbom_generator:image_id",
          "value": "sha256:c81c8ae4dda7dedc0711daefe4076d33a88a69a28c398688090c1141eff17e50"
        },
        {
          "name": "amazon:inspector:sbom_generator:layer_diff_id",
          "value": "sha256:eddd0d48c295dc168d0710f70364581bd84b1dda6bb386c4a4de0b61de2f2119"
        }
      ]
    }
  },
  "components": [
    {
      "bom-ref": "comp-2",
      "type": "library",
      "name": "dnf",
      "version": "4.18.0",
      "purl": "pkg:pypi/dnf@4.18.0",
      "properties": [
        {
          "name": "amazon:inspector:sbom_generator:source_file_scanner",
          "value": "python-pkg"
        },
        {
          "name": "amazon:inspector:sbom_generator:source_package_collector",
          "value": "python-pkg"
        },
        {
          "name": "amazon:inspector:sbom_generator:source_path",
          "value": "/usr/lib/python3.12/site-packages/dnf-4.18.0.dist-info/METADATA"
        },
        {
          "name": "amazon:inspector:sbom_generator:is_duplicate_package",
          "value": "true"
        },
        {
          "name": "amazon:inspector:sbom_generator:duplicate_purl",
          "value": "pkg:rpm/fedora/python3-dnf@4.18.0-2.fc39?arch=noarch&distro=39&epoch=0"
        }
      ]
    },
    {
      "bom-ref": "comp-3",
      "type": "library",
      "name": "libcomps",
      "version": "0.1.20",
      "purl": "pkg:pypi/libcomps@0.1.20",
      "properties": [
        {
          "name": "amazon:inspector:sbom_generator:source_file_scanner",
          "value": "python-pkg"
        },
        {
          "name": "amazon:inspector:sbom_generator:source_package_collector",
          "value": "python-pkg"
        },
        {
          "name": "amazon:inspector:sbom_generator:source_path",
          "value": "/usr/lib64/python3.12/site-packages/libcomps-0.1.20-py3.12.egg-info/PKG-INFO"
        },
        {
          "name": "amazon:inspector:sbom_generator:is_duplicate_package",
          "value": "true"
        },
        {
          "name": "amazon:inspector:sbom_generator:duplicate_purl",
          "value": "pkg:rpm/fedora/python3-libcomps@0.1.20-1.fc39?arch=x86_64&distro=39&epoch=0"
        }
      ]
    }
  ]
}