Human readable format

[Kurt Seifried]

So after spending two decades reading CVE descriptions, I'd like to propose the following:

1) We support line returns (\n)

2) We support markdown formatting in the text description, notes and other large text fields meant for human consumption

CVE as you may or may not know strips line returns from data submitted (you can see in this commit for example: https://github.com/CVEProject/cvelist/commit/3a5c3c750474806777a0ebb5f10d871fc16fd33b#diff-85d12d6ac7fa63abd0832b1ffe2edf0bd393fd620488d66001e5d4759daa096e)

 

and of course, there is no support for formatting. I'd like to suggest markdown formatting for two simple reasons: it's simple and most people know it and people can drop HTML directly in if needed, but it makes treating the text field safely a bit easier. The other advantage of line returns and markdown is even if a human has to look at the raw JSON it's still reasonably readable. Any strong objections/concerns/thoughts? Please let me know.

Kurt Seifried (He/Him) Chief Blockchain Officer and Director of Special Projects Cloud Security Alliance e: ksei...@cloudsecurityalliance.org

[Josh Bressers]

On Tue, Jan 4, 2022 at 2:38 PM 'Kurt Seifried' via GSD Discussion Group <g...@groups.cloudsecurityalliance.org> wrote:

So after spending two decades reading CVE descriptions, I'd like to propose the following:

1) We support line returns (\n)

2) We support markdown formatting in the text description, notes and other large text fields meant for human consumption

CVE as you may or may not know strips line returns from data submitted (you can see in this commit for example: https://github.com/CVEProject/cvelist/commit/3a5c3c750474806777a0ebb5f10d871fc16fd33b#diff-85d12d6ac7fa63abd0832b1ffe2edf0bd393fd620488d66001e5d4759daa096e)

 

and of course, there is no support for formatting. I'd like to suggest markdown formatting for two simple reasons: it's simple and most people know it and people can drop HTML directly in if needed, but it makes treating the text field safely a bit easier. The other advantage of line returns and markdown is even if a human has to look at the raw JSON it's still reasonably readable. Any strong objections/concerns/thoughts? Please let me know.

Using markdown for any human generated content makes sense.

I do think for the "official" description of a vulnerability we should make it a goal (a long term goal) to contain enough metadata about the identifier that a description can be machine generated. Human prose is very hard to parse which leads to a lot of annoying problems.

-- 

     Josh

 

[Kurt Seifried]

It occurs to me that we should maybe have more than one. E.g.:

{
  "description": {
    "generated_short": "$VENDOR $PRODUCT $VERSION is vulnerable to a $VULNTYPE occuring in $COMPONENT resulting in $OUTCOME.",
    "generated_long": "# Description \n\n $VENDOR $PRODUCT $VERSION is vulnerable to a $VULNTYPE occuring in $COMPONENT resuklting in $OUTCOME. \n\n # Workaround \n\n $WORKAROUND DATA \n\n # Exploits \n\n $EXPLOIT_DATA \n\n etc etc...",
    "manual": "All the above or whatever and someone writes some really beautiful text here, eg the generated long format plus more prose and a haiku or whatever"
  }
}

In most cases, with a well-formed request, you have enough data to create the sentence (it's how I did all the DWF CVEs back in the day). With additional data, you can have additional sections like workarounds, exploit code, etc. I think there should always be a place for manual prose, rather than trying to bash the machine formatted data to fit, or add something in a weird way (e.g. "use the notes field but label it at the top as an example of indicators of compromise in cat meme format"). But I think we should strive for automation first, but allow manual shenanigans. 

 

-- 

     Josh