Add link for pip-audit & example input variant

Author: ArBridgeman

doc/design.rst

@@ -196,14 +196,68 @@ _________________
 security-issues
 ^^^^^^^^^^^^^^^
 The `security-issues/action.yml` creates GitHub Issues for known vulnerabilities
-for `maven` and `pip-audit`.
+for `maven` and `pip-audit <https://pypi.org/project/pip-audit/>`_.
 The following steps are taken:
 
 1. Convert a JSON of known vulnerabilities into a common format (`class Issue`)
 2. Filter out vulnerabilities which already have an existing GitHub Issue via CVE
 3. Create new GitHub Issues
 4. Return a JSON of the newly created GitHub Issues
 
+Input variants
+~~~~~~~~~~~~~~
+An input variant would be passed in as a string-encoded JSON.
+
+`maven` (via `mvn --batch-mode org.sonatype.ossindex.maven:ossindex-maven-plugin:audit org.sonatype.ossindex.maven:ossindex-maven-plugin:audit-aggregate`)
+
+.. code-block:: json
+
+        {
+            "vulnerable": {
+                "<package_name>@<package_version>:compile": {
+                    "coordinates": "<package_name>@<package_version>",
+                    "description": "<package_description>",
+                    "reference": "<oss_url_for_vuln>",
+                    "vulnerabilities": [
+                        {
+                            "id": "<vuln_id>",
+                            "displayName": "<vuln_name>",
+                            "title": "<vuln_title>",
+                            "description": "<vuln_description>",
+                            "cvssScore": 7.5,
+                            "cvssVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
+                            "cwe": "<cwe_vuln_id>",
+                            "cve": "<cve_vuln_id>",
+                            "reference": "<oss_url_for_vuln>",
+                            "externalReferences": ["<vuln_reference_url>"],
+                        }
+                    ],
+                },
+            }
+        }
+
+`pip-audit` (via `nox -s dependency:audit`)
+
+.. code-block:: json
+
+   {
+        "dependencies": [
+            {
+                "name": "<package_name>",
+                "version": "<package_version>",
+                "vulns":
+                [
+                    {
+                        "id": "<vuln_id>",
+                        "fix_versions": ["<fix_version>"],
+                        "aliases": ["<vuln_id2>"],
+                        "description": "<vuln_description>"
+                    }
+                ]
+            }
+        ]
+    }
+
 Known Issues
 ~~~~~~~~~~~~~
 The `security-issues/action.yml` assumes that eventually every known vulnerability will
@@ -216,9 +270,9 @@ be associated with a singular CVE.
 * Additionally, reporting tools like `pip-audit` must link a vulnerability with the
   different vulnerability IDs from different reporting services. Typically, this is done
   by selecting 1 of the vulnerability IDs as the unique identifier of the vulnerability.
-  This, as is the case for `pip-audit`, is not the CVE, so it is possible if the linked
-  vulnerability IDs were to change (i.e. wrongly linked CVE) that we could end up with
-  multiple GitHub Issues for the same underlying vulnerability.
+  This, as is the case for `pip-audit`, may not be the CVE, so it is possible if the
+  linked vulnerability IDs were to change (i.e. wrongly linked CVE) that we could end
+  up with multiple GitHub Issues for the same underlying vulnerability.
 
 
 Known Issues