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

Return to the regular view of this page.

User Guides

1 - SBOM Generation

SBOM Generation User Guide

An SBOM, or Software Bill of Materials, is a detailed list of all the components, libraries, and modules that make up a piece of software.

For a developer, having an SBOM is crucial for tracking dependencies, quickly identifying known vulnerabilities within those components, and ensuring license compliance.

For a consumer or organization using the software, an SBOM provides transparency into the software’s supply chain, allowing them to assess potential security risks and understand what’s “under the hood.”

Syft is an open-source command-line tool and Go library. Its primary function is to scan container images, file systems, and archives to automatically generate a Software Bill of Materials, making it easier to understand the composition of software.

Get Started - Install Syft, create an SBOM and examine the contents.
Supported Data Sources - The variety of sources supported by our tools.
File Selection - Specify which files will be cataloged.
Output Formats - The industry-standard supported SBOM formats.
Configuration - Configuring Syft for your environment and requirements.

1.1 - Getting Started

SBOM Generation Getting Started

Introduction

Syft is our CLI tool for generating a Software Bill of Materials (SBOM) from container images and filesystems.

Install the latest Syft release

Syft is provided as a single compiled executable. Issue the command for your platform to download the latest release of Syft. The full list of official and community maintained packages can be found on the installation page.

curl -sSfL <a href="https://get.anchore.io/syft">https://get.anchore.io/syft</a> | sudo sh -s &ndash; -b /usr/local/bin

brew install syft

nuget install Anchore.Syft

Once installed, ensure the syft binary is in the PATH for your system.

Create an SBOM with Syft

Generate an SBOM for a container image:

syft <image>

Display the contents of a public container image

Run syft with default options against a small container, which will be pulled from DockerHub. The output will be a simple human-readable table.

Learn more

Syft supports more than just containers, find out more about Supported Sources

syft alpine:latest

The output will look similar to the following table.

 ✔ Pulled image
 ✔ Loaded image alpine:latest
 ✔ Parsed image sha256:8d591b0b7dea080ea3be9e12ae563eebf9…
 ✔ Cataloged contents 058c92d86112aa6f641b01ed238a07a3885…
   ├── ✔ Packages                        [15 packages]
   ├── ✔ File metadata                   [82 locations]
   ├── ✔ File digests                    [82 files]
   └── ✔ Executables                     [17 executables]
NAME                    VERSION      TYPE
alpine-baselayout       3.6.8-r1     apk
alpine-baselayout-data  3.6.8-r1     apk
alpine-keys             2.5-r0       apk
alpine-release          3.21.3-r0    apk
apk-tools               2.14.6-r3    apk
busybox                 1.37.0-r12   apk
busybox-binsh           1.37.0-r12   apk
ca-certificates-bundle  20241121-r1  apk
libcrypto3              3.3.3-r0     apk
libssl3                 3.3.3-r0     apk
musl                    1.2.5-r9     apk
musl-utils              1.2.5-r9     apk
scanelf                 1.3.8-r1     apk
ssl_client              1.37.0-r12   apk
zlib                    1.3.1-r2     apk

Create an SPDX formatted SBOM

The next command will display the human-readable table, and write an SBOM in an industry-standard format, SPDX.

syft alpine:latest -o table -o spdx-json=alpine_latest-spdx.json

The same table will be displayed, but there will also be an SBOM in the current directory.

Learn more

Syft supports multiple SBOM output formats, find out more about Output Formats.

Examine the SPDX file contents

The JSON output by Syft is long, but compressed down to one line. We can use jq to prettify it, and extract some package data.

Note

jq is an third-party command-line utility for manipulating JSON documents, find out more about jq on the jqlang website.

jq '.packages[].name' < alpine_latest-spdx.json

The output will show a list of packages that Syft found in the container.

"alpine-baselayout"
"alpine-baselayout-data"
"alpine-keys"
"alpine-release"
"apk-tools"
"busybox"
"busybox-binsh"
"ca-certificates-bundle"
"libcrypto3"
"libssl3"
"musl"
"musl-utils"
"scanelf"
"ssl_client"
"zlib"
"alpine"

The above output includes only software that is visible in the container (i.e., the squashed representation of the image). To include software from all image layers in the SBOM, regardless of its presence in the final image, provide --scope all-layers:

syft <image> --scope all-layers

Next steps

Try running Syft against other containers, or an application directory on your workstation.
Find out more about Supported Sources and Output Formats.
Learn about Vulnerability Scanning and License Scanning your SBOMs.

1.2 - Supported Sources

SBOM Generation Supported Sources

Supported sources

Syft can generate an SBOM from a variety of sources including images, files, directories, and archives. Syft will attempt to determine the type of source based on provided input, for example:

# catalog a container image archive (from the result of `docker image save ...`, `podman save ...`, or `skopeo copy` commands)
syft path/to/image.tar

# catalog a Singularity Image Format (SIF) container
syft path/to/image.sif

# catalog a directory
syft path/to/dir

To explicitly specify the source behavior, use the --from flag. Allowable options are:

