<!--
**Note:** When your KEP is complete, all of these comment blocks should be removed.

To get started with this template:

- [ ] **Pick a hosting SIG.**
  Make sure that the problem space is something the SIG is interested in taking
  up. KEPs should not be checked in without a sponsoring SIG.
- [ ] **Create an issue in kubernetes/enhancements**
  When filing an enhancement tracking issue, please make sure to complete all
  fields in that template. One of the fields asks for a link to the KEP. You
  can leave that blank until this KEP is filed, and then go back to the
  enhancement and add the link.
- [ ] **Make a copy of this template directory.**
  Copy this template into the owning SIG's directory and name it
  `NNNN-short-descriptive-title`, where `NNNN` is the issue number (with no
  leading-zero padding) assigned to your enhancement above.
- [ ] **Fill out as much of the kep.yaml file as you can.**
  At minimum, you should fill in the "Title", "Authors", "Owning-sig",
  "Status", and date-related fields.
- [ ] **Fill out this file as best you can.**
  At minimum, you should fill in the "Summary" and "Motivation" sections.
  These should be easy if you've preflighted the idea of the KEP with the
  appropriate SIG(s).
- [ ] **Create a PR for this KEP.**
  Assign it to people in the SIG who are sponsoring this process.
- [ ] **Merge early and iterate.**
  Avoid getting hung up on specific details and instead aim to get the goals of
  the KEP clarified and merged quickly. The best way to do this is to just
  start with the high-level sections and fill out details incrementally in
  subsequent PRs.

Just because a KEP is merged does not mean it is complete or approved. Any KEP
marked as `provisional` is a working document and subject to change. You can
denote sections that are under active debate as follows:

```
<<[UNRESOLVED optional short context or usernames ]>>
Stuff that is being argued.
<<[/UNRESOLVED]>>
```

When editing KEPS, aim for tightly-scoped, single-topic PRs to keep discussions
focused. If you disagree with what is already in a document, open a new PR
with suggested changes.

One KEP corresponds to one "feature" or "enhancement" for its whole lifecycle.
You do not need a new KEP to move from beta to GA, for example. If
new details emerge that belong in the KEP, edit the KEP. Once a feature has become
"implemented", major changes should get new KEPs.

The canonical place for the latest set of instructions (and the likely source
of this file) is [here](/keps/NNNN-kep-template/README.md).

**Note:** Any PRs to move a KEP to `implementable`, or significant changes once
it is marked `implementable`, must be approved by each of the KEP approvers.
If none of those approvers are still appropriate, then changes to that list
should be approved by the remaining approvers and/or the owning SIG (or
SIG Architecture for cross-cutting KEPs).
-->

# KEP-3203: Auto-Refreshing Official CVE Feed

<!--
This is the title of your KEP. Keep it short, simple, and descriptive. A good
title can help communicate what the KEP is and should be considered as part of
any review.
-->

<!--
A table of contents is helpful for quickly jumping to sections of a KEP and for
highlighting any additional information provided beyond the standard KEP
template.

Ensure the TOC is wrapped with
  <code>&lt;!-- toc --&rt;&lt;!-- /toc --&rt;</code>
tags, and then generate with `hack/update-toc.sh`.
-->

