From 75bfecfe11c9fe944a8ddc31346beda4d81ab731 Mon Sep 17 00:00:00 2001
From: Will Murphy <willmurphyscode@users.noreply.github.com>
Date: Wed, 25 Sep 2024 16:55:19 -0400
Subject: [PATCH] docs: start documenting how to add new provider

Many of these docs are over at Vunnel, but Grype is
sort of the central repo for how these vulnerabilities
are reported, so an outline at least belongs in Grype.

Signed-off-by: Will Murphy <willmurphyscode@users.noreply.github.com>
---
 DEVELOPING.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)

diff --git a/DEVELOPING.md b/DEVELOPING.md
index 3c1993ecbb0..3adc899ef57 100644
--- a/DEVELOPING.md
+++ b/DEVELOPING.md
@@ -79,3 +79,101 @@ id             record_source  package_name  namespace   version_constraint  vers
 -------------  -------------  ------------  ----------  ------------------  --------------  -----------------------------------------------------------  ---------------------
 CVE-2006-2450                 libvncserver  nvd         = 0.7.1             unknown         ["cpe:2.3:a:libvncserver:libvncserver:0.7.1:*:*:*:*:*:*:*"]  []
 ```
+
+## Adding a Data Source
+
+These are the steps for adding a new data source to Grype. For example,
+maybe we don't have vulnerabilities for your favorite Linux yet, or
+maybe a language you work in hosts a vulnerability feed on their package
+manager, and you would like to add it to Grype. Here is an outline of the
+process.
+
+### Step 1: Ensure Syft can Find what you want to Match
+
+Grype uses [Syft](https://github.com/anchore/syft) to scan artifacts.
+
+Before Grype can tell you whether a package is vulnerable, Syft needs
+to be able to correctly identify the package.
+
+If you're adding a new distro, you could run something like:
+
+``` sh
+syft -o json my-favorite-distro:latest | jq .distro
+```
+
+and make sure you agree with what you see. Syft will automatically
+try to parse distro information from `/etc/os-release`, so you probably
+don't need to make a change here, but it's a good idea to check.
+
+Next, make sure syft can find packages you want:
+
+``` sh
+syft my-favorite-distro:latest
+```
+
+and take a look at the resulting table. Are you seeing the OS packages you'd
+expect to see? For example, here's `alpine:latest` as of this writing:
+
+``` sh
+$ syft -o json alpine:latest | jq .distro
+{
+  "prettyName": "Alpine Linux v3.20",
+  "name": "Alpine Linux",
+  "id": "alpine",
+  "versionID": "3.20.0",
+  "homeURL": "https://alpinelinux.org/",
+  "bugReportURL": "https://gitlab.alpinelinux.org/alpine/aports/-/issues"
+}
+$ syft alpine:latest
+ ✔ Loaded image                                                  alpine:latest
+ ... snip ...
+NAME                    VERSION      TYPE   
+alpine-baselayout       3.6.5-r0     apk     
+alpine-baselayout-data  3.6.5-r0     apk     
+alpine-keys             2.4-r1       apk     
+...
+```
+
+Syft is identifying Alpine Linux correctly, and is finding `apk` packages (that
+is, packages from Alpine's package manager), so we're good to go.
+
+If Syft does not identify your the new distro or the its package manager's
+packages correctly, please [open an issue
+there](https://github.com/anchore/syft/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=)
+
+
+### Step 2. Add a Vunnel Provider
+
+[Vunnel](https://github.com/anchore/vunnel) is a project that serves as an
+adapter layer between vulnerability providers and Grype's code base. The main
+coding work of adding a data source to Grype is to write a Vunnel provider
+that takes the vulnerability data from its source and renders it in a format
+that [Grype DB](https://github.com/anchore/grype-db) speaks, so that it can
+be written into the database that grype downloads on each execution.
+
+Create a new directory in which to clone 3 repos:
+
+1. This repo, grype
+2. [Vunnel](https://github.com/anchore/vunnel)
+3. [Grype DB](https://github.com/anchore/grype-db)
+
+So that it looks like this:
+
+``` sh
+.
+├── grype
+├── grype-db
+└── vunnel
+```
+
+The majority of the work will be done within Vunnel. Vunnel
+has a command `make dev` that has a few effects:
+
+1. It compiles `grype` and `grype-db` binaries from the source code in the
+   sibling directories
+2. It writes config files for `grype` and `grype-db` so that they use the
+   development vunnel
+3. Creates a `poetry shell` to put vunnel and its python dev tools on PATH
+
+For more details on actually building the vunnel provider, see the
+[Vunnel development docs](https://github.com/anchore/vunnel/blob/main/DEVELOPING.md)