chore: comments in vulnerability-allowlist.yml and info in README.md

README.md

@@ -96,3 +96,35 @@ be pushed to a `test` subfolder of the
 
 You can force dynamic CI pipeline jobs to run by setting `FORCE_DYNAMIC_JOBS` when running the
 pipeline.
+
+### Adding known vulnerabilities to allowlist file
+
+This project has **container-scanning** job enabled for all images. As a result, this project has detailed
+[Vulnerability report](https://gitlab.developers.cam.ac.uk/uis/devops/infra/dockerimages/-/security/vulnerability_report)
+with information about all detected vulnerabilities. Periodically, the Cloud Team triage those findings and some of
+them could be count as false positive or known issues. To exclude such issues from the final report, the issues must be
+added to the `vulnerability-allowlist.yml` file in the root of this project. The syntax is described in
+[GitLab docs](https://docs.gitlab.com/ee/user/application_security/container_scanning/#vulnerability-allowlisting).
+
+```yaml
+generalallowlist:
+  # https://gitlab.developers.cam.ac.uk/uis/devops/infra/dockerimages/-/issues/80
+  CVE-2023-6879: libaom
+images:
+  registry.gitlab.developers.cam.ac.uk/uis/devops/infra/dockerimages/ucam-mellon-proxy:
+    # https://gitlab.developers.cam.ac.uk/uis/devops/infra/dockerimages/-/issues/81
+    CVE-2023-45853: zlib1g
+```
+
+On the example above:
+
+* CVE-2023-6879: allowed for every image where it is detected in `libaom` package;
+* CVE-2023-6879: allowed for image `registry.gitlab.developers.cam.ac.uk/uis/devops/infra/dockerimages/ucam-mellon-proxy`,
+  `zlib1g` package;
+
+The GitLab issue reference must be added as a comment.
+
+This file is also being used for "container-scanning" job in
+[CI Templates](https://gitlab.developers.cam.ac.uk/uis/devops/continuous-delivery/ci-templates) project.
+The job downloads latest version of this file and use it as a source of information about allowed
+vulnerabilities. Project's own `vulnerability-allowlist.yml` file has priority over the one in this repository.

vulnerability-allowlist.yml

 generalallowlist:
+  # https://gitlab.developers.cam.ac.uk/uis/devops/infra/dockerimages/-/issues/80
   CVE-2023-6879: libaom
 images:
   registry.gitlab.developers.cam.ac.uk/uis/devops/infra/dockerimages/ucam-mellon-proxy:
+    # https://gitlab.developers.cam.ac.uk/uis/devops/infra/dockerimages/-/issues/81
     CVE-2023-45853: zlib1g