From 5e61d9caceaa8cdc513880f43aa724a571f251d6 Mon Sep 17 00:00:00 2001 From: Jonathan Moroney Date: Tue, 5 Dec 2023 14:10:45 -0800 Subject: [PATCH 1/7] Add affected attribute format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/README.md b/README.md index 25ec9290c..a20de2add 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,34 @@ 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 to that attribute to the OSV payload. Eg. +``` +{ + attribute: "ImageFont", + modules: ["PIL"] +} +``` +which is equivalent to `PIL:ImageFont`. If a second attribute `ImageFont2` is also affected then a second payload should be added and delimited with a `;`. Eg. +``` +{ + 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), From d46cc8883e924590e394cd71da6df203f92319bc Mon Sep 17 00:00:00 2001 From: Jon Date: Tue, 5 Dec 2023 15:19:56 -0800 Subject: [PATCH 2/7] Update README.md Add json syntax for the markdown codeblock Co-authored-by: William Woodruff --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a20de2add..922762ccf 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ generate the `.yaml` entries here. ### 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 to that attribute to the OSV payload. Eg. -``` +```json { attribute: "ImageFont", modules: ["PIL"] From 3fc7e40eaf5ff6555caf09b6edb84305bb8d30dd Mon Sep 17 00:00:00 2001 From: Jon Date: Tue, 5 Dec 2023 15:20:07 -0800 Subject: [PATCH 3/7] Update README.md Add json syntax Co-authored-by: William Woodruff --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 922762ccf..d2b420bc5 100644 --- a/README.md +++ b/README.md @@ -30,8 +30,8 @@ generate the `.yaml` entries here. 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 to that attribute to the OSV payload. Eg. ```json { - attribute: "ImageFont", - modules: ["PIL"] + "attribute": "ImageFont", + "modules": ["PIL"] } ``` which is equivalent to `PIL:ImageFont`. If a second attribute `ImageFont2` is also affected then a second payload should be added and delimited with a `;`. Eg. From f46a500e23986b17d42837ba8954b18e3f4f428f Mon Sep 17 00:00:00 2001 From: Jonathan Moroney Date: Wed, 6 Dec 2023 11:48:00 -0800 Subject: [PATCH 4/7] Add note about starting at top level module just to be explicit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d2b420bc5..4d32614ea 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ 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 to that attribute to the OSV payload. Eg. +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. ```json { "attribute": "ImageFont", From 9898260b6d69a5d3b937d86ad1f59c09dbe32556 Mon Sep 17 00:00:00 2001 From: Jonathan Moroney Date: Tue, 12 Dec 2023 15:35:20 -0800 Subject: [PATCH 5/7] change the ImageFont/ImageFont2 example based on feedback and make json examples a little more explicit --- README.md | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 4d32614ea..d508c7c65 100644 --- a/README.md +++ b/README.md @@ -27,21 +27,34 @@ 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. +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 -{ - "attribute": "ImageFont", - "modules": ["PIL"] +"ecosystem_specific": { + "imports": [ + { + "attribute": string, + "modules": [ string ], + } + ] } ``` -which is equivalent to `PIL:ImageFont`. If a second attribute `ImageFont2` is also affected then a second payload should be added and delimited with a `;`. Eg. +"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"] + } +] ``` -{ - attribute: "ImageFont", - modules: ["PIL"]; - attribute: "ImageFont2", - modules: ["PIL"] -} +which is equivalent to `PIL:ImageFont`. If a second attribute `ImageFont2` is also affected then a second payload should be added and delimited with a `;`. Eg. +```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) From 8761c1b7d62ea4d577a45eb161bc3621a17a3761 Mon Sep 17 00:00:00 2001 From: Jon Date: Wed, 13 Dec 2023 09:36:31 -0800 Subject: [PATCH 6/7] Update README.md Co-authored-by: Oliver Chang --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d508c7c65..63a3adc72 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ For example, a vulnerability that affects PIL::ImageFont can be represented as.. } ] ``` -which is equivalent to `PIL:ImageFont`. If a second attribute `ImageFont2` is also affected then a second payload should be added and delimited with a `;`. Eg. +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"] }, From cbd0503d20ca62918c1d757f7d7fe3857a2695c1 Mon Sep 17 00:00:00 2001 From: Jon Date: Wed, 13 Dec 2023 09:36:48 -0800 Subject: [PATCH 7/7] Update README.md Co-authored-by: Oliver Chang --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 63a3adc72..a2aa4f13c 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ which is equivalent to `PIL:ImageFont`. If a second attribute `ImageFont2` is al ] ``` -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) +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 ```