Description
Right now advisories are TOML documents with large amounts of Markdown crammed into the description field. Here are a couple examples:
This is suboptimal for a couple reasons:
- Anyone editing Markdown crammed into the
descriptionfield 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
descriptionfield 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.
...