BREAKING CHANGE: migration to new JSON schema

[knqyf263]

Overview

We will migrate the JSON schema of scan results to a new schema in v0.20.0. You might need to update your JSON parser.

v0.19.0 displays a warning as below when you specify -f json.

$ trivy image -f json alpine:3.11
...
2021-06-08T11:22:17.201+0300    WARN    DEPRECATED: the current JSON schema is deprecated, check https://github.com/aquasecurity/trivy/discussions/1050 for more information.
...

Impact

Trivy CLI

This change affects--format/-f json option regardless of scanning modes such as image, fs, and client. v0.20.0 will generate JSON with a different schema.

$ trivy image -f json alpine:3.12

if you parse the JSON output from Trivy, this change breaks your script. -f table (default) and -f template will not be affected by this change.

GitHub Action (trivy-action)

Not affected

https://github.com/aquasecurity/trivy-action

Schema Change

Current:

[
  {
    "Target": "alpine 3.12",
    "Type": "alpine",
    "Vulnerabilities": [...],
  },
  {
    "Target": "app/jenkins.jar",
    "Type": "java",
    "Vulnerabilities": [...],
  }
]

New:

The current data structure will be kept intact and moved under Results.

NOTE: This new schema is subject to change before the release of v0.19.0.

{
  "SchemaVersion": 2,
  "ArtifactName": "alpine:3.14",
  "ArtifactType": "container_image",
  "Metadata": {
    "OS": {
      "Family": "alpine",
      "Name": "3.14.2"
    },
    "ImageID": "sha256:14119a10abf4669e8cdbdff324a9f9605d99697215a0d21c360fe8dfa8471bab",
    "DiffIDs": [
      "sha256:e2eb06d8af8218cfec8210147357a68b7e13f7c485b991c288c2d01dc228bb68"
    ],
    "RepoTags": [
      "alpine:3.14"
    ],
    "RepoDigests": [
      "alpine@sha256:e1c082e3d3c45cccac829840a25941e679c25d438cc8412c2fa221cf1a824e6a"
    ],
    "ImageConfig": {
      "architecture": "amd64",
      "container": "330289c649db86f5fb1ae5bfef18501012b550adb0638b9193d4a3a4b65a2f9b",
      "created": "2021-08-27T17:19:45.758611523Z",
      "docker_version": "20.10.7",
      "history": [
        {
          "created": "2021-08-27T17:19:45.553092363Z",
          "created_by": "/bin/sh -c #(nop) ADD file:aad4290d27580cc1a094ffaf98c3ca2fc5d699fe695dfb8e6e9fac20f1129450 in / "
        },
        {
          "created": "2021-08-27T17:19:45.758611523Z",
          "created_by": "/bin/sh -c #(nop)  CMD [\"/bin/sh\"]",
          "empty_layer": true
        }
      ],
      "os": "linux",
      "rootfs": {
        "type": "layers",
        "diff_ids": [
          "sha256:e2eb06d8af8218cfec8210147357a68b7e13f7c485b991c288c2d01dc228bb68"
        ]
      },
      "config": {
        "Cmd": [
          "/bin/sh"
        ],
        "Env": [
          "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
        ],
        "Image": "sha256:d3e0b6258ec2f725c19668f11ae5323c3b0245e197ec478424ec6a87935690eb"
      }
    }
  },
  "Results": [
    {
      "Target": "alpine 3.12",
      "Type": "alpine",
      "Class": "os-pkgs",
      "Vulnerabilities": [...],
    },
    {
      "Target": "app/jenkins.jar",
      "Type": "java",
      "Class": "lang-pkgs",
      "Vulnerabilities": [...],
    }
  ]
}

Test

This new JSON schema is available in v0.19.0 by specifying TRIVY_NEW_JSON_SCHEMA=true. The warning is not displayed.

$ TRIVY_NEW_JSON_SCHEMA=true trivy image -f json alpine:3.11
2021-06-08T11:22:17.197+0300    INFO    Detected OS: alpine
2021-06-08T11:22:17.198+0300    INFO    Detecting Alpine vulnerabilities...
2021-06-08T11:22:17.200+0300    INFO    Number of language-specific files: 0
...

We apologize for the inconvenience, but please try this environment variable to fix your JSON parser.

TRIVY_NEW_JSON_SCHEMA env will be removed in v0.20.0, so you will not have to specify it in v0.20.0 or later.

Examples

Here are some examples of what modifications might be needed.

jq

An example of jq parsing the result JSON and displaying the vulnerability IDs

Before:

$ trivy image -f json -o result.json alpine:3.11
$ jq '.[].Vulnerabilities[].VulnerabilityID' result.json
"CVE-2021-30139"
"CVE-2021-28831"
...

After:

$ TRIVY_NEW_JSON_SCHEMA=true trivy image -f json -o result.json alpine:3.11
$ jq '.Results[].Vulnerabilities[].VulnerabilityID' result.json
"CVE-2021-30139"
"CVE-2021-28831"
...

Python

An example of python parsing the result JSON and displaying the vulnerability IDs

Before:

$ trivy image -f json -o result.json alpine:3.11
$ cat parse.py
import json

with open('./result.json') as f:
    res = json.load(f)
    for r in res:
        for v in r["Vulnerabilities"]:
            print(v["VulnerabilityID"])
$ python parse.py
CVE-2021-30139
CVE-2021-28831
...

After:

$ TRIVY_NEW_JSON_SCHEMA=true trivy image -f json -o result.json alpine:3.11
$ cat parse2.py
import json

with open('./result.json') as f:
    res = json.load(f)
    for r in res["Results"]:
        for v in r["Vulnerabilities"]:
            print(v["VulnerabilityID"])
$ python parse.py
CVE-2021-30139
CVE-2021-28831
...

Diff

$ diff parse.py parse2.py
5c5
<     for r in res:
---
>     for r in res["Results"]:

[tspearconquest]

I saw the warning today as we upgraded to 0.19.1 and I want to just say thanks. This new schema is a massive improvement.

[wwuck]

@knqyf263 @tofuatjava Trivy support was recently added to Jenkins in the warnings-ng and analysis-model plugins. This will need to be updated for the new schema?

jenkinsci/warnings-ng-plugin#711
jenkinsci/analysis-model#542

[knqyf263]

I'm sorry I missed your message. If the plugins use Trivy JSON, they need to migrate to the new JSON schema.

[Morl99]

Thanks for the heads-up, that was an easy fix. Really nice, that this was testable with the Environment variable beforehand.
See dbsystel/trivy-vulnerability-explorer#22 for our fix.