Proposed "V3" advisory format: move to Markdown + (TOML) "front matter"

[tarcieri]

Right now advisories are TOML documents with large amounts of Markdown crammed into the description field. Here are a couple examples:

• RUSTSEC-2019-0023
• CVE-2019-16760

This is suboptimal for a couple reasons:

• Anyone editing Markdown crammed into the description field can't take advantage of their editor's Markdown syntax highlighting or preview features
• Likewise the Markdown is not rendered when viewing advisories on GitHub, which is useful in the PR process to ensure Markdown is well-formatted, but also for anyone browsing the advisory DB's git repo on GitHub
• It makes advisory metadata located below the description field harder to see. As of the move to the new V2 advisory format, this is all version information, which is some of the most important information in advisories.

This issue proposes what is hopefully the last change to the advisory format before freezing it and releasing 1.0 versions of cargo-audit and the rustsec crate: moving to a Markdown advisory format.

Markdown (unofficially) supports the notion of "front matter": typically a YAML document embedded at the beginning of a Markdown file like so:

---
id: CVE-2019-16760
package: cargo
date: 2019-09-30
...
---

The Rust team was recently notified of a security concern when using older
versions of Cargo to build crates which use the package rename feature added in
newer versions of Cargo. If you're using Rust 1.26.0, released on 2018-05-10,
or later you're not affected.

...

This proposal is to migrate advisories from .toml files to .md files which leverage Markdown "front matter" to store advisory metadata.

If this happens, it may make sense to switch the advisory format from TOML to YAML as this is better supported in the Markdown ecosystem (e.g. GitHub will apply syntax highlighting and/or render it as a table).

However, that doesn't necessarily have to be the case: we could also continue to use TOML front matter, which enjoys some support:

---
[advisory]
id = "CVE-2019-16760"
package = "cargo"
date = "2019-09-30"
...
---

The Rust team was recently notified of a security concern when using older
versions of Cargo to build crates which use the package rename feature added in
newer versions of Cargo. If you're using Rust 1.26.0, released on 2018-05-10,
or later you're not affected.

...

[8573]

Besides the migration diff being greater, what disadvantages do you see in using YAML for the metadata?

[tarcieri]

YAML is a more loosely structured format, but has better support for this particular purpose

[tarcieri]

Opened a draft PR with a new proposed V3 advisory format.

https://github.com/RustSec/rustsec-crate/pull/167

Edit: merged

[tarcieri]

Support for the new format implemented in the PR above shipped in rustsec crate v0.19.0, which was released in May 2020. cargo-audit v0.12 was also released in May 2020 and supports the format.

I would suggest attempting to switch over to the new format on October 1st, 2020 (next Thursday).

[tarcieri]

We'll attempt a migration today. The migration is tracked in #414.