docker             use images from the Docker daemon
podman             use images from the Podman daemon
containerd         use images from the Containerd daemon
docker-archive     use a tarball from disk for archives created from "docker save"
oci-archive        use a tarball from disk for OCI archives (from Skopeo or otherwise)
oci-dir            read directly from a path on disk for OCI layout directories (from Skopeo or otherwise)
singularity        read directly from a Singularity Image Format (SIF) container on disk
dir                read directly from a path on disk (any directory)
file               read directly from a path on disk (any single file)
registry           pull image directly from a registry (no container runtime required)

If a source is not provided and Syft identifies the input as a potential image reference, Syft will attempt to resolve it using: the Docker, Podman, and Containerd daemons followed by direct registry access, in that order.

This default behavior can be overridden with the default-image-pull-source configuration option (See Configuration for more details).

1.3 - File Selection

SBOM Generation File Selection

File selection

By default, Syft will catalog file details and digests for files that are owned by discovered packages. You can change this behavior by using the SYFT_FILE_METADATA_SELECTION environment variable or the file.metadata.selection configuration option. The options are:

all: capture all files from the search space
owned-by-package: capture only files owned by packages (default)
none: disable capturing any file information

Excluding file paths

Syft can exclude files and paths from being scanned within a source by using glob expressions with one or more --exclude parameters:

syft <source> --exclude './out/**/*.json' --exclude /etc

Note: in the case of image scanning, since the entire filesystem is scanned it is possible to use absolute paths like /etc or /usr/**/*.txt whereas directory scans exclude files relative to the specified directory. For example: scanning /usr/foo with --exclude ./package.json would exclude /usr/foo/package.json and --exclude '**/package.json' would exclude all package.json files under /usr/foo. For directory scans, it is required to begin path expressions with ./, */, or **/, all of which will be resolved relative to the specified scan directory. Keep in mind, your shell may attempt to expand wildcards, so put those parameters in single quotes, like: '**/*.json'.

1.4 - Output Formats

SBOM Generation Output Formats

Output formats

The output format for Syft is configurable as well using the -o (or --output) option:

syft <image> -o <format>

Where the formats available are:

syft-json: Use this to get as much information out of Syft as possible!
syft-text: A row-oriented, human-and-machine-friendly output.
cyclonedx-xml: A XML report conforming to the CycloneDX 1.6 specification.
cyclonedx-json: A JSON report conforming to the CycloneDX 1.6 specification.
spdx-tag-value: A tag-value formatted report conforming to the SPDX 2.3 specification.
spdx-tag-value@2.2: A tag-value formatted report conforming to the SPDX 2.2 specification.
spdx-json: A JSON report conforming to the SPDX 2.3 JSON Schema.
spdx-json@2.2: A JSON report conforming to the SPDX 2.2 JSON Schema.
github-json: A JSON report conforming to GitHub’s dependency snapshot format.
syft-table: A columnar summary (default).

template: Lets the user specify the output format.

Multiple Outputs

Syft can also output multiple files in differing formats by appending =<file> to the option, for example to output Syft JSON and SPDX JSON:

syft <image> -o syft-json=sbom.syft.json -o spdx-json=sbom.spdx.json

1.5 - Package Catalogers

SBOM Generation Package Catalogers

Package cataloger selection

Concepts

Note

Syft uses a different set of catalogers by default when scanning files directly than it does when scanning images.

The catalogers for an image scan assumes that package installation steps have already been completed. For example, Syft will identify Python packages that have egg or wheel metadata files under a site-packages directory, since this is how the canonical tooling pip installs python packages.

The catalogers for a directory scan will look for installed software as well as declared dependencies that are not necessarily installed. For example, dependencies listed in a Python requirements.txt.

This default set of catalogers being dynamic is critical as this allows Syft to be used in a variety of contexts while still generating accurate SBOMs. Overriding the set of default catalogers is not recommended for most purposes, however, is possible if needed.

Catalogers can be referenced in two different ways:

by name: the exact cataloger name (e.g. java-pom-cataloger or java-archive-cataloger)
by tag: a tag that is associated with a cataloger (e.g. java)

Syft can take lists of references on the CLI or in the application configuration to define which catalogers to use.

You can set the list of catalogers explicitly to use with the --override-default-catalogers CLI flag, accepting a comma-separated list of cataloger names or tags.

You can also add to, remove from, or sub-select catalogers to use within the default set of catalogers by using the --select-catalogers CLI flag.

To sub-select catalogers simply provide a tag (e.g. --select-catalogers TAG). Catalogers will always be selected from the default set of catalogers (e.g. --select-catalogers java,go will select all the java catalogers in the default set and all the go catalogers in the default set).
To add a cataloger prefix the cataloger name with + (e.g. --select-catalogers +NAME). Added catalogers will always be added regardless of removals, filtering, or other defaults.
To remove a cataloger prefix the cataloger name or tag with - (e.g. --select-catalogers -NAME_OR_TAG). Catalogers are removed from the set of default catalogers after processing any sub-selections.

These rules and the dynamic default cataloger sets approximates to the following logic:

image_catalogers = all_catalogers AND catalogers_tagged("image")

directory_catalogers = all_catalogers AND catalogers_tagged("directory")

default_catalogers = image_catalogers OR directory_catalogers

sub_selected_catalogers = default_catalogers INTERSECT catalogers_tagged(TAG) [ UNION sub_selected_catalogers ... ]

base_catalogers = default_catalogers OR sub_selected_catalogers

