grype

Grype logo

A vulnerability scanner for container images and filesystems. Easily install the binary to try it out. Works with Syft, the powerful SBOM (software bill of materials) tool for container images and filesystems.

Join our community meetings!

Calendar: https://calendar.google.com/calendar/u/0/r?cid=Y182OTM4dGt0MjRtajI0NnNzOThiaGtnM29qNEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t
Agenda: https://docs.google.com/document/d/1ZtSAa6fj2a6KRWviTn3WoJm09edvrNUp4Iz_dOjjyY8/edit?usp=sharing (join this group for write access)
All are welcome!

For commercial support options with Syft or Grype, please contact Anchore

grype-demo

Features

Scan the contents of a container image or filesystem to find known vulnerabilities.
Find vulnerabilities for major operating system packages:
- Alpine
- Amazon Linux
- BusyBox
- CentOS
- CBL-Mariner
- Debian
- Distroless
- Oracle Linux
- Red Hat (RHEL)
- Ubuntu
- Wolfi
Find vulnerabilities for language-specific packages:
- Ruby (Gems)
- Java (JAR, WAR, EAR, JPI, HPI)
- JavaScript (NPM, Yarn)
- Python (Egg, Wheel, Poetry, requirements.txt/setup.py files)
- Dotnet (deps.json)
- Golang (go.mod)
- PHP (Composer)
- Rust (Cargo)
Supports Docker, OCI and Singularity image formats.
OpenVEX support for filtering and augmenting scanning results.

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

Installation

Chocolatey

The chocolatey distribution of grype is community maintained and not distributed by the anchore team

choco install grype -y

Homebrew

brew tap anchore/grype
brew install grype

MacPorts

On macOS, Grype can additionally be installed from the community maintained port via MacPorts:

sudo port install grype

Note: Currently, Grype is built only for macOS and Linux.

From source

See DEVELOPING.md for instructions to build and run from source.

GitHub Actions

If you're using GitHub Actions, you can simply use our Grype-based action to run vulnerability scans on your code or container images during your CI workflows.

Verifying the artifacts

Checksums are applied to all artifacts, and the resulting checksum file is signed using cosign.

You need the following tool to verify signature:

Cosign

Verification steps are as follow:

Download the files you want, and the checksums.txt, checksums.txt.pem and checksums.txt.sig files from the releases page:
Verify the signature:

cosign verify-blob <path to checksum.txt> \
--certificate <path to checksums.txt.pem> \
--signature <path to checksums.txt.sig> \
--certificate-identity-regexp 'https://github\.com/anchore/grype/\.github/workflows/.+' \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"

Once the signature is confirmed as valid, you can proceed to validate that the SHA256 sums align with the downloaded artifact:

sha256sum --ignore-missing -c checksums.txt

Getting started

Install the binary, and make sure that grype is available in your path. To scan for vulnerabilities in an image:

grype <image>

The above command scans for vulnerabilities that are visible in the container (i.e., the squashed representation of the image). To include software from all image layers in the vulnerability scan, regardless of its presence in the final image, provide --scope all-layers:

grype <image> --scope all-layers

To run grype from a Docker container so it can scan a running container, use the following command:

docker run --rm \
--volume /var/run/docker.sock:/var/run/docker.sock \
--name Grype anchore/grype:latest \
$(ImageName):$(ImageTag)

Supported sources

Grype can scan a variety of sources beyond those found in Docker.

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

# scan a Singularity Image Format (SIF) container
grype path/to/image.sif

# scan a directory
grype dir:path/to/dir

Sources can be explicitly provided with a scheme:

podman:yourrepo/yourimage:tag          use images from the Podman daemon
docker:yourrepo/yourimage:tag          use images from the Docker daemon
docker-archive:path/to/yourimage.tar   use a tarball from disk for archives created from "docker save"
oci-archive:path/to/yourimage.tar      use a tarball from disk for OCI archives (from Skopeo or otherwise)
oci-dir:path/to/yourimage              read directly from a path on disk for OCI layout directories (from Skopeo or otherwise)
singularity:path/to/yourimage.sif      read directly from a Singularity Image Format (SIF) container on disk
dir:path/to/yourproject                read directly from a path on disk (any directory)
sbom:path/to/syft.json                 read Syft JSON from path on disk
registry:yourrepo/yourimage:tag        pull image directly from a registry (no container runtime required)

If an image source is not provided and cannot be detected from the given reference it is assumed the image should be pulled from the Docker daemon. If docker is not present, then the Podman daemon is attempted next, followed by reaching out directly to the image registry last.

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

Use SBOMs for even faster vulnerability scanning in Grype:

# Then scan for new vulnerabilities as frequently as needed
grype sbom:./sbom.json

# (You can also pipe the SBOM into Grype)
cat ./sbom.json | grype

