DOCSEARCHbyAlgolia
Submit Docs

Grype Vulnerability Scanner

repository·main·Indexed 11 days ago

https://github.com/anchore/grype

A vulnerability scanner for container images, filesystems, and SBOMs that helps developers and security teams identify known vulnerabilities across various OS and language ecosystems.

Tokens
24.1K
Snippets
82
Records
117
Agent score
95%

What's inside Grype

  1. Grype Overview and Features

    main

    Grype is a vulnerability scanner designed for container images, filesystems, and SBOMs.

    Key Capabilities:

    • Broad Ecosystem Support: Scans major OS package ecosystems (Alpine, Debian, Ubuntu, RHEL, Oracle Linux, Amazon Linux, etc.) and language-specific packages (Ruby, Java, JavaScript, Python, .NET, Go, PHP, Rust, etc.).
    • Image Format Support: Supports Docker, OCI, and Singularity image formats.
    • Risk Prioritization: Integrates with EPSS, KEV, and risk scoring to help prioritize vulnerabilities.
    • OpenVEX Support: Allows for filtering and augmenting scan results using OpenVEX.

  2. Use Grype Go templates for custom reports

    main
    Grype provides a set of helper Go templates that can be used to generate custom vulnerability reports. These templates allow you to format Grype scan results into different structures like HTML, CSV, JUnit, or tables. You can extend or modify these templates to suit your specific reporting needs.

  3. Use fluent assertions for vulnerability matching

    main

    The dbtest package provides string-based, API-agnostic assertion helpers to validate match results. This decouples tests from internal API shapes and ensures completeness.

    Completeness Checking

    By default, assertions require that all matches and details are asserted. If a matcher returns results that you haven't explicitly checked, the test will fail.

    To assert that a chain is intentionally partial, use SkipCompleteness(). If you use SkipCompleteness() but your chain ends up being exhaustive, the test will fail, signaling that the call is dead weight and should be removed.

    Basic Usage Patterns

    // Match and assert in one chain
db.Match(t, &matcher, pkg).
    SelectMatch("CVE-2024-1234").
    SelectDetailByType(match.ExactDirectMatch).
    AsDistroSearch("< 1.0.0")

// Use AssertFindings with existing matches
dbtest.AssertFindings(t, matches, pkg).
    HasCount(2).
    OnlyHasVulnerabilities("CVE-2024-1234", "CVE-2024-5678")

  5. Fixture directory structure and metadata

    main

    Extracted fixtures follow the vunnel workspace format. Each fixture contains configuration and state tracking files.

    Directory Layout

    fixture/
├── db.yaml               # extraction config (auto-generate flag, patterns)
├── db-lock.json          # state tracking (content hash, timestamps)
├── provider-name/
│   ├── metadata.json     # provider state (store: "flat-file")
│   └── results/
│       ├── debian@11_CVE-2024-1234.json
│       ├── debian@11_CVE-2024-5678.json
│       └── listing.xxh64
└── another-provider/
    ├── metadata.json
    └── results/
        └── ...

    Note: : in identifiers is replaced with @ and / with _ in filenames.

    db.yaml (Intent)

    This file is human-editable and defines what extractions should be performed.

    • auto-generate (bool): If true, the fixture can be regenerated from the vunnel cache.
    • extractions (map): A map of provider names to lists of patterns.

    db-lock.json (State)

    This machine-generated file tracks the state of the fixture.

    • content_hash: xxh64 hash of fixture content (excludes db.yaml and db-lock.json).
    • created_at: Timestamp when the fixture was first created.
    • regenerated_at: Timestamp when it was last regenerated.
    • providers.<name>.vunnel_version: Vunnel version used by the provider.
    • providers.<name>.timestamp: Provider's data timestamp.

  6. Understand the `db-search vuln` JSON Schema versioning

    main

    The JSON schema for the grype db search vuln command follows a specific versioning format: MODEL.REVISION.ADDITION. This is a variation of Semantic Versioning designed for data models:

    • MODEL: Increment this when making a breaking schema change that prevents interaction with any historical data.
    • REVISION: Increment this when making a schema change that may prevent interaction with some historical data.
    • ADDITION: Increment this when making a schema change that remains compatible with all historical data.

  7. Versioning the `db-search` JSON Schema

    main

    The db-search schema uses a versioning format of MODEL.REVISION.ADDITION (a variation of Semantic Versioning for data models). To update the version, you must manually change the MatchesSchemaVersion constant in cmd/grype/cli/commands/internal/dbsearch/versions.go.

    MODEL.REVISION.ADDITION

