Merge pull request #80 from pdeslaur/deprecate-secdb-docs

chore(secdb): Mark secdb as deprecated

Author: luhring

docs/foundational_concepts.md

@@ -38,7 +38,23 @@ We can use advisory data to produce different kinds of downstream data. The prim
 
 ### Security feeds
 
-#### The secdb
+#### OSV feed (Recommended)
+
+**✅ RECOMMENDED**: New scanner integrations must use the OSV feed. If you're unfamiliar with the OSV format, check out https://ossf.github.io/osv-schema/.
+
+The OSV feed provides several advantages over the secdb. While the secdb uses a format unique to the Alpine community, OSV has grown into a standard used by numerous software ecosystems. On top of that, the OSV format also allows data providers (like Chainguard) to express more detail about each vulnerability and its impact on their provided software artifacts (APKs, in our case).
+
+Chainguard provides a **single OSV feed** that includes security data for both Wolfi and Chainguard's private package repositories — unlike how there are _two secdbs_, for "Wolfi" and "Chainguard" respectively.
+
+An index of Chainguard's OSV data is located at `https://packages.cgr.dev/chainguard/osv/all.json`.
+
+Each individual Chainguard advisory is represented as its own file, where the advisory ID (prefixed with `CGA-`) replaces the "all" in the URL above. For example, the advisory CGA-2226-2498-2frm is located at `https://packages.cgr.dev/chainguard/osv/CGA-2226-2498-2frm.json`.
+
+This OSV feed is licensed under [Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0)](https://creativecommons.org/licenses/by-nc-nd/4.0/?ref=chooser-v1), provided, however, the Chainguard License for Commercial Scanners shall apply to Commercial Scanners available at https://www.chainguard.dev/legal/chainguard-license-for-commercial-scanners, as such terms are defined therein.
+
+#### The secdb (Deprecated)
+
+**⚠️ DEPRECATED**: The secdb format is deprecated for new scanner integrations. Use the [OSV feed](#osv-feed-recommended) instead, which provides richer vulnerability data and follows industry standards.
 
 A secdb is a JSON file that uses the same schema as the Alpine distro's security feeds.
 
@@ -90,20 +106,6 @@ For example, here's an excerpt of the Wolfi secdb:
 
 From this data, we can see that the Wolfi package named `apko`, in its version `0.7.3-r1`, resolved three CVEs: `CVE-2023-28840`, `CVE-2023-28841`, and `CVE-2023-28842`.
 
-#### OSV feed
-
-As an alternative to the secdb, we also provide an OSV feed. If you're unfamiliar with the OSV format, check out https://ossf.github.io/osv-schema/.
-
-The OSV feed provides several advantages over the secdb. While the secdb uses a format unique to the Alpine community, OSV has grown into a standard used by numerous software ecosystems. On top of that, the OSV format also allows data providers (like Chainguard) to express more detail about each vulnerability and its impact on their provided software artifacts (APKs, in our case).
-
-Chainguard provides a **single OSV feed** that includes security data for both Wolfi and Chainguard's private package repositories — unlike how there are _two secdbs_, for "Wolfi" and "Chainguard" respectively.
-
-An index of Chainguard's OSV data is located at `https://packages.cgr.dev/chainguard/osv/all.json`.
-
-Each individual Chainguard advisory is represented as its own file, where the advisory ID (prefixed with `CGA-`) replaces the "all" in the URL above. For example, the advisory CGA-2226-2498-2frm is located at `https://packages.cgr.dev/chainguard/osv/CGA-2226-2498-2frm.json`.
-
-This OSV feed is licensed under [Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0)](https://creativecommons.org/licenses/by-nc-nd/4.0/?ref=chooser-v1), provided, however, the Chainguard License for Commercial Scanners shall apply to Commercial Scanners available at https://www.chainguard.dev/legal/chainguard-license-for-commercial-scanners, as such terms are defined therein.
-
 #### Update frequency
 
 Both Chainguard's secdbs and the OSV feed are updated frequently, as soon as new data is available in our central advisory data store. This means that both data feed mechanisms usually receive updates several times a day.

docs/scanning_implementation.md

@@ -114,11 +114,19 @@ If the SBOM already lists the installed distro packages for you, and each packag
 
 ## Step 3: Matching installed packages to vulnerabilities
 
-🎯 **Goal of this step:** Produce a list of vulnerability matches, where each match links an installed distro package to a known vulnerability, using either the [secdb](foundational_concepts.md#the-secdb) associated with the identified distro or the unified [OSV feed](foundational_concepts.md#osv-feed-experimental).
+🎯 **Goal of this step:** Produce a list of vulnerability matches, where each match links an installed distro package to a known vulnerability, using the [OSV feed](foundational_concepts.md#osv-feed-recommended) (recommended) or the [secdb](foundational_concepts.md#the-secdb-deprecated) (deprecated).
 
-### (If using the secdb) Selecting the correct vulnerability data set
+### Using the OSV feed (Recommended)
 
-As [mentioned in "Foundational Concepts"](./foundational_concepts.md#the-secdb), Chainguard provides two different secdbs. We need to be sure we're using data from the correct secdb.
+**✅ RECOMMENDED**: New scanner integrations must use the OSV feed, which provides richer vulnerability data and follows industry standards.
+
+The OSV feed provides a unified data source for both Wolfi and Chainguard packages, eliminating the need to select between different feeds. See the [OSV feed section](#using-the-osv-feed-to-find-vulnerability-matches) below for implementation details.
+
+### Using the secdb (Deprecated)
+
+**⚠️ DEPRECATED**: The secdb format is deprecated for new scanner integrations. Use the OSV feed instead.
+
+As [mentioned in "Foundational Concepts"](./foundational_concepts.md#the-secdb-deprecated), Chainguard provides two different secdbs. We need to be sure we're using data from the correct secdb.
 
 We make this choice using the distro ID we got from [Step 1: Detecting the distro](#step-1-detecting-the-distro):
 
@@ -148,9 +156,19 @@ For the sake of an example, let's say we have this package on our list:
 },
 ```
 
-#### Using the secdb to find vulnerability matches
+#### Using the OSV feed to find vulnerability matches
+
+To find vulnerabilities in the OSV feed that match a given package, you only need to know the distro ID, the package's name, and its version. (You don't need to find the package's origin package name.)
+
+Packages in the OSV feed are identified by purl (Package URL — see the [specification](https://github.com/package-url/purl-spec) for more information).
+
+OSV JSON documents have an `.affected` property, which is a list of objects. Each object has a `.package` property, which itself has a `.purl` property. You can index this value in order to quickly find vulnerability data given the above information.
+
+For example, if you find that an image's distro ID is `wolfi`, and there's an APK package named `ko` installed, you can look for affected ranges in the OSV documents where the package `purl` is `pkg:apk/wolfi/ko`.
+
+From there, you can find that `affected` object's `.ranges` property in order to compare the APK package's installed version to the versions affected by the given vulnerability.
 
-_(If you're using the OSV feed instead, jump down to [here](#using-the-osv-feed-to-find-vulnerability-matches).)_
+#### Using the secdb to find vulnerability matches (Deprecated)
 
 The next step is to identify vulnerabilities for this package, using data from the [selected secdb](#selecting-the-correct-vulnerability-data-set).
 
@@ -193,19 +211,6 @@ For any `secfixes` entry where our installed package version is LESS THAN the li
 
 So following our example, where our container image has `libcrypto3` version `3.1.1-r2` installed, we'd know that our package is affected by `CVE-2023-3446` and `CVE-2023-3817` — because those CVEs are addressed in _later versions_ of our package than what we have installed in the image. And, we know that our package is not affected by `CVE-2023-0466`, `CVE-2023-4807`, `CVE-2022-4203`, `CVE-2022-4204`, or `CVE-2023-2975`.
 
-
-#### Using the OSV feed to find vulnerability matches
-
-To find vulnerabilities in the OSV feed that match a given package, you only need to know the distro ID, the package's name, and its version. (You don't need to find the package's origin package name.)
-
-Packages in the OSV feed are identified by purl (Package URL — see the [specification](https://github.com/package-url/purl-spec) for more information).
-
-OSV JSON documents have an `.affected` property, which is a list of objects. Each object has a `.package` property, which itself has a `.purl` property. You can index this value in order to quickly find vulnerability data given the above information.
-
-For example, if you find that an image's distro ID is `wolfi`, and there's an APK package named `ko` installed, you can look for affected ranges in the OSV documents where the package `purl` is `pkg:apk/wolfi/ko`.
-
-From there, you can find that `affected` object's `.ranges` property in order to compare the APK package's installed version to the versions affected by the given vulnerability.
-
 #### The meaning of version "0"
 
 You probably noticed above that one of the "fixed" versions in examples above was `"0"`. There was never a version `"0"` of the `libcrypto3` or `openssl` packages. So what does this mean?
@@ -214,7 +219,7 @@ As a standard part of Chainguard's analysis, we identify vulnerabilities that ar
 
 These false positive conclusions get translated to `secfixes` entries (and OSV data) with version `"0"`, because `0` sorts as _less than_ any possible installed version of an APK package.
 
-### (Optional) Supplementing Chainguard's data with additional vulnerability information
+### Supplementing Chainguard's data with additional vulnerability information
 
 It's perfectly acceptable to use only Chainguard's data when performing a scan of a Wolfi or Chainguard distro container image. Chainguard is continuously monitoring numerous vulnerability data sources to identify vulnerabilities that could affect any of its packages, and address any potential vulnerabilities with fixes or other advisory updates (such as identifying **false positives**).