Add affected attribute format (#175)

* Add affected attribute format Following up on #149 it seems like we have general agreement on what this format should be, so I've gone ahead and kicked off the PR 🎉 I took a liberty in how to deliniate two attributes (with a `;`). Happy to change that if there's disagreement on how to delimit multiple different attributes on the same osv payload. The osv payload is explicitly called out as equivalent to the dot-colon single line format as well. I also added a brief section linking to the osv schema. * Update README.md Add json syntax for the markdown codeblock Co-authored-by: William Woodruff <[email protected]> * Update README.md Add json syntax Co-authored-by: William Woodruff <[email protected]> * Add note about starting at top level module just to be explicit * change the ImageFont/ImageFont2 example based on feedback and make json examples a little more explicit * Update README.md Co-authored-by: Oliver Chang <[email protected]> * Update README.md Co-authored-by: Oliver Chang <[email protected]> --------- Co-authored-by: William Woodruff <[email protected]> Co-authored-by: Oliver Chang <[email protected]>
pypa · Dec 14, 2023 · e2bf537 · e2bf537
1 parent 2e4fd73
commit e2bf537
Showing 1 changed file with 41 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -26,6 +26,47 @@ generate the `.yaml` entries here.
 
 ## Using this data
 
+### Marking specific attributes
+It can be helpful to know which specific code elements of a package are vulnerable and this is done by appending an attribute and list of module paths starting from the top level module of a package to the OSV payload. Eg. 
+OSV entries in this database have the following ecosystem_specific definition: 
+```json
+"ecosystem_specific": {
+  "imports": [
+    { 
+       "attribute": string,
+       "modules": [ string ],
+    }
+  ]
+}
+```
+"imports" is a JSON array containing the modules and attributes affected by the vulnerability...
+For example, a vulnerability that affects PIL::ImageFont can be represented as...
+```json
+"imports": [
+  {
+    "attribute": "ImageFont",
+    "modules": ["PIL"]
+  }
+]
+```
+which is equivalent to `PIL:ImageFont`. If a second attribute `ImageFont2` is also affected, then a second import entry needs to be added to the `imports` array. 
+```json
+"imports": [
+  { "attribute": "ImageFont", "modules": ["PIL"] },
+  { "attribute": "ImageFont2", "modules": ["PIL"] }
+]
+```
+
+Attributes which are accessible via multiple paths may be represented in a condensed form. Consider the attribute `django.db.models:JSONField` from the [django project](https://github.com/django/django/blob/0ee2b8c326d47387bacb713a3ab369fa9a7a22ee/django/db/models/__init__.py#L99) 
+The attribute `django.db.models:JSONField` is a re-export of `django.db.models.fields.json:JSONField` and both are valid paths.
+These can be condensed to a more compact OSV representation as 
+```
+{
+  attribute: "JSONField",
+  modules: ["django.db.models", "django.db.models.fields.json"]
+}
+```
+
 ### Tooling
 
 This data is exposed by [`pip-audit`](https://github.com/pypa/pip-audit),