Standard for VEX document discovery

[micahhausler]

As a vendor who would want to publish VEX documents for a certain artifact and enable consumers (end users, security scanners, etc) to know where to find a document for that artifact, there is currently no standard discovery mechanism. This is similar to #9, but distinct in that I'm imagining a pull model rather than a push.

There are several other similar standards we can look to for this:

• RPM ecosystem has a repos file on disk, the mirror contains a repodata/repomd.xml, which points to a repodata/updateinfo.xml file containing CVE/errata information for all packages for all time. Its easy to imagine a file like /etc/vex/vex-provider.json containing a URL (or base URL) which appends a /.well-known/openvex path or similar.
• OpenID Connect (OIDC) embeds an "iss" issuer URL in JWT token claims, that relying parties append a /.well-known/openid-configuration path to discover metadata. Artifact types like OCI images that support key/value string metadata could include a well-known key (say, openvex.dev/discovery) that could have a value of a VEX discovery URI.

In addition to having a discovery mechanism, we'll need some format for the associating a discovery document with a particular artifact. To my knowledge, RPM's repodata/updateinfo.xml never is never rotated and grows over time. Rather than having to devise additional metadata formats (such as a big list of VEX URLs) for discovery under a well-known URI and forcing clients to make subsequent requests, for OpenVEX, I could see the need to also embed alongside discovery information some unique identifier for the artifact, maybe just a UUID4.

For argument's sake, imagine the following keys either in a config file or key/value annotations.

{
  "openvex.dev/discovery": "https://alas.aws.amazon.com/alas2023/",
  "openvex.dev/identifier": "931e5e35-2351-4278-9dc4-d45621d4f3c1",
  "openvex.dev/version": "v0.2.0"
}

Such that tooling could infer the vex document for an artifact is available at
https://alas.aws.amazon.com/alas2023/.well-known/openvex/931e5e35-2351-4278-9dc4-d45621d4f3c1 and is built with the v0.2.0 version of the spec.

[puerco]

I love it @micahhausler.

Regarding the format, one of the goals we want with OpenVEX is that once you discover one document, the format itself can provide links to the rest of the relevant statements using its linked data capabilities.

One of the features we're thinking of adding to OpenVEX is support for references to link to other documents. One of the use cases this will unlock is to have "empty" OpenVEX documents - that is docs without any VEX statements - that only reference other documents. For example (this is just an idea no proposal exists yet for this):

{
  "@context": "https://openvex.dev/ns/v0.2.0",
  "@id": "https://openvex.dev/docs/example/vex-9fb3463de1b57",
  "links": [
      {"ref": "https://myurl.com/index.openvex.json"},
   ]
}

Using that schema, you can reference another document with relevant statements, but also you could point to an OpenVEX API endpoint or a continuously appended document (like an index) with links to known documents. For example:

{
  "@context": "https://openvex.dev/ns/v0.2.0",
  "@id": "https://myurl.com/index.openvex.json",
  "links": [
      {"ref": "https://myurl.com/document1.openvex.json"},
      {"ref": "https://myurl.com/document2.openvex.json"},
      {"ref": "https://myurl.com/document3.openvex.json"},
   ]
}

It would be awesome to fast forward this, the .well-known URL could respond with these documents.

[akcrisp]

surely this would be fixed if you implemented the request on issue 34 - media type - discovery of vex artifacts then becomes straightforward using tools like oras