From feb16fc4f9e74ad6a99b2db8134260f4625e68e4 Mon Sep 17 00:00:00 2001 From: Mahe Tardy Date: Fri, 14 Mar 2025 17:09:57 +0100 Subject: [PATCH] Add documentation for the official CVE feed Signed-off-by: Mahe Tardy --- sig-security-tooling/cve-feed/README.md | 48 +++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 sig-security-tooling/cve-feed/README.md diff --git a/sig-security-tooling/cve-feed/README.md b/sig-security-tooling/cve-feed/README.md new file mode 100644 index 0000000..9321475 --- /dev/null +++ b/sig-security-tooling/cve-feed/README.md @@ -0,0 +1,48 @@ +# Official CVE Feed + +The official CVE feed is separated into two main components: +1. The scripts, that update a cloud bucket containing the feed. +2. The website, rendering and serving the feed in various formats. + +## Scripts + +A script in the [kubernetes/sig-security](https://github.com/kubernetes/sig-security) +repository under the [sig-security-tooling/cve-feed/hack](https://github.com/kubernetes/sig-security/tree/main/sig-security-tooling/cve-feed/hack) +folder. This script is +a bash script named `fetch-cve-feed.sh` that: +- sets up the python3 environment; +- generates the CVE feed file with `fetch-official-cve-feed.py`; +- compares the sha256 of the newly generated file with the existing one; +- if the sha256 changed, uploads the newly generated CVE feed file to the bucket. + +The `fetch-official-cve-feed.py` file executed by the `fetch-cve-feed.sh` is a +python3 script that: +- queries the GitHub API to fetch all the issues with the `official-cve-feed` + label in the [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/issues?q=is%3Aissue%20label%3Aofficial-cve-feed%20) + repository; +- formats the result with the appropriate JSON schema to be JSON feed + compliant; +- prints the output to stdout. + +These scripts are run regularly as a CronJob on the k8s infrastructure. + +In short, these scripts take the GitHub [kubernetes/kubernetes issues +labeled with `official-cve-feed`](https://github.com/kubernetes/kubernetes/issues?q=is%3Aissue%20label%3Aofficial-cve-feed%20) +as the input and generate a JSON feed file as an output in a cloud bucket. The +output can be publicly fetched at [gs://k8s-cve-feed/](https://console.cloud.google.com/storage/browser/k8s-cve-feed) or [storage.googleapis.com/k8s-cve-feed](https://storage.googleapis.com/k8s-cve-feed/). + +## Website + +The main output of the official CVE feed is the HTML website page available on +[k8s.io/docs/reference/issues-security/official-cve-feed](https://kubernetes.io/docs/reference/issues-security/official-cve-feed/) +where you can also find links to the JSON and RSS feed formats. + +The corresponding HTML page is generated from the [official-cve-feed.md](https://github.com/kubernetes/website/blob/main/content/en/docs/reference/issues-security/official-cve-feed.md?plain=1) +file from the [kubernetes/website](https://github.com/kubernetes/website) +repository. It mainly calls the `cve-feed` shortcode that is defined in +[website/layouts/shortcodes/cve-feed.html](https://github.com/kubernetes/website/blob/main/layouts/shortcodes/cve-feed.html) +which consumes the JSON format by fetching the URL from the +[`.Site.Params.cveFeedBucket`](https://github.com/kubernetes/website/blob/75f19fc9675d07fdbc724d02953d905ef7ca8619/hugo.toml#L168) +and translating it to an HTML table. + +This page is thus updated every time the website is built.