Merge branch 'update-osv-scanner-documentation'

1 files changed, 38 insertions, 13 deletions

diff --git a/osv-scanner.toml b/osv-scanner.toml
index 1837415f42..b87ae7ea2f 100644
--- a/osv-scanner.toml
+++ b/osv-scanner.toml
@@ -1,20 +1,32 @@
 # List of ignored known vulnerabilities
 #
-# A vulnerability should only be ignored if it cannot be upgraded to a fixed version, or if
-# upgrading it has significant other downsides.
+# When osv-scanner reports a vulnerability, evaluate if the vulnerability affects the security
+# of our app. If it does, escalate the issue and discuss in the team and with tech leadership.
+# If the vulnerability does *not* affect the security of the app, there are three ways to fix it.
+# Here they are listed in priority order:
 #
-# Every ignored vulnerability entry must have an `ignoreUntil`.
-# * It is not allowed to ignore a vulnerability indefinitely.
+# 1. Try to upgrade the dependency to a version that does not have the vulnerability.
+#    If possible and does not come with too many other downsides, this is always recommended.
+# 2. If upgrading is not feasible and the vulnerability does not affect the security of our app,
+#    it can be ignored with an `IgnoredVulns` entry. See below for rules.
+# 3. If one package has very many vulnerabilities or a constant stream of new vulnerabilities
+#    found, and they are never a threat to our app's security, the entire package can be ignored
+#    with a `PackageOverrides` entry. See below for rules. This should be avoided if feasible.
+#
+# Every ignored vulnerability/package entry must have an end date. It is not allowed to ignore
+# vulnerabilies indefinitely. This means specifying an `ignoreUntil` for `IgnoredVulns` entries
+# and `effectiveUntil` for `PackageOverrides` entries.
 # * The default should be to ignore a vulnerability for three months.
 # * A vulnerability can be ignored for up to a year at most (Use extremely sparsely).
 # * If anything above three months is used, write a short comment about why this ignore is longer.
 #
-# Try to use the "original" identifier as `id`. This means the identifier used by the original
-# vulnerability database it originates from. These are usually listed as "Aliases" on osv.dev.
-# Feel free to add more identifiers as comments after the `id`.
+# Every entry must have a `reason` field that explains why this vulnerability does not affect us,
+# and why we can't/decided not to change to an unaffected version.
 #
-# In the `reason` field explain why this vulnerability does not affect us,
-# and why we can't change to an unaffected version.
+# Try to use the "original" identifier as `id` in `IgnoredVulns`. This means the identifier used
+# by the original vulnerability database it originates from.
+# These are usually listed as "Aliases" on osv.dev.
+# Feel free to add more identifiers as comments after the `id`.
 #
 # Write a comment above each entry specifying what dependency it is about and what type of
 # vulnerability it is. The other fields do not convey this.
@@ -22,13 +34,13 @@
 # Remove the ignore as soon as we upgrade or otherwise get rid of the vulnerable dependency from
 # our product.
 #
-# When an `ignoreUntil` expire and start yielding errors on a previously ignored issue, follow
-# these steps:
+# When an `ignoreUntil`/`effectiveUntil` expire and start yielding errors on a previously ignored
+# issue, follow these steps:
 # 1. Try to upgrade away from the vulnerable versions and get rid of the ignore.
 # 2. Update any outdated info in this ignore.
 # 3. Bump the `ignoreUntil` following the same rules as when initially adding an ignore entry.
-
-# Example entry:
+#
+# Example `IgnoredVulns` entry:
 #
 # ```
 # # libbaz remote code execution in get_date() function
@@ -40,3 +52,16 @@
 # `renderer-helper` currently depend on this version of libbaz, preventing us from upgrading to a fixed version.
 # """
 # ```
+#
+# Example `PackageOverrides` entry:
+#
+# ```
+# # Entire package ignored since there is a constant stream of newly found regular expression attacks.
+# # All of these attacks rely on the input being malicious. We only use this package in our trusted
+# # build environment with trusted inputs.
+# [[PackageOverrides]]
+# name = "rexml"
+# ignore = true
+# effectiveUntil = 2024-11-02
+# reason = "The XML payload is generated by Apple tooling which we trust"
+# ```