<!-- toc -->
- [Release Signoff Checklist](#release-signoff-checklist)
- [Summary](#summary)
- [Motivation](#motivation)
  - [Goals](#goals)
  - [Non-Goals](#non-goals)
  - [User Stories (Optional)](#user-stories-optional)
    - [Story 1](#story-1)
    - [Story 2](#story-2)
    - [Story 3](#story-3)
  - [Story 4](#story-4)
- [Proposal](#proposal)
  - [Pre-requisites](#pre-requisites)
  - [Overview](#overview)
  - [Risks and Mitigations](#risks-and-mitigations)
    - [JSON blob construction will fail](#json-blob-construction-will-fail)
    - [Misuse of Auto-Refresh feature](#misuse-of-auto-refresh-feature)
    - [Large JSON blob could lead to slower read/write and resource consumption](#large-json-blob-could-lead-to-slower-readwrite-and-resource-consumption)
- [Design Details](#design-details)
  - [Test Plan](#test-plan)
  - [Graduation Criteria](#graduation-criteria)
    - [Alpha](#alpha)
    - [Beta](#beta)
  - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
  - [Version Skew Strategy](#version-skew-strategy)
- [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire)
- [Implementation History](#implementation-history)
- [Drawbacks](#drawbacks)
- [Alternatives](#alternatives)
  - [Storage of CVE feed blob](#storage-of-cve-feed-blob)
    - [1. <strong>Only use Google Cloud Bucket</strong>](#1-only-use-google-cloud-bucket)
    - [2. <strong>Only use Git Repository</strong>](#2-only-use-git-repository)
- [Infrastructure Needed (Optional)](#infrastructure-needed-optional)
<!-- /toc -->

## Release Signoff Checklist

<!--
**ACTION REQUIRED:** In order to merge code into a release, there must be an
issue in [kubernetes/enhancements] referencing this KEP and targeting a release
milestone **before the [Enhancement Freeze](https://git.k8s.io/sig-release/releases)
of the targeted release**.

For enhancements that make changes to code or processes/procedures in core
Kubernetes—i.e., [kubernetes/kubernetes], we require the following Release
Signoff checklist to be completed.

Check these off as they are completed for the Release Team to track. These
checklist items _must_ be updated for the enhancement to be released.
-->

Items marked with (R) are required *prior to targeting to a milestone / release*
.

- [ ] (R) Enhancement issue in release milestone, which links to KEP dir
  in [kubernetes/enhancements] (not the initial KEP PR)
- [ ] (R) KEP approvers have approved the KEP status as `implementable`
- [ ] (R) Design details are appropriately documented
- [ ] (R) Test plan is in place, giving consideration to SIG Architecture and
  SIG Testing input (including test refactors)
  - [ ] e2e Tests for all Beta API Operations (endpoints)
  - [ ] (R) Ensure GA e2e tests for meet requirements
    for [Conformance Tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/conformance-tests.md)
  - [ ] (R) Minimum Two Week Window for GA e2e tests to prove flake free
- [ ] (R) Graduation criteria is in place
  - [ ] (
    R) [all GA Endpoints](https://github.com/kubernetes/community/pull/1806)
    must be hit
    by [Conformance Tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/conformance-tests.md)
- [ ] (R) Production readiness review completed
- [ ] (R) Production readiness review approved
- [ ] "Implementation History" section is up-to-date for milestone
- [ ] User-facing documentation has been created in [kubernetes/website], for
  publication to [kubernetes.io]
- [ ] Supporting documentation—e.g., additional design documents, links to
  mailing list discussions/SIG meetings, relevant PRs/issues, release notes

<!--
**Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone.
-->

[kubernetes.io]: https://kubernetes.io/

[kubernetes/enhancements]: https://git.k8s.io/enhancements

[kubernetes/kubernetes]: https://git.k8s.io/kubernetes

[kubernetes/website]: https://git.k8s.io/website

## Summary

Currently it is not possible to filter for issues or PRs that are related to
CVEs announced by kubernetes. This KEP addresses this concern by labeling these
issues or PRs with the new label **official-cve-feed** using the automation. The
in-scope issues are the closed issues for which there is a CVE ID and is
officially announced as a Kubernetes CVE by SRC in the past.

## Motivation

With the growing number of eyes on Kubernetes, the number of CVEs related to
Kubernetes have increased. Although most CVEs that directly, indirectly, or
transitively impact Kubernetes are regularly fixed, there is no single place
for the end users of Kubernetes to programmatically subscribe or pull the data
of fixed CVEs. Current options are either
[broken or incomplete](https://github.com/kubernetes/sig-security/issues/1).

An auto-refreshing CVE feed will allow end users to programmatically fetch the
list of CVEs and allow them to get the latest information from Kubernetes
community.

### Goals

Create a periodically auto-refreshing, machine-readable list of official
Kubernetes CVEs

### Non-Goals

- Triage and vulnerability disclosure: This will continue to be done by SRC
- Listing CVEs that are identified in build time dependencies and container
  images. Only official CVEs announced by the Kubernetes SRC will be published
  in the feed.
- Integration with [CVEProject](https://github.com/CVEProject/cvelist) may
  happen at a future stage but currently is not planned or scoped.

### User Stories (Optional)

#### Story 1

As a K8s end user, I want a list of CVEs with relevant information that I can
fetch programmatically, so I can track when new CVEs are announced.

#### Story 2

As a K8s End User, I want to use my browser to get a list of fixed CVEs, from
the official K8s website so that I can trust it as an authoritative source of
data through implicit trust offered by website certificate and domain name.

#### Story 3

As a K8s maintainer, I want to create a process that auto-updates CVE feed, when
SRC announces new CVEs such that I do not have to do extra work to maintain this
feed manually

### Story 4

As a K8s platform provider, I want to automatically know if my Kubernetes 
clusters are vulnerable to any of the CVEs SRC have announced. I want to have a
programmatically available API to parse this kind of data so I can easily
provide it to users of my platform.

## Proposal

### Pre-requisites

- [x] Add official-cve-label https://github.com/kubernetes/test-infra/pull/23428
- [x] Search and Identify closed issues that have a CVE ID e.g. CVE-1001-12345
  in the issue description or summary (This
  search [filter](https://github.com/kubernetes/kubernetes/issues?q=is%3Aissue+in%3Abody+%22CVSS%3A3.%22+label%3Acommittee%2Fsecurity-response+is%3Aclosed+)
  is giving the most accurate data so far)
- [x] Label those issues with `official-cve-feed`
  using https://docs.github.com/en/rest/reference/issues REST API
- [x] Add `official-cve-feed` label as part of SRC
  playbook: https://github.com/kubernetes/committee-security-response/pull/133

### Overview

- Generate a JSON blob using the results from the filtered label on `k/k`
  repo.
- Create a Prow job to periodically generate this JSON blob.
- Push this JSON blob when needed (e.g. when a new CVE is announced) to GCS (
  Google Cloud Bucket)
- Using Hugo and other tooling (such as Netlify), publish the list from this
  JSON blob on official k8s website during `k/website` build
- Generate an RSS feed (atom format) with hugo templates using the generated
  JSON blob

### Risks and Mitigations

#### JSON blob construction will fail

If the generation of the JSON blob listing known CVEs were to fail, downstream
jobs also fail. If blob construction fails, the failure will alert the owners of
this feature and we will take action as needed. If the failure can not be fixed
in a reasonable amount of time, the CVE feed will be stale until it is fixed. In
case of an urgent need from the community to update the vulnerabilities feed,
JSON blob will be manually updated via `gsutil` command.

#### Misuse of Auto-Refresh feature

Without proper filtering and control over who can label GitHub issues, the list
of CVEs can become a list with poor signal-to-noise ratio making the list
unusable.

For this purpose, the filtering is applied such that only issues that are marked
as `closed`
will be part of the list. Also, additionally, the `official-cve-feed` label is a
[restricted](https://github.com/kubernetes/test-infra/blob/master/config/prow/plugins.yaml#L140-L150)
label that can only be applied by SRC and SIG Security Tooling Leads.

#### Large JSON blob could lead to slower read/write and resource consumption

Blobs will only be rewritten, if the generated blob is different from existing
blob. As hash file would be created and stored alongside generated blob. This
hash file will be check everytime before push to the hash of the generated file.
If the hash file matches writing to the bucket will be skipped, if hash file is
different writing to bucket, will be triggered.

## Design Details

The steps to implement this design will involve a prow job that:

1. Queries Github API for fixed official CVEs
1. Generates a JSON blob based on the query results
1. Writes the JSON blob to gcs-bucket if it is different than existing blob
1. Triggers the `k/website` build using netlify
   [build-hook](https://docs.netlify.com/configure-builds/build-hooks/). Secret
   token to trigger build is added as External Secret. See example for
   [snyk-token](https://github.com/kubernetes/k8s.io/pull/2222/files)
1. `k/website` build pulls the JSON blob from gcs bucket during website rebuild,
   pulling it from gcs-bucket into something like
   `https://kubernetes.io/security/official-cve-feed.json`
1. `k/website` renders the JSON blob as an HTML table for viewing the list of
   fixed CVEs from a browser at this location:
   `https://kubernetes.io/docs/reference/issues-security/official-cve-feed`
   and linked from this
   page: `https://kubernetes.io/docs/reference/issues-security/security/`

*Notes*:

- A GCS bucket needs to be created. Example PR for this looks
  like [this](https://github.com/kubernetes/k8s.io/pull/2570/files)
- Additional custom fields need to be added to make JSON feed compliant with 
  https://validator.jsonfeed.org/ 

### Test Plan

<!--
<!--
**Note:** *Not required until targeted at a release.*
The goal is to ensure that we don't accept enhancements with inadequate testing.

All code is expected to have adequate tests (eventually with coverage
expectations). Please adhere to the [Kubernetes testing guidelines][testing-guidelines]
when drafting this test plan.

[testing-guidelines]: https://git.k8s.io/community/contributors/devel/sig-testing/testing.md
-->

This is a process KEP implemented using periodic prow job. This KEP is not implemented for any functional use cases of kubernetes. So no e2e/unit/integration tests are applicable and going forward test plan will mostly include the scenarios around monitoring of the prow job for any failures as and when needed. 

### Graduation Criteria

#### Alpha

- Feature implemented with working JSON feed and tabular list
- Initial e2e testing completed and alerting setup for detecting failures

#### Beta

- Gather feedback from developers and end users
- Make JSON feed compliant with `jsonfeed` spec
- Add `RSS` feed for the CVE list
- Add fields that signal freshness of the data

<!--
**Note:** *Not required until targeted at a release.*

Define graduation milestones.

These may be defined in terms of API maturity, or as something else. The KEP
should keep this high-level with a focus on what signals will be looked at to
determine graduation.

Consider the following in developing the graduation criteria for this enhancement:
- [Maturity levels (`alpha`, `beta`, `stable`)][maturity-levels]
- [Deprecation policy][deprecation-policy]

Clearly define what graduation means by either linking to the [API doc
definition](https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning)
or by redefining what graduation means.

In general we try to use the same stages (alpha, beta, GA), regardless of how the
functionality is accessed.

[maturity-levels]: https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions
[deprecation-policy]: https://kubernetes.io/docs/reference/using-api/deprecation-policy/

Below are some examples to consider, in addition to the aforementioned [maturity levels][maturity-levels].

#### Alpha

- Feature implemented behind a feature flag
- Initial e2e tests completed and enabled

#### Beta

- Gather feedback from developers and surveys
- Complete features A, B, C
- Additional tests are in Testgrid and linked in KEP

#### GA

- N examples of real-world usage
- N installs
- More rigorous forms of testing—e.g., downgrade tests and scalability tests
- Allowing time for feedback

**Note:** Generally we also wait at least two releases between beta and
GA/stable, because there's no opportunity for user feedback, or even bug reports,
in back-to-back releases.

**For non-optional features moving to GA, the graduation criteria must include
[conformance tests].**

[conformance tests]: https://git.k8s.io/community/contributors/devel/sig-architecture/conformance-tests.md

#### Deprecation

- Announce deprecation and support policy of the existing flag
- Two versions passed since introducing the functionality that deprecates the flag (to address version skew)
- Address feedback on usage/changed behavior, provided on GitHub issues
- Deprecate the flag
-->

### Upgrade / Downgrade Strategy

Not applicable

### Version Skew Strategy

Not applicable

## Production Readiness Review Questionnaire

Not applicable as per this
[comment](https://github.com/kubernetes/enhancements/pull/3204#issuecomment-1042367862)

<!--

Production readiness reviews are intended to ensure that features merging into
Kubernetes are observable, scalable and supportable; can be safely operated in
production environments, and can be disabled or rolled back in the event they
cause increased failures in production. See more in the PRR KEP at
https://git.k8s.io/enhancements/keps/sig-architecture/1194-prod-readiness.

The production readiness review questionnaire must be completed and approved
for the KEP to move to `implementable` status and be included in the release.

In some cases, the questions below should also have answers in `kep.yaml`. This
is to enable automation to verify the presence of the review, and to reduce review
burden and latency.

The KEP must have a approver from the
[`prod-readiness-approvers`](http://git.k8s.io/enhancements/OWNERS_ALIASES)
team. Please reach out on the
[#prod-readiness](https://kubernetes.slack.com/archives/CPNHUMN74) channel if
you need any help or guidance.
-->

## Implementation History

<!--
Major milestones in the lifecycle of a KEP should be tracked in this section.
Major milestones might include:
- the `Summary` and `Motivation` sections being merged, signaling SIG acceptance
- the `Proposal` section being merged, signaling agreement on a proposed design
- the date implementation started
- the first Kubernetes release where an initial version of the KEP was available
- the version of Kubernetes where the KEP graduated to general availability
- when the KEP was retired or superseded
-->

## Drawbacks

<!--
Why should this KEP _not_ be implemented?
-->

## Alternatives

### Storage of CVE feed blob

There are two options to store the CVE feed JSON blob:

#### 1. __Only use Google Cloud Bucket__

A new Google cloud bucket can be created where the CVE feed is written using
 `gsutil` tool and read via `curl` call.

  * Advantages: 
      * Transparent updates to JSON blob where the prow job run will be identical everytime. 
      * Access control for writing to bucket is least privilege i.e. managed 
      via a service account and Google group membership 
  * Disadvantages:
      * CVE list has an unofficial looking URL which would be hard for an 
      end user to decipher for its authenticity and provenance.

#### 2. __Only use Git Repository__

Store it as a version controlled artifact in one of the `kubernetes` 
GitHub Org repositories.

  * Advantages:
      * When a Git Repository especially `k/website` hosts the JSON blob the domain
      name in the URL would be `k8s.io/static/security/official-cve-feed.json` 
      which is much more recognizable, intuitive in terms of trust, TLS enabled 
      and unlikely to be spoofed. But there are several disadvantages:

  * Disadvantages:
      * This might get delayed by PR review and approval process. However, this 
      can be prevented through use of `skip-review` label.
      * A fork would need to be maintained under a Github Robot for `k/website` or 
      `k/sig-security` which will add overhead for GitHub Admins who manage the 
      robot accounts and its forks.

In summary, because both the approaches have pros and cons, the finalized approach
combined the good parts from both the alternatives by storing the blob in Google
Cloud bucket but rendering it via `kubernetes/website` GitHub Repository. 

## Infrastructure Needed (Optional)

A GCS bucket to store JSON blob is needed, with its corresponding service account.
