Provide explanation by knowledge database

If we would provide an internal knowledge database we could provide an alternative for #476 which would be a product neutral. way to provide #474

The knowledge database would provide as a first step the explanation of a CWE and we would use this internally to obtain details.

Disadvantages:

we must provide, adopt, handle the information and maintain the kb

Advantages:

would be part of SecHub Open Source
not product specific
maintainable
open
future ready

How could we use it then inside sechub/sereco

we would store those information NOT inside other product results, but ONLY at sereco report output!!!!!
so at least sereco must have access to the kb (by simply sending a message and obtaining result - so we would not use https rest SERVICE here.)

Request format

We could provide a request format in JSON style - e.g.:

{
   "outputFormat" : "html",

   "request" : [
       "cwe" : [
           {
                  "id": "CWE-ID-XYZ1"
           },
           {
                  "id": "CWE-ID-XYZ2"
           }
       ]

   ]
}

So this would be very open and clear to read. If we provide something other than CWE ids, we could simply add this as another field - easy to extend.

Output format

HTML

Hmm.. HTML output ... maybe a little bit odd? HTML sechub report generation could do this itself in a more suitable way? So JSON output should be preferred way and HTML maybe only a second choice in future?

JSON

We should provide provide a good readable json document structure and provide the content in asciidoc format. reason for asciidoc : plain text, but we can integrate code examples etc. as well - and it becomes an industrial standard.

{
   "results" : [
          { 
              "type" : "cwe",
              "id": "CWE-ID-XYZ1",
              "explanation" : "explaintation description in asciidoc format - can contain codesnippets as well"
              "mitigation" : "mitigation description is asciidoc - can contain code snippets etc. as well",
          }
   ]
}

Additional ways for interaction

Also we could use this format for ADMIN rest api call - and maybe if this comes to an option at a public KB service REST. We would provide this same request data structure as used for internal messaging.

^{Albert Tregnaghi albert.tregnaghi@daimler.com, Daimler TSS GmbH, imprint}

mercedes-benz / sechub