Add EXAMPLE_ADVISORY.md (#436)

Adds an example advisory in the V3 format (#414) and updates the schema
information in README.md to reflect that.

EXAMPLE_ADVISORY.md

@@ -0,0 +1,41 @@
+```toml
+[advisory]
+id = "RUSTSEC-0000-0000"
+package = "crate-name"
+date = "2020-01-31"
+url = "https://example.com"
+categories = ["code-execution", "privilege-escalation"]
+keywords = ["example", "freeform", "keywords"]
+#aliases = ["CVE-YYYY-NNNN"]
+#cvss = "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H"
+
+[versions]
+patched = [">= 1.2.3"]
+unaffected = ["0.1.2"]
+
+[affected]
+#arch = ["x86"]
+#os = ["windows"]
+functions = { "crate_name::MyStruct::vulnerable_fn" = ["< 1.2.3"] }
+```
+
+# RustSec Advisory Template - Advisory Title Goes Here
+
+This is an example template for a RustSec advisory. Please copy this to
+`crates/<crate-name>` and rename it to `RUSTSEC-0000-0000.md`.
+
+In this section of the advisory you can write an extended description
+of the vulnerability, will be converted into HTML and rendered at
+<https://rustsec.org>.
+
+- Markdown formatted
+- TOML "front matter". See `README.md` for schema.
+- Please include as much detail as you'd like.
+
+A well structured advisory will include information like:
+
+Affected versions of this crate did not properly X.
+
+This allows an attacker to Y.
+
+The flaw was corrected by Z.

README.md

@@ -24,7 +24,10 @@ See [CONTRIBUTING.md] for more information.
 
 ## Advisory Format
 
-Each advisory contains information in [TOML] format:
+See [EXAMPLE_ADVISORY.md] for a template.
+
+Advisories are formatted in [Markdown] with [TOML] "front matter".
+Below is the scehma of the "front matter" section of an advisory:
 
 ```toml
 # Before you submit a PR using this template, **please delete the comments**
@@ -41,9 +44,6 @@ package = "mycrate"
 # Disclosure date of the advisory as an RFC 3339 date (mandatory)
 date = "2019-10-01"
 
-# Single-line description of a vulnerability (mandatory)
-title = "Flaw in X allows Y"
-
 # URL to a long-form description of this issue, e.g. a GitHub issue/PR,
 # a change log entry, or a blogpost announcing the release (optional)
 url = "https://github.com/mystuff/mycrate/issues/123"
@@ -68,15 +68,6 @@ keywords = ["ssl", "mitm"]
 # e.g. CVE for a C library wrapped by a -sys crate)
 #references = ["CVE-2018-YYYY", "CVE-2018-ZZZZ"]
 
-# Enter a short-form description of the vulnerability here (mandatory)
-description = """
-Affected versions of this crate did not properly X.
-
-This allows an attacker to Y.
- 
-The flaw was corrected by Z.
-"""
-
 # Optional: metadata which narrows the scope of what this advisory affects
 [affected]
 # CPU architectures impacted by this vulnerability (optional).
@@ -124,6 +115,8 @@ All content in this repository is placed in the public domain.
 
 [//]: # (general links)
 
+[EXAMPLE_ADVISORY.md]: https://github.com/RustSec/advisory-db/blob/master/EXAMPLE_ADVISORY.md
+[Markdown]: https://www.markdownguide.org/
 [TOML]: https://github.com/toml-lang/toml
 [cargo-audit]: https://github.com/rustsec/cargo-audit
 [cargo-deny]: https://github.com/EmbarkStudios/cargo-deny