final_set = (base_catalogers SUBTRACT removed_catalogers) UNION added_catalogers

Examples

Only scan for python related packages with catalogers appropriate for the source type (image or directory):

syft <some container image> --select-catalogers "python"
# results in the following catalogers being used:
# - python-installed-package-cataloger

Same command, but the set of catalogers changes based on what is being analyzed (in this case a directory):

syft <a directory> --select-catalogers "python"
# results in the following catalogers being used:
# - python-installed-package-cataloger
# - python-package-cataloger

Use the default set of catalogers and add a cataloger to the set:

syft ... --select-catalogers "+sbom-cataloger"

Use the default set of catalogers but remove any catalogers that deal with RPMs:

syft ... --select-catalogers "-rpm"

Only scan with catalogers that:

are tagged with “go”
always use the sbom-cataloger
are appropriate for the source type (image or directory)

syft <some container image> --select-catalogers "go,+sbom-cataloger"
# results in the following catalogers being used:
# - go-module-binary-cataloger
# - sbom-cataloger

Scan with all catalogers that deal with binary analysis, regardless of the source type:

syft ... --override-default-catalogers "binary"
# results in the following catalogers being used:
# - binary-cataloger
# - cargo-auditable-binary-cataloger
# - dotnet-portable-executable-cataloger
# - go-module-binary-cataloger

Only scan with the specific go-module-binary-cataloger and go-module-file-cataloger catalogers:

syft ... --override-default-catalogers "go-module-binary-cataloger,go-module-file-cataloger"

1.6 - Using Templates

SBOM Generation Using Templates

Using templates

Syft lets you define custom output formats, using Go templates relative to the Syft JSON output. Here’s how it works:

Define your format as a Go template, and save this template as a file.
Set the output format to “template” (-o template).
Specify the path to the template file (-t ./path/to/custom.template).
Syft’s template processing uses the same data models as the syft-json output format — so if you’re wondering what data is available as you author a template, you can use the output from syft <image> -o syft-json as a reference.

Example: You could make Syft output data in CSV format by writing a Go template that renders CSV data and then running syft <image> -o template -t ~/path/to/csv.tmpl.

Here’s what the csv.tmpl file might look like:

"Package","Version Installed", "Found by"
{{- range .artifacts}}
"{{.name}}","{{.version}}","{{.foundBy}}"
{{- end}}

Which would produce output like:

"Package","Version Installed","Found by"
"alpine-baselayout","3.2.0-r20","apkdb-cataloger"
"alpine-baselayout-data","3.2.0-r20","apkdb-cataloger"
"alpine-keys","2.4-r1","apkdb-cataloger"
...

Syft also includes a vast array of utility templating functions from sprig apart from the default Golang text/template to allow users to customize the output format.

Lastly, Syft has custom templating functions defined in ./syft/format/template/encoder.go to help parse the passed-in JSON structs.

Note

If you have templates being used before Syft v0.102.0 that are no longer working. This is because templating keys were relative to the internal go structs before this version whereas now the keys are relative to the Syft JSON output. To get the legacy behavior back you can set the format.template.legacy option to true in your configuration.

1.7 - Format Conversion (experimental)

SBOM Generation Format Conversion (experimental)

Format Conversion (experimental)

The ability to convert existing SBOMs means you can create SBOMs in different formats quickly, without the need to regenerate the SBOM from scratch, which may take significantly more time.

syft convert <ORIGINAL-SBOM-FILE> -o <NEW-SBOM-FORMAT>[=<NEW-SBOM-FILE>]

This feature is experimental and data might be lost when converting formats. Packages are the main SBOM component easily transferable across formats, whereas files and relationships, as well as other information Syft doesn’t support, are more likely to be lost.

We support formats with wide community usage AND good encode/decode support by Syft. The supported formats are:

Syft JSON (-o syft-json)
SPDX 2.2 JSON (-o spdx-json)
SPDX 2.2 tag-value (-o spdx-tag-value)
CycloneDX 1.4 JSON (-o cyclonedx-json)
CycloneDX 1.4 XML (-o cyclonedx-xml)

Conversion example:

syft alpine:latest -o syft-json=sbom.syft.json # generate a syft SBOM
syft convert sbom.syft.json -o cyclonedx-json=sbom.cdx.json  # convert it to CycloneDX

1.8 - Private Registry Authentication

SBOM Generation Private Registry Authentication

Private Registry Authentication

Local Docker Credentials

When a container runtime is not present, Syft can still utilize credentials configured in common credential sources (such as ~/.docker/config.json). It will pull images from private registries using these credentials. The config file is where your credentials are stored when authenticating with private registries via some command like docker login. For more information see the go-containerregistry documentation.

An example config.json looks something like this:

{
  "auths": {
    "registry.example.com": {
      "username": "AzureDiamond",
      "password": "hunter2"
    }
  }
}

You can run the following command as an example. It details the mount/environment configuration a container needs to access a private registry:

docker run -v ./config.json:/config/config.json -e "DOCKER_CONFIG=/config" anchore/syft:latest  <private_image>

Docker Credentials in Kubernetes

Here’s a simple workflow to mount this config file as a secret into a container on Kubernetes.