Grype supports input of Syft, SPDX, and CycloneDX SBOM formats. If Syft has generated any of these file types, they should have the appropriate information to work properly with Grype. It is also possible to use SBOMs generated by other tools with varying degrees of success. Two things that make Grype matching more successful are the inclusion of CPE and Linux distribution information. If an SBOM does not include any CPE information, it is possible to generate these based on package information using the --add-cpes-if-none flag. To specify a distribution, use the --distro <distro>:<version> flag. A full example is:

grype --add-cpes-if-none --distro alpine:3.10 sbom:some-alpine-3.10.spdx.json

Supported versions

Any version of Grype before v0.40.1 is not supported. Unsupported releases will not receive any software updates or vulnerability database updates. You can still build vulnerability databases for unsupported Grype releases by using previous releases of vunnel to gather the upstream data and grype-db to build databases for unsupported schemas.

Working with attestations

Grype supports scanning SBOMs as input via stdin. Users can use cosign to verify attestations with an SBOM as its content to scan an image for vulnerabilities:

COSIGN_EXPERIMENTAL=1 cosign verify-attestation caphill4/java-spdx-tools:latest \
| jq -r .payload \
| base64 --decode \
| jq -r .predicate.Data \
| grype

Vulnerability Summary

Basic Grype Vulnerability Data Shape

 {
  "vulnerability": {
    ...
  },
  "relatedVulnerabilities": [
    ...
  ],
  "matchDetails": [
    ...
  ],
  "artifact": {
    ...
  }
}

Vulnerability: All information on the specific vulnerability that was directly matched on (e.g. ID, severity, CVSS score, fix information, links for more information)
RelatedVulnerabilities: Information pertaining to vulnerabilities found to be related to the main reported vulnerability. Maybe the vulnerability we matched on was a GitHub Security Advisory, which has an upstream CVE (in the authoritative national vulnerability database). In these cases we list the upstream vulnerabilities here.
MatchDetails: This section tries to explain what we searched for while looking for a match and exactly what details on the package and vulnerability that lead to a match.
Artifact: This is a subset of the information that we know about the package (when compared to the Syft json output, we summarize the metadata section). This has information about where within the container image or directory we found the package, what kind of package it is, licensing info, pURLs, CPEs, etc.

Excluding file paths

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

grype <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'.

External Sources

Grype can be configured to incorporate external data sources for added fidelity in vulnerability matching. This feature is currently disabled by default. To enable this feature add the following to the grype config:

external-sources:
  enable: true
  maven:
    search-upstream-by-sha1: true
    base-url: https://repo1.maven.org/maven2

You can also configure the base-url if you're using another registry as your maven endpoint.

Output formats

The output format for Grype is configurable as well:

grype <image> -o <format>

Where the formats available are:

table: A columnar summary (default).
cyclonedx: An XML report conforming to the CycloneDX 1.6 specification.
cyclonedx-json: A JSON report conforming to the CycloneDX 1.6 specification.
json: Use this to get as much information out of Grype as possible!
sarif: Use this option to get a SARIF report (Static Analysis Results Interchange Format)
template: Lets the user specify the output format. See "Using templates" below.

Using templates

Grype lets you define custom output formats, using Go templates. 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).
Grype's template processing uses the same data models as the json output format — so if you're wondering what data is available as you author a template, you can use the output from grype <image> -o json as a reference.

Please note: Templates can access information about the system they are running on, such as environment variables. You should never run untrusted templates.

There are several example templates in the templates directory in the Grype source which can serve as a starting point for a custom output format. For example, csv.tmpl produces a vulnerability report in CSV (comma separated value) format:

"Package","Version Installed","Vulnerability ID","Severity"
"coreutils","8.30-3ubuntu2","CVE-2016-2781","Low"
"libc-bin","2.31-0ubuntu9","CVE-2016-10228","Negligible"
"libc-bin","2.31-0ubuntu9","CVE-2020-6096","Low"
...

You can also find the template for the default "table" output format in the same place.

Grype 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 from Grype.

Gating on severity of vulnerabilities

You can have Grype exit with an error if any vulnerabilities are reported at or above the specified severity level. This comes in handy when using Grype within a script or CI pipeline. To do this, use the --fail-on <severity> CLI flag.

For example, here's how you could trigger a CI pipeline failure if any vulnerabilities are found in the ubuntu:latest image with a severity of "medium" or higher:

grype ubuntu:latest --fail-on medium

Specifying matches to ignore

If you're seeing Grype report false positives or any other vulnerability matches that you just don't want to see, you can tell Grype to ignore matches by specifying one or more "ignore rules" in your Grype configuration file (e.g. ~/.grype.yaml). This causes Grype not to report any vulnerability matches that meet the criteria specified by any of your ignore rules.

Each rule can specify any combination of the following criteria: