Grype - Find Security Vulnerabilities Before They Bite You

Grype is a command-line tool that scans your Docker images and finds known security vulnerabilities. That's it. No enterprise sales pitch, no "paradigm-shifting solutions" - it just tells you what's broken in your containers so you can fix it before someone exploits it.

Been running this for a while now in production, and here's what actually matters.

The Problem: Your Images Are Full of Holes

Look, every Docker image you pull has vulnerabilities. Pull ubuntu:20.04 right now and scan it - you'll find dozens of CVEs. Pull node:16-alpine and you'll find more. That fancy base image your team loves? Also compromised.

The issue isn't that vulnerabilities exist (they always will), it's that most teams have no idea what's in their images. You layer on packages, add dependencies, copy in binaries, and ship to production without knowing you're running OpenSSL 1.1.1k with CVE-2021-3712.

Learned this the hard way during a security audit where they found hundreds of "critical" vulnerabilities in our prod images. Most of them were in random OS packages we never touch, but try explaining that to an auditor who just wants everything fixed. Spent that whole weekend dealing with the mess. NIST's guidance on container security makes it clear that visibility into your software supply chain is critical.

How Grype Actually Works

Grype downloads a vulnerability database (about 150MB) that gets updated daily with CVE feeds from multiple sources including NVD, Alpine SecDB, and Ubuntu Security Notices. When you scan an image, it:

It rips apart your image layer by layer, checks every package against its vulnerability database, then spits out everything that's broken and how badly you're screwed.