Create a secret. The value of config.json is important. It refers to the specification detailed here. Below this section is the secret.yaml file that the pod configuration will consume as a volume. The key config.json is important. It will end up being the name of the file when mounted into the pod.
```
# secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: registry-config
  namespace: syft
data:
  config.json: <base64 encoded config.json>
```
kubectl apply -f secret.yaml

Create your pod running syft. The env DOCKER_CONFIG is important because it advertises where to look for the credential file. In the below example, setting DOCKER_CONFIG=/config informs syft that credentials can be found at /config/config.json. This is why we used config.json as the key for our secret. When mounted into containers the secrets’ key is used as the filename. The volumeMounts section mounts our secret to /config. The volumes section names our volume and leverages the secret we created in step one.

# pod.yaml

apiVersion: v1
kind: Pod
metadata:
  name: syft-k8s-usage
spec:
  containers:
    - image: anchore/syft:latest
      name: syft-private-registry-demo
      env:
        - name: DOCKER_CONFIG
          value: /config
      volumeMounts:
        - mountPath: /config
          name: registry-config
          readOnly: true
      args:
        - <private_image>
  volumes:
    - name: registry-config
      secret:
        secretName: registry-config

kubectl apply -f pod.yaml

The user can now run kubectl logs syft-private-registry-demo. The logs should show the Syft analysis for the <private_image> provided in the pod configuration.

Using the above information, users should be able to configure private registry access without having to do so in the grype or syft configuration files. They will also not be dependent on a Docker daemon, (or some other runtime software) for registry configuration and access.

1.9 - Attestation (experimental)

SBOM Generation Attestation (experimental)

Attestation (experimental)

Keyless support

Syft supports generating attestations using cosign’s keyless signatures.

Note: users need to have >= v1.12.0 of cosign installed for this command to function

To use this feature with a format like CycloneDX json simply run:

syft attest --output cyclonedx-json <IMAGE WITH OCI WRITE ACCESS>

This command will open a web browser and allow the user to authenticate their OIDC identity as the root of trust for the attestation (Github, Google, Microsoft).

After authenticating, Syft will upload the attestation to the OCI registry specified by the image that the user has write access to.

You will need to make sure your credentials are configured for the OCI registry you are uploading to so that the attestation can write successfully.

Users can then verify the attestation(or any image with attestations) by running:

COSIGN_EXPERIMENTAL=1 cosign verify-attestation <IMAGE_WITH_ATTESTATIONS>

Users should see that the uploaded attestation claims are validated, the claims exist within the transparency log, and certificates on the attestations were verified against fulcio. There will also be a printout of the certificates subject <user identity> and the certificate issuer URL: <provider of user identity (Github, Google, Microsoft)>:

Certificate subject:  test.email@testdomain.com
Certificate issuer URL:  https://accounts.google.com

Local private key support

To generate an SBOM attestation for a container image using a local private key:

syft attest --output [FORMAT] --key [KEY] [SOURCE] [flags]

The above output is in the form of the DSSE envelope. The payload is a base64 encoded in-toto statement with the generated SBOM as the predicate. For details on workflows using this command see here.

Adding an SBOM to an image as an attestation using Syft

syft attest --output [FORMAT] --key [KEY] [SOURCE] [flags]

SBOMs themselves can serve as input to different analysis tools. Grype, a vulnerability scanner CLI tool from Anchore, is one such tool. Publishers of container images can use attestations to enable their consumers to trust Syft-generated SBOM descriptions of those container images. To create and provide these attestations, image publishers can run syft attest in conjunction with the cosign tool to attach SBOM attestations to their images.

Example attestation

Note for the following example replace docker.io/image:latest with an image you own. You should also have push access to its remote reference. Replace $MY_PRIVATE_KEY with a private key you own or have generated with cosign.

syft attest --key $MY_PRIVATE_KEY -o spdx-json docker.io/image:latest > image_latest_sbom_attestation.json
cosign attach attestation --attestation image_latest_sbom_attestation.json docker.io/image:latest

Verify the new attestation exists on your image.

cosign verify-attestation --key $MY_PUBLIC_KEY --type spdxjson docker.io/image:latest | jq '.payload | @base64d | .payload | fromjson | .predicate'

You should see this output along with the attached SBOM:

Verification for docker.io/image:latest --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key
  - Any certificates were verified against the Fulcio roots.

Consumers of your image can now trust that the SBOM associated with your image is correct and from a trusted source.

The SBOM can be piped to Grype:

cosign verify-attestation --key $MY_PUBLIC_KEY --type spdxjson docker.io/image:latest | jq '.payload | @base64d | .payload | fromjson | .predicate' | grype

1.10 - Configuration

SBOM Generation Configuration

Configuration

Ways to specify values

For each configurable value, Syft checks the following places in order, taking the first value that is found:

Arguments passed on the command line
Environment variables
The configuration file (see below for which file is chosen)
The default value

In other words, if SYFT_LOG_LEVEL is set in the environment, and log.level is set in the config file, and -vvv is passed, the log level will be trace because -vvv took precedence over the environment variable and the config file value.

If Syft is invoked with log level at debug or trace (-vv or -vvv or SYFT_LOG_LEVEL=debug), Syft prints its entire configuration at the beginning of its run.

Use syft --help for a list of command line arguments. Use syft config to print a sample config file to stdout. Use syft config --load to print the current config to stdout.

Environment variables

The environment variable checked is determined by the nesting path in the configuration file. For example, Syft lets you specify whether JSON output should be pretty (include indents and line breaks) via the following config file snippet:

format:
  json:
    pretty: true

The path from the document root to the value is format->json->pretty, so the environment variable that sets this value SYFT_FORMAT_JSON_PRETTY. See below a complete sample config file with environment variables noted.

Config File

The following paths are searched, in order, for a syft config file. The first file that exists is used entirely; no merging of config files is done at this time:

.syft.yaml
.syft/config.yaml
~/.syft.yaml
<XDG_CONFIG_HOME>/syft/config.yaml

List of configurable values

You can print a sample config file by running syft config. You can print the current config by running syft config --load.

Configuration options (example values are the default):

# the output format(s) of the SBOM report (options: syft-table, syft-text, syft-json, spdx-json, ...)
# to specify multiple output files in differing formats, use a list:
# output:
#   - "syft-json=<syft-json-output-file>"
#   - "spdx-json=<spdx-json-output-file>"
# SYFT_OUTPUT env var / -o, --output flags
output:
  - "syft-table"

# suppress all output (except for the SBOM report)
# SYFT_QUIET env var / -q flag
quiet: false

# enable/disable checking for application updates on startup
# SYFT_CHECK_FOR_APP_UPDATE env var
check-for-app-update: true

# maximum number of workers used to process the list of package catalogers in parallel
parallelism: 1

# a list of globs to exclude from scanning, for example:
# exclude:
#   - "/etc/**"
#   - "./out/**/*.json"
# SYFT_EXCLUDE env var / --exclude flag
exclude: []

# os and/or architecture to use when referencing container images (e.g. "windows/armv6" or "arm64")
# SYFT_PLATFORM env var / --platform flag
platform: ""

# the search space to look for file and package data (options: all-layers, squashed)
# SYFT_SCOPE env var
scope: "squashed"

# set the list of package catalogers to use when generating the SBOM
# default = empty (cataloger set determined automatically by the source type [image or file/directory])
# Use `syft cataloger list` for a list of catalogers you can specify
# DEPRECATED: please use default-catalogers and select-catalogers configuration options instead
# SYFT_CATALOGERS env var / --catalogers flag
catalogers:

# set the base set of catalogers to use (defaults to 'image' or 'directory' depending on the scan source)
# SYFT_DEFAULT_CATALOGERS env var / --override-default-catalogers flag
default-catalogers: []

# add, remove, and filter the catalogers to be used
# SYFT_SELECT_CATALOGERS env var / --select-catalogers flag;
select-catalogers: []

# all format configuration
format:
  # default value for all formats that support the "pretty" option (default is unset)
  # SYFT_FORMAT_PRETTY env var
  pretty:

  # all syft-json format options
  json:
    # include space indention and newlines (inherits default value from 'format.pretty' or 'false' if parent is unset)
    # note: inherits default value from 'format.pretty' or 'false' if parent is unset
    # SYFT_FORMAT_JSON_PRETTY env var
    pretty: false

    # transform any syft-json output to conform to an approximation of the v11.0.1 schema. This includes:
    # - using the package metadata type names from before v12 of the JSON schema (changed in https://github.com/anchore/syft/pull/1983)
    #
    # Note: this will still include package types and fields that were added at or after json schema v12. This means
    # that output might not strictly be json schema v11 compliant, however, for consumers that require time to port
    # over to the final syft 1.0 json output this option can be used to ease the transition.
    #
    # Note: long term support for this option is not guaranteed (it may change or break at any time).
    # SYFT_FORMAT_JSON_LEGACY env var
    legacy: false

  # all template format options
  template:
    # path to the template file to use when rendering the output with the `template` output format.
    # Note that all template paths are based on the current syft-json schema.
    # SYFT_FORMAT_TEMPLATE_PATH env var / -t flag
    path: ""

    # if true, uses the go structs for the syft-json format for templating.
    # if false, uses the syft-json output for templating (which follows the syft JSON schema exactly).
    #
    # Note: long term support for this option is not guaranteed (it may change or break at any time).
    # SYFT_FORMAT_TEMPLATE_LEGACY env var
    legacy: false

  # all spdx-json format options
  spdx-json:
    # include space indention and newlines
    # note: inherits default value from 'format.pretty' or 'false' if parent is unset
    # SYFT_FORMAT_SPDX_JSON_PRETTY env var
    pretty: false

  # all cyclonedx-json format options
  cyclonedx-json:
    # include space indention and newlines
    # note: inherits default value from 'format.pretty' or 'false' if parent is unset
    # SYFT_FORMAT_CYCLONEDX_JSON_PRETTY env var
    pretty: false

  # all cyclonedx-xml format options
  cyclonedx-xml:
    # include space indention
    # note: inherits default value from 'format.pretty' or 'false' if parent is unset
    # SYFT_FORMAT_CYCLONEDX_XML_PRETTY env var
    pretty: false

