Skip to content

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

Closed
@tarcieri

Description

@tarcieri

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 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.

...

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions