TrivySummary

TrivySummary summarises Trivy scan JSON output for reporting purposes. Package vulnerabilities are collapsed down to the respective CVE, and headline counts of vulnerabilities at different priorities. As well as the vendor severity and CVSS v3 score provided by Trivy, EPSS scores can also be retrieved, allowing the exploitability and severity of all vulnerabilities to be graphed and prioritised.

The tool has a number of options to aid reporting.

• It can take a single Trivy scan JSON file and summarise it to PDF or to JSON
• It can take two Trivy scan JSON files for the same logical component, taken at different points in time and compare them, again summarising to PDF or JSON

It also can aid CI/CD pipelines by exiting with an error if there are open vulnerabilities at a given priority or above (e.g. fail if at least one CRITICAL or HIGH vulnerability has been found).

Usage

Requires Java Runtime Environment 17 or higher. Run application from the bin folder (on Windows, use trivysummary.bat not trivysummary).

To summarise a single Trivy JSON file, use the form:

trivysummary <trivyScanOutput>.json <args>

To summarise and compare two Trivy JSON files for the same component, use the form:

trivysummary <previousTrivyOutput>.json <latestTrivyOutput>.json <args>

For scan dates, this application relies on the createdAt property added by later versions of Trivy (since v0.48.0).

Arguments

  --help
    Displays this help message

  --title=...
    Sets a report title. If unset, a default title is used containing
    the input file path(s) provided

  --outputFile=...
    The required output file name. If the filename ends in .pdf then the
    output is a PDF report. If not, a JSON format is used. Defaults to
    "trivysummary.pdf" in the current working directory.
    Please note that the --bothPDFAndJSONOutput argument can be used to 
    output both PDF _and_ JSON

  --bothPDFAndJSONOutput
    If set, both PDF and JSON output will be created, using the --outputFile
    argument and intelligently amending the suffix. Saves time if you need
    both output forms.

  --failPriorityThreshold=...
    The priority threshold at or above which any open vulnerabilities
    will cause this app to return an error (returns 1, rather than 0).
    Must be one of LOW, MEDIUM, HIGH or CRITICAL.
    If unset, an error won't be returned for any set minimum priority.

  --whitelist=...
    If set, one or more files in JSON format listing CVEs which should be
    whitelisted in the output. You can specify this argument multiple times
    if you wish to load multiple whitelists

  --treatmentPlan=...
    If set, the JSON format treatment plan so that progress can be reported
    and tracked. Only one treatment plan may be specified.

  --offline
    If set, TrivySummary will not attempt to access EPSS scores to assess
    the exploitability of CVEs. This will bypass graphing and prioritisation
    but is useful if using this tool from airgapped environments.

  --priorityModel=...
    If this is set, TrivySummary will load the specified priority model
    JSON file.
    If this isn't set, the model defaults to SEVERITYONLY, i.e. that
    the priority is the same as the vendor severity.

  --useTodayForEPSSQuery
    If this is set, TrivySummary will request EPSS scores for today and
    not for the date of the scan (the default).
    Is ignored if in offline mode

Whitelisting

This application supports whitelisting vulnerabilities, based on supplying one or more JSON files, each in the format specified below.

Whitelisting a CVE causes it to be removed from the list of open vulnerabilities reported by Trivy and to exclude it from consideration as to the fail threshold (e.g. if the fail threshold is set to CRITICAL and you whitelist the only open CRITICAL CVE, then the application will not report this as an error).

Each JSON file is an array of whitelisting entries. Each whitelisting entry has the following properties:

• vulnerabilityID (mandatory)

  The CVE reference.

• reason (mandatory)

  The justification for why this can be whitelisted, i.e. does not affect your code. Has it been confirmed as a false positive? Does your code feature-control this component to disable the exposure? etc.

