Suggestion for new vulnerability report format

Motivation

The current state of a report is not fully normalized which makes it hard to parse it as machine readable format. Moreover, the report has mixed formatting, for example: a newline indicated by \n and code emphasis indicated by markdown as ``

Recommended format

Title

The weakness description of the vulnerability. Always a clear-text string, no formatting allowed.

Overview

Markdown parsable text

Author

Name would be a full name, username is as set in the hackerone report, and website as a social reference for the user (will be taken from the hackerone platform).

Author field will consist of an object with the following fields:

author: {
  name: "",
  username: "",
  website: ""
}

Dates

• created_at: should be specified as ISO 8601 YYYY-MM-DD
• updated_at: should be specified as ISO 8601 YYYY-MM-DD
• publish_date: should be specified as ISO 8601 YYYY-MM-DD

References

Instead of a string, this should be an array of strings:

references: [
  "https://hackerone.com/...",
  "https://github.com/..."
]

Slug

Probably refers to the nodejs, or nsp blog where the vulnerability was disclosed. Recommending to remove this entry.

Recommendation

I’m wondering if we can have some status enum thing here, where the path is easily understood such as either you should upgrade, or drop it completely due to no fix available. Something like:

recommendation: "UPGRADE|DROP|any other status we can have?"

If not this, then we should have a formatted string that follows a standard, such as:

• for upgrading: “It is recommended to upgrade to a newer version”
• for dropping support: “At the time of the report, there is no available upgrade path” They aren’t the final suggestions, just to convey the point. Not sure that the module name or version should even be in them since that information is already available through other fields in the vulnerability report.

Existing format for reference:

{
  "id": 399,
  "title": "Command Injection - Generic",
  "overview": "`whereis` concatenates unsanitized input into exec() command",
  "created_at": "2018-02-25",
  "updated_at": "2018-03-28",
  "publish_date": "2018-03-28",
  "author": "Сковорода Никита Андреевич (https://github.com/ChALkeR)",
  "module_name": "whereis",
  "cves": [
    ""
  ],
  "vulnerable_versions": "<=0.4.0",
  "patched_versions": ">=0.4.1",
  "slug": "whereis-command-injection---generic",
  "recommendation": "use npm package `which` instead",
  "references": "- https://hackerone.com/reports/319476\n- https://github.com/vvo/node-whereis/commit/0f64e3780235004fb6e43bfd153ea3e0e210ee2b",
  "cvss_vector": "CVSS:3.0/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H",
  "cvss_score": 9.9,
  "coordinating_vendor": ""
}

Status

• title: limit to 100 chars (set to 150 in #227), no markdown (this probably needs to be added to the validator)
• date format: ISO 8601 (#226)
• published at field: added (#216 )
• remove slug field (#225)
• author: an object with name, username and website (#314)
• references (#316)
• overview: parsable markdown
• format of vulnerable versions

A reference to the proposed changes:

{
  "id": 399,
  "title": "Command Injection - Generic",
  "overview": "`whereis` concatenates unsanitized input into `exec()` command",
  "created_at": "2018-02-25",
  "updated_at": "2018-03-28",
  "publish_date": "2018-03-28",
  "author": {
    "name": "Сковорода Никита Андреевич",
    "username": "ChALkeR",
    "website": "https://github.com/ChALkeR"
  },
  "module_name": "whereis",
  "cves": [
  ],
  "vulnerable_versions": "<=0.4.0",
  "patched_versions": ">=0.4.1",
  "recommendation": "DROP: the package and use npm package `which` instead",
  "references": [
    "https://hackerone.com/reports/319476",
    "https://github.com/vvo/node-whereis/commit/0f64e3780235004fb6e43bfd153ea3e0e210ee2b"
  ],
  "cvss_vector": "CVSS:3.0/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H",
  "cvss_score": 9.9,
  "coordinating_vendor": ""
}

Relates to https://github.com/nodejs/security-wg/issues/115

[pxlpnk]

I have time to work on this and move it forward. I try to do it in the following order:

• author
• overview
• references
• vulnerable versions

and will propose individual PRs for this.

[pxlpnk]

I think https://github.com/nodejs/security-wg/issues/171 can be closed in favour of this PR.

The changes proposed until now (checked are merged already):

• title: limit to 100 chars (set to 150 in #227), no markdown (this probably needs to be added to the validator)
• date format: ISO 8601 (#226)
• published at field: added (#216 )
• remove slug field (#225)
• author: an object with name, username and website
• overview: parsable markdown
• format of vulnerable versions
• references

I took the liberty updated the reference provided in the issue with the proposed and applied changes:

{
  "id": 399,
  "title": "Command Injection - Generic",
  "overview": "`whereis` concatenates unsanitized input into `exec()` command",
  "created_at": "2018-02-25",
  "updated_at": "2018-03-28",
  "publish_date": "2018-03-28",
  "author": {
    "name": "Сковорода Никита Андреевич",
    "username": "ChALkeR",
    "website": "https://github.com/ChALkeR"
  },
  "module_name": "whereis",
  "cves": [
  ],
  "vulnerable_versions": "<=0.4.0",
  "patched_versions": ">=0.4.1",
  "recommendation": "DROP: the package and use npm package `which` instead",
  "references": [
    "https://hackerone.com/reports/319476",
    "https://github.com/vvo/node-whereis/commit/0f64e3780235004fb6e43bfd153ea3e0e210ee2b"
  ],
  "cvss_vector": "CVSS:3.0/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H",
  "cvss_score": 9.9,
  "coordinating_vendor": ""
}

Overall those changes make all sense to me and would make working with the npm now and in the future way easier.

What needs some final discussion imoh:

• the format of vulnerable versions: https://github.com/nodejs/security-wg/issues/200#issuecomment-381431012 and https://github.com/nodejs/security-wg/issues/200#issuecomment-381251003 have some good ideas.
• overview: do we need character limit here? Should we ensure the text can be parsed as markdown?
• author: the proposed changes make sense, but I would not tie it too much to h1 or any other platform

After working through the PRs I think this should not be too much work, and I would like to spend some time on this. WDYT?