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 2,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.

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

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

Customize scans to exclude specific files

When analyzing and processing a container image, Sbomgen scans the size of all files in that container image. You can customize scans to exclude specific files or target specific packages.

To reduce disk consumption, RAM consumption, elapsed runtime, and skip files that exceed the provided threshold, use the --max-file-size argument with the container subcommand:

./inspector-sbomgen container --image alpine:latest \
--outfile /tmp/sbom.json \
--max-file-size 300000000

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 ineractive 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"
        }
      ]
    }
  ]
}