• nextReviewDate (mandatory)

  A date in yyyy-MM-dd format. Must be specified. If you are creating a new item for immediate review (e.g. to allow your code to build until you have assessed whether you need to remediate before publication, then set this to today's date or a date in the past).

• approvalDate (optional)

  The date on which this vulnerability was reviewed, in yyyy-MM-dd format. Both the approvalDate and approvedBy fields must be set for TrivySummary to recognise this as having been approved. The approvalDate must not be in the future, or else TrivySummary will not recognise this as having been approved.

• approvedBy (optional)

  The name of the approver. Both the approvalDate and approvedBy fields must be set for TrivySummary to recognise this whitelisting as having been approved.

For sample JSON to whitelist see here

Treatment plan

This application supports a fuller reporting structure of progress by specifying a treatment plan which will be merged into any generated PDF report.

The format of a treatment plan is as follows:

• ticketSystemURLTemplate (mandatory)

  A templated URL form for your ticketing system with the ticket reference replaced by {ticketId}. For example, a typical Jira configuration might be https://myjirasystem.mydomain.com/browse/{ticketId}

• defaultNoteText (mandatory, but may be left blank)

  A default note to be displayed in the event that a vulnerability is detected which does not match a note or treatment

• treatments (mandatory)

  A list of treatments currently in the ticketing system, matching one or more CVE references, and/or one or more artefact names.

• notes (mandatory)

  A list of notes which may apply, matching one or more CVE references, and/or one or more artefact names. Artefact names are matched on the basis of starts-with, so you can write a note that matches multiple tags (e.g. to give operational context to where the component sits in your architecture). The intent here is to be able to give clarity as to the agreed approach where a ticket would be inappropriate (e.g. where no fixes are available yet but a patch release is expected imminently, a note to explain this and how this is tracked might be more appropriate than a treatment linked to a ticket).

For a sample treatment plan JSON see here

<a id="epss"/>Better remediation prioritisation through EPSS (exploitability scoring)

The open source version of Trivy only supports assessment against severity (more properly, emphasising vendor assessment of severity). There are other means of scoring CVEs including EPSS, the Exploit Prediction Scoring System.

TrivySummary will, by default, add EPSS scores to each CVE (unless overridden by the --offline flag) and graph the results. CVEs which are of the highest combination of CVSS and EPSS will be labelled.

In addition, through the use of a custom priority model CVEs with both CVSS and EPSS scores can be more effectively prioritised than by one where only severity is considered..

Please note that a CVE's marked severity and CVSS score may not correspond, as vendors such as RedHat often set a different vendor severity from that implied by the CVSS due to their assessment of the wider circumstances and how software is deployed and used. Trivy takes this into account and prefers the vendor assessment (see Severity Selection section).

<a id="priority-model"/>Priority Model

Providing that TrivySummary is not used in --offline mode, support for a number of different priority models are provided.

Severity-only

The default mode, without specifying a priority model, is Severity-only, where the only prioritisation is, like the open source Trivy product itself, set by the vendor severity (CRITICAL, HIGH, MEDIUM, LOW).

A sample graph might appear as follows:

<img src="media/PriorityMode-SeverityOnly.PNG" width="50%" alt="Severity-only priority model">

Whilst simple in concept, the downside is that it doesn't really assist developers in triaging and prioritising vulnerabilities as each vendor severity may, or may not, align with the expectations of CVSS v3 scores, let alone factor in the exploitability of the vulnerability using EPSS scores.

Rectangular

In this model type, CRITICAL, HIGH and MEDIUM priority CVEs may be identified by setting minimum CVSS and EPSS threshold for each priority and TrivySummary sets a priority purely on the basis of whether each vulnerability is above each threshold. This makes each priority appear as a rectangle, as in the following example:

<img src="media/PriorityMode-Rectangular.PNG" width="50%" alt="Rectangular priority model">

Note the colour grading now and the fact that this is a much clearer model. Also note the effective triaging this allows of vulnerabilities (compare numbers of CRITICAL, HIGH and MEDIUM CVEs with the Severity-only model above).

It's clear advantages are that it improves the signal-to-noise ratio of assessing vulnerabilities and is a very easy model to describe to stakeholders.

It does, however, make the bottom left hand corner of each rectangle be a bit of a potential trap for borderline cases for vulnerabilities, potentially making them appear higher priority than they are. This can be mitigated by simply keeping thresholds to align with the standard model (where it exists) for assigning a textual marker