file:
  metadata:
    # select which files should be captured by the file-metadata cataloger and included in the SBOM.
    # Options include:
    #  - "all": capture all files from the search space
    #  - "owned-by-package": capture only files owned by packages
    #  - "none", "": do not capture any files
    # SYFT_FILE_METADATA_SELECTION env var
    selection: "owned-by-package"

    # the file digest algorithms to use when cataloging files (options: "md5", "sha1", "sha224", "sha256", "sha384", "sha512")
    # SYFT_FILE_METADATA_DIGESTS env var
    digests:
      - "sha256"
      - "sha1"

  # capture the contents of select files in the SBOM
  content:
    # skip searching a file entirely if it is above the given size (default = 1MB; unit = bytes)
    # SYFT_FILE_CONTENT_SKIP_FILES_ABOVE_SIZE env var
    skip-files-above-size: 1048576

    # file globs for the cataloger to match on
    # SYFT_FILE_CONTENT_GLOBS env var
    globs: []

# cataloging packages is exposed through the packages and power-user subcommands
package:
  # search within archives that do contain a file index to search against (zip)
  # note: for now this only applies to the java package cataloger
  # SYFT_PACKAGE_SEARCH_INDEXED_ARCHIVES env var
  search-indexed-archives: true

  # search within archives that do not contain a file index to search against (tar, tar.gz, tar.bz2, etc)
  # note: enabling this may result in a performance impact since all discovered compressed tars will be decompressed
  # note: for now this only applies to the java package cataloger
  # SYFT_PACKAGE_SEARCH_UNINDEXED_ARCHIVES env var
  search-unindexed-archives: false

  # allows users to exclude synthetic binary packages from the sbom
  # these packages are removed if an overlap with a non-synthetic package is found
  # SYFT_PACKAGE_EXCLUDE_BINARY_OVERLAP_BY_OWNERSHIP env var
  exclude-binary-overlap-by-ownership: true

golang:
  # search for go package licences in the GOPATH of the system running Syft, note that this is outside the
  # container filesystem and potentially outside the root of a local directory scan
  # SYFT_GOLANG_SEARCH_LOCAL_MOD_CACHE_LICENSES env var
  search-local-mod-cache-licenses: false

  # specify an explicit go mod cache directory, if unset this defaults to $GOPATH/pkg/mod or $HOME/go/pkg/mod
  # SYFT_GOLANG_LOCAL_MOD_CACHE_DIR env var
  local-mod-cache-dir: ""

  # search for go package licences by retrieving the package from a network proxy
  # SYFT_GOLANG_SEARCH_REMOTE_LICENSES env var
  search-remote-licenses: false

  # remote proxy to use when retrieving go packages from the network,
  # if unset this defaults to $GOPROXY followed by https://proxy.golang.org
  # SYFT_GOLANG_PROXY env var
  proxy: ""

  # specifies packages which should not be fetched by proxy
  # if unset this defaults to $GONOPROXY
  # SYFT_GOLANG_NOPROXY env var
  no-proxy: ""

  # the go main module version discovered from binaries built with the go compiler will
  # always show (devel) as the version. Use these options to control heuristics to guess
  # a more accurate version from the binary.
  main-module-version:
    # look for LD flags that appear to be setting a version (e.g. -X main.version=1.0.0)
    # SYFT_GOLANG_MAIN_MODULE_VERSION_FROM_LD_FLAGS env var
    from-ld-flags: true

    # use the build settings (e.g. vcs.version & vcs.time) to craft a v0 pseudo version
    # (e.g. v0.0.0-20220308212642-53e6d0aaf6fb) when a more accurate version cannot be found otherwise.
    # SYFT_GOLANG_MAIN_MODULE_VERSION_FROM_BUILD_SETTINGS env var
    from-build-settings: true

    # search for semver-like strings in the binary contents.
    # SYFT_GOLANG_MAIN_MODULE_VERSION_FROM_CONTENTS env var
    from-contents: true

java:
  maven-url: "https://repo1.maven.org/maven2"
  max-parent-recursive-depth: 5
  # enables Syft to use the network to fill in more detailed information about artifacts
  # currently this enables searching maven-url for license data
  # when running across pom.xml files that could have more information, syft will
  # explicitly search maven for license information by querying the online pom when this is true
  # this option is helpful for when the parent pom has more data,
  # that is not accessible from within the final built artifact
  use-network: false

linux-kernel:
  # whether to catalog linux kernel modules found within lib/modules/** directories
  # SYFT_LINUX_KERNEL_CATALOG_MODULES env var
  catalog-modules: true

python:
  # when running across entries in requirements.txt that do not specify a specific version
  # (e.g. "sqlalchemy >= 1.0.0, <= 2.0.0, != 3.0.0, <= 3.0.0"), attempt to guess what the version could
  # be based on the version requirements specified (e.g. "1.0.0"). When enabled the lowest expressible version
  # when given an arbitrary constraint will be used (even if that version may not be available/published).
  guess-unpinned-requirements: false

javascript:
  search-remote-licenses: false
  npm-base-url: "https://registry.npmjs.org"

# configuration for the source that the SBOM is generated from (e.g. a file, directory, or container image)
source:
  # alias name for the source
  # SYFT_SOURCE_NAME env var / --source-name flag
  name: ""

  # alias version for the source
  # SYFT_SOURCE_VERSION env var / --source-version flag
  version: ""

  # base directory for scanning, no links will be followed above this directory, and all paths will be
  # reported relative to this directory
  # SYFT_SOURCE_BASE_PATH env var
  base-path:
    ""

    # options affecting the file source type
  file:
    # the file digest algorithms to use on the scanned file (options: "md5", "sha1", "sha224", "sha256", "sha384", "sha512")
    digests:
      - "sha256"

  image:
    # allows users to specify which image source should be used to generate the sbom
    # valid values are: registry, docker, podman
    # SYFT_SOURCE_IMAGE_DEFAULT_PULL_SOURCE env var
    default-pull-source: ""

