API proposal

[lulf]

Happy path examples!

GET /package?purl={:purl} Response:

{
    "ref": "https://.../package/?purl={:purl}",
    "relatedVersions": [
      "1.2.3"
    ],
    "vulnerabilities": [
      ...
    ],
    "snyk": ...
}

GET /package/dependencies?purl={:purl} Response:

[
  {
    "purl": "foo-3.2.1",
    "ref": "https://.../package?purl=foo-3.2.1"
  }
]

GET /package/dependants?purl={:purl} Response:

[
  {
    "purl": "foo-3.2.1",
    "ref": "https://.../package?purl=foo-3.2.1"
  }
]

GET /vulnerability/{:cveid} Response:

[
  {
    "purl": "foo-3.2.1",
    "ref": "https://.../package?purl=foo-3.2.1"
  }
]

POST /analyze/sbom Input: CycloneDX or SPDX (autodetected) Response:

{
  "advisories": [
    "https://access.redhat.com/security/data/csaf/v2/advisories/2023/rhsa-2022_7401.json"
  ],
  "vulnerabilities": [
    "https://..../vulnerability/123",
    "https://..../vulnerability/124"
  ],
  "dependencies": [
    "https://.../package?purl=foo-3.2.1",
    "https://.../package?purl=bar-3.2.1"
  ]
}

[bobmcwhirter]

For /analyze/sbom perhaps mixing vulns and deps, so we know where a vuln in brought in?

"vulnerabilities": {
  "pkg:some:purl": [ ], // not affected
  "pkg:other:purl": [
        "https://.../vuln/123",
        "https://.../vuln/2344",
    ]
}

[lulf]

Updated version, now with JSON body payload as a way to pass arrays of purls if needed. Also mixed vuln and deps:

GET /package?purl=pkg:maven/org.quarkus/quarkus@1.2 Response:

[
  {
    "trustedVersions": [
      "pkg:maven/org.quarkus/quarkus@1.2-redhat-007"
    ],
    "vulnerabilities": [
      ...
    ],
    "snyk": ...
  }
]

POST /package Request:

[
  "pkg:maven/org.quarkus/quarkus@1.2"
]

Response:

[
  {
    "trustedVersions": [
      "pkg:maven/org.quarkus/quarkus@1.2-redhat-007"
    ],
    "vulnerabilities": [
      ...
    ],
    "snyk": ...
  }
]

POST /package/dependencies Request:

[
  "pkg:maven/org.quarkus/quarkus@1.2"
]

Response:

[
  {
    "purl": "pkg:maven/org.jboss.logging/jboss-logging-annotations@2.2.1.Final",
    "ref": "https://..../package?purl=pkg:maven/org.jboss.logging/jboss-logging-annotations@2.2.1.Final"
  }
]

GET /package/dependants Request:

[
  "pkg:maven/org.jboss.logging/jboss-logging-annotations@2.2.1.Final"
]

Response:

[
  {
    "purl": "pkg:maven/org.quarkus/quarkus@1.2",
    "ref": "https://..../package?purl=pkg:maven/org.quarkus/quarkus@1.2"
  }
]

GET /vulnerability/{:cveid} Response:

[
  {
    "purl": "foo-3.2.1",
    "ref": "https://.../package?purl=foo-3.2.1"
  }
]

POST /analyze/sbom Input: CycloneDX or SPDX (autodetected) Response:

{
  "advisories": [
    "https://access.redhat.com/security/data/csaf/v2/advisories/2023/rhsa-2022_7401.json"
  ],
  "vulnerabilities": [
    {
      "purl": "https://.../package?purl=foo-3.2.1",
      "vulnerabilities": [
        "https://..../vulnerability/123",
        "https://..../vulnerability/124"
      ]
    },
    {
      "purl": "https://.../package?purl=bar-3.2.1",
      "vulnerabilities": [
      ]
    }
  ]
}

[bobmcwhirter]

Looking good. CRDA is definitely concerned about being able to batch all that is possible.

Also, though, not sure if any of our Java vuln information will be at all different from what we can get from Snyk. We should at least report the Snyk stuff, even if our own Java VEX is thin or non-existant.

Should the purl fields be actual pURLs, though? And have additional hrefs for links within the API or to the HTML console? e.g., treat the purl field as a bonafide primary-key identifier so that the submitter can coallate what they submitted with what we returned?

[dejanb]

I added support to look up packages in guac. At the moment the logic will look both "trusted" packages from a static file and all other versions of the package in guac.

curl --json '["pkg:maven/io.quarkus/quarkus-vertx@2.13.7.Final"]' http://localhost:8081/api/package | jq
[
  {
    "purl": "pkg:maven/io.quarkus/quarkus-vertx@2.13.7.Final",
    "href": "/api/package?purl=pkg%3Amaven%2Fio.quarkus%2Fquarkus-vertx%402.13.7.Final",
    "trustedVersions": [
      {
        "purl": "pkg:maven/io.quarkus/quarkus-vertx@2.16.2.Final",
        "href": "/api/package?purl=pkg%3Amaven%2Fio.quarkus%2Fquarkus-vertx%402.16.2.Final"
      },
      {
        "purl": "pkg:maven/io.quarkus/quarkus-vertx@2.13.7.Final-redhat-00003",
        "href": "/api/package?purl=pkg%3Amaven%2Fio.quarkus%2Fquarkus-vertx%402.13.7.Final-redhat-00003"
      }
    ]
  }
]

I'll try to insert all trusted gavs into guac, so we can do a single lookup.

I'm still not sure how we are going to differentiate "trusted" from all other "related" packages yet. Maybe just a simple logic to mark @version-redhat-* as trusted for now will work? Should we return other packages as well under trustedVersions? Or should we add relatedVersions? Should it be a different API call for related packages? Or will the UI figure all this out?

[bobmcwhirter]

That looks pretty flippin' nice. Thanks!