sec-actions/setup-osv-db

Setup OSV offline DB Action

A reusable Gitea Action that restores or populates the OSV-Scanner local vulnerability cache used with --offline-vulnerabilities.

Databases are fetched with curl from https://osv-vulnerabilities.storage.googleapis.com/ as described under Manual database download: for each requested ecosystem, download …/<ecosystem>/all.zip into osv-scanner/<ecosystem>/all.zip. OSV-Scanner is not invoked for downloads.

Requires: curl, bash 4+ (associative arrays), python3 (URL-encoding paths).

Note: This action only prepares the local DB directory. Install the scanner separately (e.g. with the setup-osv-scanner action).

Ecosystems input

Use ecosystems: a comma-separated list (spaces around commas are trimmed). Each token is matched to an entry from ecosystems.txt by:

• Slug match: lowercased, spaces → -, brackets removed (e.g. GitHub Actions and github-actions both match).
• Special case: docker is not an OSV ecosystem; it is treated as Linux (useful as a default when scanning image-related data). Override with Alpine, Debian, etc. if you prefer.

The actions/cache key includes the sorted, slugified list of resolved ecosystems (e.g. github-actions,go,linux,npm) plus the hour bucket settings, so different ecosystem sets never share a cache entry.

Usage

uses: https://gitea.example/your-user/osv-scanner-actions/setup-osv-db@0.0.1
with:
  ecosystems: PyPI,npm,Go

Example workflow

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup OSV-Scanner
        uses: https://gitea.example/your-user/osv-scanner-actions/setup-osv-scanner@0.0.1
      - name: Setup offline DB
        id: setup-db
        uses: https://gitea.example/your-user/osv-scanner-actions/setup-osv-db@0.0.1
        with:
          cache-bucket-hours: 6
          ecosystems: github-actions,npm,go,Alpine
      - name: Scan (offline vulnerabilities only)
        env:
          OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY: ${{ steps.setup-db.outputs.cache-dir }}
        run: osv-scanner scan source --offline-vulnerabilities -r .

Inputs

Name	Description	Required	Default
cache-dir	Directory for OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY	No	${{ runner.temp }}/osv-scanner
cache-bucket-hours	actions/cache primary key includes floor(UTC unix time / (3600 × N)).	No	24
ecosystems	Comma-separated tokens (names/slugs; docker → Linux).	No	github-actions,npm,go,docker

Outputs

Name	Description
cache-dir	Same as input path

Behavior

• Cache: Key pattern osv-scanner-db-{hours}h-eco-{sorted-slugs}-{bucket}. restore-keys reuse the newest cache for the same hours + ecosystem set when the current time bucket misses.
• Populate: On cache miss, ${cache-dir}/osv-scanner is recreated and only the requested ecosystems are downloaded.