# options when pulling directly from a registry via the "registry:" or "containerd:" scheme
registry:
  # skip TLS verification when communicating with the registry
  # SYFT_REGISTRY_INSECURE_SKIP_TLS_VERIFY env var
  insecure-skip-tls-verify: false

  # use http instead of https when connecting to the registry
  # SYFT_REGISTRY_INSECURE_USE_HTTP env var
  insecure-use-http: false

  # filepath to a CA certificate (or directory containing *.crt, *.cert, *.pem) used to generate the client certificate
  # SYFT_REGISTRY_CA_CERT env var
  ca-cert: ""

  # credentials for specific registries
  auth:
    # the URL to the registry (e.g. "docker.io", "localhost:5000", etc.)
    # SYFT_REGISTRY_AUTH_AUTHORITY env var
    - authority: ""

      # SYFT_REGISTRY_AUTH_USERNAME env var
      username: ""

      # SYFT_REGISTRY_AUTH_PASSWORD env var
      password: ""

      # note: token and username/password are mutually exclusive
      # SYFT_REGISTRY_AUTH_TOKEN env var
      token: ""

      # filepath to the client certificate used for TLS authentication to the registry
      # SYFT_REGISTRY_AUTH_TLS_CERT env var
      tls-cert: ""

      # filepath to the client key used for TLS authentication to the registry
      # SYFT_REGISTRY_AUTH_TLS_KEY env var
      tls-key: ""

    # - ... # note, more credentials can be provided via config file only (not env vars)

# generate an attested SBOM
attest:
  # path to the private key file to use for attestation
  # SYFT_ATTEST_KEY env var
  key: "cosign.key"

  # password to decrypt to given private key
  # SYFT_ATTEST_PASSWORD env var, additionally responds to COSIGN_PASSWORD
  password: ""

log:
  # use structured logging
  # SYFT_LOG_STRUCTURED env var
  structured: false

  # the log level; note: detailed logging suppress the ETUI
  # SYFT_LOG_LEVEL env var
  level: "error"

  # location to write the log file (default is not to have a log file)
  # SYFT_LOG_FILE env var
  file: ""

2 - Vulnerability Scanning

Vulnerability Scanning User Guide

Vulnerability scanning is the automated process of proactively identifying security weaknesses and known exploits within software and systems. This is crucial because it helps developers and organizations find and fix potential security holes before malicious actors can discover and exploit them, thus protecting data and maintaining system integrity.

Grype is an open-source vulnerability scanner specifically designed to analyze container images and filesystems. It works by comparing the software components it finds against a database of known vulnerabilities, providing a report of potential risks so they can be addressed.

Get Started - Install Grype, scan an SBOM and container for vulnerabilities.
Vulnerability Database - Learn how to manage the vulnerability database used by Grype.

2.1 - Data Sources

Vulnerability Data Sources

2.2 - Getting Started

Vulnerability Scanning Getting Started

Introduction

Grype is an easy-to-integrate open source vulnerability scanning tool for container images and filesystems.

Install the latest Grype release

Grype is provided as a single compiled executable. Issue the command for your platform to download the latest release of Grype. The full list of official and community maintained packages can be found on the installation page.

curl -sSfL <a href="https://get.anchore.io/grype">https://get.anchore.io/grype</a> | sudo sh -s &ndash; -b /usr/local/bin

brew install grype

nuget install Anchore.Grype

Once installed, ensure the grype binary is in the PATH for your system.

Scan a container for vulnerabilities

grype <image>

Scan a public container image for vulnerabilities

Run grype with default options against a small container, which will be pulled from DockerHub. Grype will also download the latest vulnerability database. The output will be a simple human-readable table.

grype alpine:latest

 ✔ Loaded image alpine:latest
 ✔ Parsed image sha256:8d591b0b7dea080ea3be9e12ae563eebf9…
 ✔ Cataloged contents 058c92d86112aa6f641b01ed238a07a3885…
   ├── ✔ Packages                        [15 packages]
   ├── ✔ File metadata                   [82 locations]
   ├── ✔ File digests                    [82 files]
   └── ✔ Executables                     [17 executables]
 ✔ Scanned for vulnerabilities     [6 vulnerability matches]
   ├── by severity: 0 critical, 0 high, 0 medium, 6 low, 0 negligible
   └── by status:   0 fixed, 6 not-fixed, 0 ignored
NAME           INSTALLED   FIXED-IN  TYPE  VULNERABILITY   SEVERITY
busybox        1.37.0-r12            apk   CVE-2024-58251  Low
busybox        1.37.0-r12            apk   CVE-2025-46394  Low
busybox-binsh  1.37.0-r12            apk   CVE-2024-58251  Low
busybox-binsh  1.37.0-r12            apk   CVE-2025-46394  Low
ssl_client     1.37.0-r12            apk   CVE-2024-58251  Low
ssl_client     1.37.0-r12            apk   CVE-2025-46394  Low

