Add last_affected event type. (#38)

* Add `last_affected` event type. Part of #35. * Update docs/schema.md Co-authored-by: Chris Bloom <[email protected]> * JSON validation Co-authored-by: Chris Bloom <[email protected]>
ossf · Mar 24, 2022 · ef3f219 · ef3f219
1 parent 5e3cbf8
commit ef3f219
Show file tree

Hide file tree

Showing 2 changed files with 46 additions and 4 deletions.
diff --git a/docs/schema.md b/docs/schema.md
@@ -81,6 +81,7 @@ A JSON Schema for validation is also available
 			"events": [ {
 				"introduced": string,
 				"fixed": string,
+				"last_affected": string,
 				"limit": string
 			} ]
 		} ],
@@ -443,7 +444,8 @@ The `ranges` object's `events` field is a JSON array of objects. Each object
 describes a single version that either:
 1. Introduces a vulnerability: `{"introduced": string}`
 2. Fixes a vulnerability: `{"fixed": string}`
-3. Sets an upper limit on the range being described: `{"limit": string}`
+3. Describes the last known affected version: `{"last_affected": string}`
+4. Sets an upper limit on the range being described: `{"limit": string}`
 
 These `events` objects represent a "timeline" of status changes for the affected
 package.
@@ -461,9 +463,14 @@ by the `affected[].ranges[].type` field.
 
 #### Requirements
 
-Only **a single type** (either `"introduced"`, `"fixed"`, `"limit"`) is allowed in
-each event object. For instance, `{"introduced": "1.0.0", "fixed": "1.0.2"}` is
-**invalid**.
+Only **a single type** (either `"introduced"`, `"fixed"`, `"last_affected"`,
+`"limit"`) is allowed in each event object. For instance,
+`{"introduced": "1.0.0", "fixed": "1.0.2"}` is **invalid**.
+
+Entries in the `events` array can contain either `"last_affected"` or `"fixed"`
+events, but not both. It's **strongly recommended** to use `"fixed"` instead of
+`"last_affected"` where possible, as it precisely identifies the version which
+contains the fix.
 
 There must be at least one `"introduced"` object in the `events` array. While
 not required, it's also recommended to keep the `events` array sorted according
@@ -545,6 +552,8 @@ func IncludedInRanges(v, ranges)
            vulnerable = true
         else if evt.fixed is present && v >= evt.fixed
            vulnerable = false
+        else if evt.last_affected is present && v > evt.last_affected
+           vulnerable = false
 
   return vulnerable
 

diff --git a/validation/schema.json b/validation/schema.json
@@ -132,6 +132,17 @@
                           "fixed"
                         ]
                       },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "last_affected": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "last_affected"
+                        ]
+                      },
                       {
                         "type": "object",
                         "properties": {
@@ -162,6 +173,28 @@
                       "repo"
                     ]
                   }
+                },
+                {
+                  "if": {
+                    "properties": {
+                      "events": {
+                        "contains": {
+                          "required": ["last_affected"]
+                        }
+                      }
+                    }
+                  },
+                  "then": {
+                    "not": {
+                      "properties": {
+                        "events": {
+                          "contains": {
+                            "required": ["fixed"]
+                          }
+                        }
+                      }
+                    }
+                  }
                 }
               ],
               "required": [