- MODEL: Increment for breaking changes that prevent interaction with any historical data.
- REVISION: Increment for changes that may prevent interaction with some historical data.
- ADDITION: Increment for changes compatible with all historical data.

  8. Understand the `db-diff` JSON Schema

    main

    The db-diff JSON schema defines the structure of the output produced by the grype db diff command. The schema is governed by two primary components:

    1. The SchemaVersion value (defined in grype/db/v6/diff.SchemaVersion).
    2. The Result type definition (defined in github.com/anchore/grype/grype/db/v6/diff/result.go), which determines the overall shape of the JSON document.

  9. Understand Grype v6 schema versioning (SchemaVer)

    main

    Grype uses the SchemaVer format: MODEL.REVISION.ADDITION.

    • MODEL: Increment for breaking changes that prevent interaction with ALL historical data. Requires team consultation.
    • REVISION: Increment for changes that may prevent interaction with SOME historical data.
    • ADDITION: Increment for changes that are compatible with ALL historical data.

    Important: Never delete or modify existing versioned schema files. Only add new versions.

  10. Pattern matching rules for fixture selection

    main

    When using the --select flag, patterns use SQL LIKE matching with automatic wildcards. All patterns are automatically wrapped with % for partial matching.

    PatternMatchesDescription
    CVE-2024-1234debian:10/CVE-2024-1234, ubuntu:20.04/CVE-2024-1234Matches CVE in any namespace
    debian:10debian:10/CVE-2024-1234, debian:10/CVE-2024-5678Matches all CVEs in namespace
    debiandebian:10/..., debian:11/...Matches all debian namespaces
    RHSA-2024:rhel:8/RHSA-2024:0001, rhel:9/RHSA-2024:0002Matches all 2024 RHSAs
    debian:11/CVE-2024-1234debian:11/CVE-2024-1234Exact match

    Multiple --select patterns are combined using OR logic.

  11. Scan container images and directories with Grype

    main

    Grype can scan various targets for known vulnerabilities, including container images (Docker, OCI, and Singularity formats) and local filesystems/directories.

    To scan a container image, provide the image name. To scan a local directory, provide the path to the directory.

    # Scan a container image
grype alpine:latest

# Scan a directory
grype ./my-project

  12. Workflow: Creating a manual fixture

    main

    Manual fixtures are useful when you need custom modifications that should not be overwritten by automatic regeneration.

    1. Extract base: Run extract to create the initial structure.
    2. Modify: Manually edit the files in the fixture directory.
    3. Disable auto-generation: Edit db.yaml and set auto-generate: false. This prevents the regenerate command from overwriting your changes.
    4. Commit: Add the modified fixture to version control.
    # 1. extract base
go run ./internal/dbtest/cmd/manager extract \
    --vunnel-data ~/vunnel/data \
    --provider debian --select "CVE-2024-1234" \
    --output internal/dbtest/testdata/shared/manual-fixture

# 2. manually modify files
# (e.g. vim internal/dbtest/testdata/shared/manual-fixture/debian/results/...)

# 3. edit db.yaml to set auto-generate: false

# 4. commit
git add internal/dbtest/testdata/shared/manual-fixture/
git commit -m "add manual-fixture with custom modifications"