Improved documentation around custom templating

[AbhigyanKumarTrellix]

As of now the only real information that is given in readme around custom output templates is the CSV template example. Anyone trying to create / add a column to their report is basically at the mercy of god. For eg, trying to figure out the "Name" for "dataSource" is bad.
Please add at least a list /table indicating all the possible mappings /words that can be used as a header for custom templates.

Why is this needed:
A better user experience and easier custom templating
Additional context:

[gh-greg]

((trying to create / add a column to their report is basically at the mercy of god.)): AKumar, I agree.
I tried to submit a PR for the "Readme.md" , on this topic.

[kzantow]

It's possible expanded templating documentation could live in its own readme (e.g. TEMPLATES.md or something similar). However, it should be noted that any templating is going to be informed by the structure of the object model, which can be seen in the JSON returned by grype -o json, which is potentially going to be changing over time so such documentation would need to be kept up to date.

[gh-greg]

OUTPUT_TEMPLATES.md : Templating is informed by the structure of the object model, which can be seen in the JSON returned by grype -o json. As the object model changes over time, this document must be kept up to date with the actual grype runtime.The one notable difference between the JSON output and the Go templates ? The variable names are camel-case in the Go templates. As an example: JSON Structure: vulnerability: { datastore Go Template: {{.Vulnerability.DataSource}} ... Let me see, if I can find the Template Documentation, I wrote some time back in that PR ...

[AbhigyanKumarTrellix]

HI @gh-greg and @kzantow thanks for that. I did go through the section mentioned in current README.
Please note as someone new to Go, I DON'T SEE any obvious way the "json" components maps with "reference" term in the template for example, considering "dataSource", the json refers it to as:
"vulnerability": { "id": "CVE-2022-SOMEDATA", "dataSource": "https://SOME-DATA-Source", }
So, I have tried "Vulnerability.dataSource" and so on, none of those "work"
This whole thing would have been MUCH easier if just pasted how this mapping is happening.
If, anyone can, my current goal is to just get a html template with the source as one of the columns.

[kzantow]

@AbhigyanKumarTrellix -- the one notable difference I left out between the JSON output and the Go templates: the variable names are all uppercase in the Go templates. So DataSource would be what you want. Are you just trying to get this in a CSV output?

If so, this might get what you're looking for:

"Package","Version Installed","Vulnerability ID","Severity","Data Source"
{{- range .Matches}}
"{{.Artifact.Name}}","{{.Artifact.Version}}","{{.Vulnerability.ID}}","{{.Vulnerability.Severity}}","{{.Vulnerability.DataSource}}"
{{- end}}

(EDIT: I just read you're looking for HTML, I suspect you could adapt this above to HTML?)

[tgerla]

Since this issue was filed we have improved the documentation around Grype templates and published some examples in the templates directory (https://github.com/anchore/grype/tree/main/templates) -- I'll close this issue but please feel free to open another one if you have any more specific suggestions or requests. Thanks!