66 lines
3.4 KiB
Markdown
66 lines
3.4 KiB
Markdown
# Setup OSV offline DB Action
|
||
|
||
A reusable Gitea Action that restores or populates the [OSV-Scanner local vulnerability cache](https://google.github.io/osv-scanner/usage/offline-mode/) used with `--offline-vulnerabilities`.
|
||
|
||
Databases are fetched with **curl** from `https://osv-vulnerabilities.storage.googleapis.com/` as described under [Manual database download](https://google.github.io/osv-scanner/usage/offline-mode/#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.
|
||
|
||
## Ecosystems input
|
||
|
||
Use **`ecosystems`**: a comma-separated list (spaces around commas are trimmed). Each token is matched to an entry from [ecosystems.txt](https://osv-vulnerabilities.storage.googleapis.com/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
|
||
|
||
```yaml
|
||
uses: https://gitea.example/your-user/osv-scanner-actions/setup-osv-db@0.0.1
|
||
with:
|
||
ecosystems: PyPI,npm,Go
|
||
```
|
||
|
||
## Example workflow
|
||
|
||
```yaml
|
||
jobs:
|
||
scan:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- 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.
|