Annotations File

You can specify an annotation JSON file with the --annotations parameter of the export-report command.

Annotations are a way to specify some comments that will end on the final CVE report, allowing to comment unfixed CVEs. This may be useful to document why this CVE is not fixed and how it does affect the final product. In addition, it allows to whitelist CVEs, if they do not make sense in the context of the target product.

There are two ways of providing annotations for CVEs :

  1. by using the web interface, or
  2. by manually editing them in an JSON file.

Whatever the method used, the annotations will be stored in an JSON file with the following grammar:

ANNOTATION-FILE     ::= { "version": "2.0.0",
                          ("scopes": SCOPES)?,
                          "annotations": LIST-OF-ANNOTATIONS }
SCOPES              ::= { ("transversals": LIST-OF-TRANSVERSALS)?,
                          ("projects": LIST-OF-PROJECTS)? }
LIST-OF-TRANSVERSALS::= [ TRANSVERSAL (, TRANSVERSAL)* ]
TRANSVERSAL         ::= string
LIST-OF-PROJECTS    ::= [ PROJECT (, PROJECT)* ]
PROJECT             ::= { "name": PROJECT-NAME,
                          ("components": LIST-OF-COMPONENTS)? }
PROJECT-NAME        ::= string
LIST-OF-COMPONENTS  ::= [ COMPONENT (, COMPONENT)* ]
COMPONENT           ::= string
LIST-OF-ANNOTATIONS ::= [ ANNOTATION (, ANNOTATION)* ]
ANNOTATION          ::= { "vulnerability_name": VULNERABILITY-NAME,
                          ("scope": SCOPE,)?
                          "last_status": STATUS,
                          "last_vulnerable": BOOLEAN,
                          "logs": LIST-OF-LOGS }
VULNERABILITY-NAME  ::= string
SCOPE               ::= string
LIST-OF-LOGS        ::= [ LOG (, LOG)* ]
LOG                 ::= { "timestamp": TIMESTAMP,
                          "status_change": STATUS-CHANGE
                          "vulnerable_change": BOOLEAN
                          "comment": COMMENT }
TIMESTAMP           ::= string
STATUS-CHANGE       ::= { "from": STATUS,
                          "to": STATUS }
STATUS              ::= "patched" | 
                        "false positive" | 
                        "not exploitable" |
                        "accepted" |
                        "ongoing" |
                        "pending" |
                        "todo" |
                        "exploitable" 
COMMENT             ::= string
BOOLEAN             ::= true | false
((A)* meaning zero or more occurrences of A, (A)? meaning zero or one occurence of A, and A | B meaning A or B)

Where:

  • TRANSVERSAL, PROJECT-NAME, COMPONENT are scope names (see Scopes for details),
  • ANNOTATION gathers the analysis elements for a given vulnerability :
  • VULNERABILITY-NAME: is a vulnerability unique name (typically a CVE identifier),
  • SCOPE is a scope specifier (see Scopes for details),
  • last_status is the current status of the vulnerability,
  • last_status records whether the vulnerability is considered exploitable or not,
  • LIST-OF-LOGS records the history of status changes on this vulnerability:
    • LOG is a log entry for a vulnerability, recording a change of status (through the status_change entry) and whether through this change the vulnerability is considered exploitable of not (through the vulnerable_change entry),
    • TIMESTAMP is a ISO 8601 timestamp for the log entry (formatted as YYYY-MM-DDThh:mm:ss.sssZ),

Example: 

{ "version": "2.0.0",
  "scopes": {
        "transversals": [ "arm","intel" ],
        "projects": [
            { "name": "p1",
              "components": [ "c1","c2" ] },
            { "name": "p2" }
        ]
    },
  "annotations": [
     {
          "vulnerability_name": "CVE-2024-1234",
          "scope": "*",
          "last_status": "on going",
          "last_vulnerable": true,
          "logs": [
              {
                  "timestamp": "2024-07-29T16:29:04.844Z",
                  "status_change": {
                      "from": "undefined",
                      "to": "on going"
                  },
                  "vulnerable_change": true,
                  "comment": "Ongoing analysis"
              }
          ]
      },
      {
          "vulnerability_name": "CVE-2021-5678",
          "scope": "/p1/c2",
          "last_status": "false positive",
          "last_vulnerable": false,
          "logs": [
              {
                  "timestamp": "2024-07-29T16:28:08.346Z",
                  "status_change": {
                      "from": "undefined",
                      "to": "false positive"
                  },
                  "vulnerable_change": false,
                  "comment": "This CVE is not relevant because ..."
              }
          ]
      }
  ]
}