Contributing grype-db vunnel

Grype DB

Developer guidelines when contributing to Grype DB
Categories:
Tags:

Getting started

This codebase is primarily Go, however, there are also Python scripts critical to the daily DB publishing process as well as acceptance testing. You will require the following:

  • Python 3.11+ installed on your system (Python 3.11-3.13 supported). Consider using pyenv if you do not have a preference for managing python interpreter installations.
  • zstd binary utility if you are packaging v6+ DB schemas
  • (optional) xz binary utility if you have specifically overridden the package command options
  • uv installed for Python package and virtualenv management

To download Go tooling used for static analysis, dependent Go modules, and Python dependencies run:

make bootstrap

Useful commands

Common commands for ongoing development:

  • make help - List all available commands
  • make lint - Check code formatting and linting
  • make lint-fix - Auto-fix formatting issues
  • make unit - Run unit tests (Go and Python)
  • make cli - Run CLI tests
  • make db-acceptance schema=<version> - Run DB acceptance tests for a schema version
  • make snapshot - Build release snapshot with all binaries and packages
  • make download-all-provider-cache - Download pre-built vulnerability data cache

Development workflows

Getting vulnerability data

In order to build a grype DB you will need a local cache of vulnerability data:

make download-all-provider-cache

This will populate the ./data directory locally with everything needed to run grype-db build (without needing to run grype-db pull).

This data being pulled down is the same data used in the daily DB publishing workflow, so it should be relatively fresh.

Creating a new DB schema

  1. Create a new v# schema package in the grype repo (within pkg/db)
  2. Create a new v# schema package in the grype-db repo (use the bump-schema.py helper script) that uses the new changes from grype-db
  3. Modify the manager/src/grype_db_manager/data/schema-info.json to pin the last-latest version to a specific version of grype and add the new schema version pinned to the “main” branch of grype (or a development branch)
  4. Update all references in grype to use the new schema
  5. Use the Staging DB Publisher workflow to test your DB changes with grype in a flow similar to the daily DB publisher workflow

Testing with staging databases

While developing a new schema version it may be useful to get a DB built for you by the Staging DB Publisher GitHub Actions workflow. This code exercises the same code as the Daily DB Publisher, with the exception that only a single schema is built and is validated against a given development branch of grype. When these DBs are published you can point grype at the proper listing file like so:

GRYPE_DB_UPDATE_URL=https://toolbox-data.anchore.io/grype/staging-databases/listing.json grype centos:8 ...

Testing

Levels of testing

  • unit (make unit): Unit tests for both Go code in the main codebase and Python scripts in the manager/ directory. These tests focus on correctness of individual functions and components. Coverage metrics track Go test coverage.

  • cli (make cli): CLI tests for both Go and Python components. These validate that command-line interfaces work correctly with various inputs and configurations.

  • db-acceptance (make db-acceptance schema=<version>): Acceptance tests that verify a specific DB schema version works correctly with Grype. These tests build a database, run Grype scans, and validate that vulnerability matches are correct and complete.

Running tests

To run unit tests for Go code and Python scripts:

make unit

To verify that a specific DB schema version interops with Grype:

make db-acceptance schema=<version>
# Note: this may take a while... go make some coffee.

Next Steps

Understanding the Codebase

Related Projects

Getting Help

Last modified November 26, 2025: allow local too invocation (d20d613)