syft/README.md

syft

A CLI tool and go library for generating a Software Bill of Materials (SBOM) from container images and filesystems.

Features

• Catalog container images and filesystems to discover packages and libraries.
• Supports packages and libraries from various ecosystems (APK, DEB, RPM, Ruby Bundles, Python Wheel/Egg/requirements.txt, JavaScript NPM/Yarn, Java JAR/EAR/WAR, Jenkins plugins JPI/HPI, Go modules)
• Linux distribution identification (supports Alpine, BusyBox, CentOS/RedHat, Debian/Ubuntu flavored distributions)
• Supports Docker and OCI image formats

If you encounter an issue, please let us know using the issue tracker.

Getting started

To generate an SBOM for a Docker or OCI image:

syft packages <image>

# note: this is the same as not providing the "packages" subcommand
syft <image>

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 packages <image> --scope all-layers

Syft can generate a SBOM from a variety of sources:

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

# catalog a directory
syft packages path/to/dir

The output format for Syft is configurable as well:

syft packages <image> -o <format>

Where the formats available are:

• json: Use this to get as much information out of Syft as possible!
• text: A row-oriented, human-and-machine-friendly output.
• cyclonedx: A XML report conforming to the CycloneDX 1.2 specification.
• table: A columnar summary (default).

Installation

Recommended (macOS and Linux)

# install the latest version to /usr/local/bin
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin

# install a specific version into a specific dir
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b <SOME_BIN_PATH> <RELEASE_VERSION>

Homebrew (macOS)

brew tap anchore/syft
brew install syft

Configuration

Configuration search paths:

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

Configuration options (example values are the default):

# the output format of the SBOM report (options: table, text, json)
# same as -o ; SYFT_OUTPUT env var
output: "table"

# suppress all output (except for the SBOM report)
# same as -q ; SYFT_QUIET env var
quiet: false

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

# cataloging packages is exposed through the packages and power-user subcommands
package:
  cataloger:
    # enable/disable cataloging of packages
    # SYFT_PACKAGE_CATALOGER_ENABLED env var
    enabled: true
    
    # the search space to look for packages (options: all-layers, squashed)
    # same as -s ; SYFT_PACKAGE_CATALOGER_SCOPE env var
    scope: "squashed"

# cataloging file metadata is exposed through the power-user subcommand
file-metadata:
  cataloger:
    # enable/disable cataloging of file metadata
    # SYFT_FILE_METADATA_CATALOGER_ENABLED env var
    enabled: true
    
    # the search space to look for file metadata (options: all-layers, squashed)
    # SYFT_FILE_METADATA_CATALOGER_SCOPE env var
    scope: "squashed"
  
  # the file digest algorithms to use when cataloging files (options: "sha256", "md5", "sha1")
  # SYFT_FILE_METADATA_DIGESTS env var
  digests: ["sha256"]

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

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

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

# uploading package SBOM is exposed through the packages subcommand
anchore:
  # (feature-preview) the Anchore Enterprise Host or URL to upload results to (supported on Enterprise 3.0+)
  # same as -H ; SYFT_ANCHORE_HOST env var
  host: ""

  # (feature-preview) the path after the host to the Anchore External API (supported on Enterprise 3.0+)
  # same as SYFT_ANCHORE_PATH env var
  path: ""

  # (feature-preview) the username to authenticate against Anchore Enterprise (supported on Enterprise 3.0+)
  # same as -u ; SYFT_ANCHORE_USERNAME env var
  username: ""

  # (feature-preview) the password to authenticate against Anchore Enterprise (supported on Enterprise 3.0+)
  # same as -p ; SYFT_ANCHORE_PASSWORD env var
  password: ""

  # (feature-preview) path to dockerfile to be uploaded with the syft results to Anchore Enterprise (supported on Enterprise 3.0+)
  # same as -d ; SYFT_ANCHORE_DOCKERFILE env var
  dockerfile: ""