Scan an existing SBOM for vulnerabilities

Grype can scan containers directly, but it can also scan an existing SBOM document.

Note

This presumes you already created alpine_latest-spdx.json using Syft, or some other tool. If not, go to SBOM Generation Getting Started and create it now.

grype alpine_latest-spdx.json

Grype should give similar output to the previous table.

Create a vulnerability report in JSON format

The JSON-formatted output from Grype may be processed or visualized by other tools.

Create the vulnerability report using the --output, and via jq to make it prettier.

grype alpine:latest --output json | jq . > vuln_report.json

Example:

 ✔ Pulled image
 ✔ Loaded image alpine:latest
 ✔ Parsed image sha256:8d591b0b7dea080ea3be9e12ae563eebf9869168ffced1cb25b2470a3d9fe15e
 ✔ Cataloged contents 058c92d86112aa6f641b01ed238a07a3885b8c0815de3e423e5c5f789c398b45
   ├── ✔ Packages                        [15 packages]
   ├── ✔ File digests                    [82 files]
   ├── ✔ Executables                     [17 executables]
   └── ✔ File metadata                   [82 locations]
 ✔ Scanned for vulnerabilities     [6 vulnerability matches]
   ├── by severity: 0 critical, 0 high, 0 medium, 6 low, 0 negligible
   └── by status:   0 fixed, 6 not-fixed, 0 ignored

Create an HTML Vulnerability Report

Next steps

Try searching for vulnerabilities in an older container!
Learn about SBOM Generation and License Scanning your SBOMs.

2.3 - Publishing the Vulnerability Database

Publishing the Grype Vulnerability Database

TODO

2.4 - Vulnerability Database

Using the Grype Vulnerability Database

Introduction

Grype uses a locally cached database of known vulnerabilities when searching a container, directory, or SBOM for security vulnerabilities. Anchore collates vulnerability data from common feeds, and publishes that data online, at no cost to users.

Learn more

Find out more about the vulnerability data sources at Vulnerability Data Sources.

Updating the local database

When Grype is launched, it checks for an existing vulnerability database, and looks for an updated one online. If available, Grype will automatically download the new database.

Users can manage the locally cached database with the grype db command:

Check and update the database

Manually checking for updates shouldn’t be necessary, due to Grype automatically doing this on launch. However, it is possible to force Grype to look for an updated vulnerability database.

grype db check

A message will indicate if no updates are available since the last download.

Installed DB version v6.0.2 was built on 2025-05-08T04:08:40Z
No update available

If the database is outdated, a message such as this will be displayed.

Installed DB version v6.0.2 was built on 2025-05-07T04:08:13Z
Updated DB version v6.0.2 was built on 2025-05-08T04:08:40Z
You can run 'grype db update' to update to the latest db
[0000] ERROR db upgrade available

grype db update

A short animation will show progress of downloading, uncompressing and hydrating (creating indexes on) the database. Then a message reporting the successful update will be displayed.

grype db update
 ✔ Vulnerability DB                [updated]
Vulnerability database updated to latest version!

Next steps

Learn how the vulnerability DB is created and published.
Learn about SBOM Generation and License Scanning your SBOMs.

3 - License Scanning

License Scanning User Guide.

License scanning involves automatically identifying and analyzing the licenses associated with the various software components used in a project.

This is important because most software relies on third-party and open-source components, each with its own licensing terms that dictate how the software can be used, modified, and distributed, and failing to comply can lead to legal issues.

Grant is an open-source command-line tool designed to discover and report on the software licenses present in container images, SBOM documents, or filesystems. It helps users understand the licenses of their software dependencies and can check them against user-defined policies to ensure compliance.

Get Started - Install Grant and scan a container for compliant licenses.

3.1 -

“+++ title = “Getting Started” description = “License Scanning Getting Started” weight = 10 tags = [“grant”, “licenses”] url = “docs/userguides/license/getstarted” +++

Introduction

Grant searches SBOMs for licenses and the packages they belong to.

Install the latest Grant release

Grant is provided as a single compiled executable. Issue the command for your platform to download the latest release of Grant. The full list of official and community maintained packages can be found on the installation page.

Note

Grant is not currently available for Windows

curl -sSfL <a href="https://get.anchore.io/grant">https://get.anchore.io/grant</a> | sudo sh -s &ndash; -b /usr/local/bin

brew install grant

Scan a container for all the licenses used

grant alpine:latest

Grant will produce a list of licenses.

* alpine:latest
  * license matches for rule: default-deny-all; matched with pattern *
    * Apache-2.0
    * BSD-2-Clause
    * GPL-2.0-only
    * GPL-2.0-or-later
    * MIT
    * MPL-2.0
    * Zlib

Scan a container for OSI compliant licenses

Now we scan a different container, that contains some software that is distributed under non-OSI-compliant licenses.

Note

The image used here is quite large (over 3GB) so may take a while to download and analyze

grant check pytorch/pytorch:latest --osi-approved

Read more in our License Auditing User Guide.

Next steps

Try running Syft against other containers, or an application directory on your workstation.
Find out more about Supported Sources and Output Formats.
Learn about Vulnerability Scanning and License Scanning your SBOMs.

4 - Vulnerability Database

Vulnerability Feeds User Guide.