The scan takes about 5-15 seconds for typical images. Faster than Clair (when Clair isn't completely fucked), more accurate than most commercial tools, and way less painful than explaining to your CISO why you shipped prod with a 2019 version of curl.

SBOMs That Don't Completely Suck

Grype pairs with Syft to generate Software Bills of Materials. Before you roll your eyes - this is actually practical.

Generate an SBOM once during your build: syft packages my-app:latest -o json > sbom.json

Then scan the SBOM instead of the image: grype sbom:sbom.json

This cuts scan time from 10 seconds to 2 seconds, which matters when you're scanning 50+ images in CI. Plus you get inventory tracking for free, which makes compliance people happy. The executive order on cybersecurity specifically calls out SBOMs as critical for supply chain security.

Real Performance Numbers

Scan times vary like hell depending on your setup:

• Alpine apps: pretty fast - few seconds on my laptop, longer on our shitty CI runners
• Ubuntu-based stuff: takes longer - maybe 8-15 seconds depending on how much crap you've installed
• Java fat JARs: can take forever when Spring Boot includes the entire internet as dependencies
• Full OS images: 15+ seconds usually, longer when your network decides to be garbage

Memory usage stays under 100MB, so it doesn't kill your CI runners like some other tools do. Check out Anchore's benchmarks against other scanners.

The Gotchas You'll Hit

Database updates can break CI: Grype downloads the vuln database on first run. If your CI doesn't cache this properly, you'll hit rate limits or timeouts. I've watched entire teams get blocked for hours because someone changed the CDN endpoint and our corporate proxy wasn't updated. Set up a cron job to pre-pull the database or use the offline mode.

False positives in distroless images: Had an older version that was totally broken with distroless base images - reported vulnerabilities for packages that weren't even installed. Spent a day chasing phantom CVEs before realizing it was a Grype bug. Fixed in newer versions, but pin your Grype version in CI or you'll get burned by shit like this.

Windows paths will fuck you: On Windows, the database cache path gets mangled and Grype randomly fails with "cannot write to cache directory". Use GRYPE_DB_CACHE_DIR=C: emp\grype explicitly or it'll try to write to some deep nested AppData folder that doesn't exist.

Alpine packages get weird: Alpine uses different package names than Debian/Ubuntu. Sometimes Grype misses vulnerabilities in Alpine packages because the CVE database uses the Debian naming. Not Grype's fault, but worth knowing. Some versions are more aggressive about package matching which leads to more false positives. The Alpine security team maintains their own security database, but it's often weeks behind CVE publications.

Java apps timeout randomly: Large Spring Boot JARs (anything over 200MB) can cause Grype to hang on certain versions. The JAR scanning can be slow as hell. Use --timeout 10m or scan the SBOM instead of raw images if you're hitting timeouts.

The tool works, it's fast, and it doesn't require a PhD to configure. That's more than I can say for most security tools. If you want deeper integration, check out Anchore Enterprise for policy enforcement and Kubernetes admission controllers.

Here's the practical stuff you actually need to know about Grype's capabilities.

Language Support That Actually Matters

Grype scans OS packages and language dependencies. The full list of supported languages is extensive, but here's what I've tested in production:

Python: Finds vulnerabilities in pip packages, Poetry lock files, and requirements.txt. Works well most of the time but gets confused with local packages that don't have proper metadata.

JavaScript: Scans npm and Yarn dependencies accurately. Catches vulnerabilities in node_modules even when they're nested 47 levels deep. Sometimes reports false positives for dev dependencies, but you can filter those out with npm audit exclusions.

Java: Analyzes JAR files and finds vulnerabilities in dependencies. The JAR scanning can be slow on fat JARs (looking at you, Spring Boot), but it's thorough. Works with Maven and Gradle projects.

Go: Scans go.mod files and compiled binaries. Works great for Go modules but misses vulnerabilities in vendor directories if they're not properly documented. Compare with govulncheck for Go-specific scanning.

Others: Rust, PHP Composer, Ruby Gems, and .NET NuGet support exists but haven't tested them much. Docs say they work but your mileage may vary.

Input Formats (Pick What Works)

You can scan:

• Docker images: grype alpine:latest
• Local directories: grype dir:./my-project
• SBOM files: grype sbom:./app.json
• Tar archives: grype docker-archive:image.tar
• Registry images without pulling: grype registry:my-registry.com/app:v1.2.3

The registry scanning is clutch for CI environments where you don't want to pull 2GB images just to scan them.

Output Formats for Different Use Cases

Table format (default): Human-readable, good for terminal use

grype alpine:latest

JSON for automation:

grype alpine:latest -o json | jq '.matches[] | select(.vulnerability.severity == \"Critical\")'

SARIF for GitHub integration:

grype alpine:latest -o sarif

Template for custom reporting:

grype alpine:latest -o template -t my-custom-format.tmpl

CI/CD Integration (The Important Part)

GitHub Actions - Use the official action:

- name: Scan container
  uses: anchore/scan-action@v3
  with:
    image: \"my-app:latest\"
    fail-build: true
    severity-cutoff: critical

Other CI systems - Install the binary and use exit codes. Works with Jenkins, GitLab CI, and Azure DevOps, when they're not completely fucking broken:

## Fail build on critical vulnerabilities
grype my-app:latest --fail-on critical

## Fail on high or critical (prepare for broken builds)
grype my-app:latest --fail-on high

Jenkins gotcha: The plugin is garbage and randomly hangs. Just install the binary directly and call it from shell steps. Much more reliable.

GitLab CI gotcha: The default container scanning template uses an ancient version of Grype. Override it or you'll get inconsistent results compared to local scans.

Filtering and Ignoring Stuff

Create a .grype.yaml config to ignore false positives:

ignore:
  # Ignore this specific CVE
  - vulnerability: \"CVE-2021-44228\"

  # Ignore vulnerabilities in test files
  - package:
      location: \"**/test/**\"

  # Ignore low severity in dev dependencies
  - vulnerability:
      severity: \"Low\"
    package:
      location: \"**/node_modules/**\"

This is essential because you'll get flooded with noise otherwise.

Performance Tips from Real Use

Use SBOM caching: Generate the SBOM once in your build, then scan it multiple times:

## In your build stage
syft my-app:latest -o json > app-sbom.json

## In your security stage
grype sbom:app-sbom.json

Cache the vulnerability database: Set GRYPE_DB_CACHE_DIR to a persistent location to avoid re-downloading 150MB on every run.

Parallel scanning: Grype uses multiple cores by default, but you can limit it with GRYPE_PARALLELISM=2 if you're on resource-constrained CI runners.

Air-Gapped Environments

If you're in a locked-down environment:

## Download the database on a connected machine
grype db update

## Export it
grype db export grype-db.tar.gz

## Import on air-gapped system
grype db import grype-db.tar.gz

## Now scan offline
grype my-app:latest

Used this setup in locked-down environments before. Works fine, just remember to update the database periodically or you'll miss new vulnerabilities.

When Things Break

Error: "database metadata not found": The database download failed or got corrupted. Delete ~/.cache/grype and try again. On Windows, the cache is buried in %APPDATA%\Local\grype and you'll need admin rights to clear it.

Scan hangs on Java apps: Large JAR files can cause timeouts, especially Spring Boot fat JARs over 200MB. Increase the timeout with --timeout 10m or scan the SBOM instead of the image. If it's still hanging after 10 minutes, your JAR is probably corrupted or Grype hit a parsing bug.

"No such file or directory" on Alpine: Version mismatch between Grype and the Alpine package database. Update Grype or use a different base image temporarily. Had this happen with newer Alpine versions where the databases took a while to sync up. Check the Alpine package search to verify package existence.

"Permission denied" on macOS: macOS Gatekeeper blocks the binary. Run sudo xattr -rd com.apple.quarantine /usr/local/bin/grype to fix it, assuming you trust Anchore not to steal your crypto.

Database download timeouts: Corporate proxies love to block Grype's CDN endpoints randomly. Set up a cron job to download the database during off-hours, or use the offline mode if your IT department is particularly incompetent.

The tool is solid, but like any CLI tool, it has its quirks. Once you know them, it's reliable as hell. For more troubleshooting, check the GitHub issues or community forums. The configuration reference covers all available options.