Merge pull request #12 from joshbressers/josh-20240320-01

Update the readme

README.md

@@ -6,29 +6,34 @@ This repo is meant to provide additional data that is currently missing from NVD
 
 Please note, this data does not provide severity information. By definition only NVD can supply NVD CVSS scores.
 
-# Contributing
+The tooling that drives this repo as well as ideas for capturing the vulnerability data in a nicer way is being tracked in a repo called [vulnerability-data-tools](https://github.com/anchore/vulnerability-data-tools). Please use that repo for future ideas.
 
-If you are looking to contribute to this project and want to open a GitHub pull request ("PR"). Please make sure you create a signed-off commit with -s or --signoff passed to the git command.
+# Repository layout
 
-# Future vulnerability data effort
+This repository contains the data for the NVD overrides. This is data meant to enrich the JSON currently being returned by NVD.
 
-The tooling that drives this repo as well as ideas for capturing the vulnerability data in a nicer way is being tracked in a repo called [vulnerability-data-tools](https://github.com/anchore/vulnerability-data-tools). Please use that repo for future ideas.
+The `.snapshot` directory is meant to capture the original nvd record state for any properties which we are overriding at the time it is overridden so that in future if any of those properties on the upstream record change we can detect that we need to reconcile with our overridden values. For the moment it will only be useful if NVD start adding CPE configuration nodes again.
 
-We have a Google Document that describes some ideas and concepts for a later vulnerability enrichment project. This particular repository is a short term stopgap to quickly deal with the missing NVD enrichment. Long term we would like to provide vulnerability enrichment in a much more sustainable way. The data in this repository will be included in the future efforts, so the work is not wasted effort.
+In the `data` directory the override files are separated by year. The JSON in these files is meant to be inserted into the JSON from NVD for a given CVE ID. The CVE ID is not recorded in the JSON file, it should be extracted from the filename. Think of this as additional data that can be inserted into the NVD records as returned by the [NVD API](https://nvd.nist.gov/developers/vulnerabilities).
 
-https://docs.google.com/document/d/1ccW_ng9HVwuTWiL2dGC5Tqb_CKef6pAEwRQ4tg_aDgw/edit#heading=h.7lelh5vxqxu4
+At the moment the focus is on the CPE matching data. Additional data such as vendor severity and CWE would be welcome additions.
 
-We have a lot of ideas on how to do this better in the future. We envision a data format capable of generating the data currently stored in this repository. The NVD format is very constrained. By capturing the same data but formatting it in a nicer way, it will be possible to output any format needed. NVD, OSV, cve5, and more. Think of this repository as a place to learn what we don't know yet.
+# Contributing
+
+If you're looking to get involved this probably isn't the best place to start. The [vulnerability-data-tools](https://github.com/anchore/vulnerability-data-tools) repo is where the tools and planning exists. You should probably start there.
 
-Regardless of the data format used, it can be expected that this override data will be generated and available for the forseeable future.
+If you are looking to contribute to this project and want to open a GitHub pull request ("PR"). Please make sure you create a signed-off commit with -s or --signoff passed to the git command.
 
 # FAQ
 
 ### Why are you doing this?
  This data provided by NVD was used by Grype to match artifacts not covered by other data sources. We refer to this as the "matcher of last resort". As such, we need this data for a properly functioning Grype. Since we need this data, Grype is an open source project, and it would be beneficial to cooperate. Creating an open source project seemed like the best option.
 
+ ### Can Anchore actually pull this off?
+ No, we can't. We need help. Open source is one of the most amazing ways to solve problems the world has ever seen. We know we can't do this alone, please come help. Also tell all your friends.
+
 ### What happens if NVD goes back to normal?
-In the event NVD returns, or some other project takes over the current task of NVD, we expect to continue to maintain this project. Not every vulnerability database supports every ecosystem, so being able to enrich vulnerability data makes sense.
+In the event NVD returns, or some other project takes over the current task of NVD, we expect to continue to maintain this project. Not every vulnerability database supports every ecosystem, so being able to enrich vulnerability data makes sense. But the need to enrich everything would be diminished greatly. This project is meant to be downstream of something like NVD, we will defer to their data when possible.
 
 For example there could be vulnerability data about a binary they build, but if that binary is also downloaded from the project directly, that information may not be tracked anywhere else.