Getting the most out of snyk test with JSON

Running snyk test will scan your application’s dependencies and test to see if any of them contain known vulnerabilities. If any vulnerabilities are discovered, the command will result in an error and output information about the vulnerability, and how to address it, to the console.

It works great in a CI environment and provides you with plenty of actionable information. Sometimes, however, you may want to take it a step further and manipulate the test results in some way or create a local report that you can easily share. That’s where the --json option (which outputs the results of snyk test to JSON) comes into play.

We thought we would walk you through a few of the things you can accomplish using snyk test --json and a few freely available tools.

The JSON option

Running snyk test --json outputs a JSON object with some basic and useful information about your project. Here’s the basic format of that object today:

{
  "ok": false,
  "vulnerabilities": [...],
  "dependencyCount": 72,
  "org": "myOrg",
  "licensesPolicy": null,
  "isPrivate": true,
  "packageManager": "rubygems",
  "summary": "2 vulnerable dependency paths",
  "filtered": {
    "ignore": [],
    "patch": []
  },
  "uniqueCount": 1
}

In addition, vulnerabilities contains detailed information about each vulnerability discovered:

{
    "title": "",
    "credit": [],
    "description": "",
    "moduleName": "",
    "language": "",
    "packageManager": "",
    "semver": {
      "unaffected": [],
      "vulnerable": []
    },
    "identifiers": {
      "CWE": [],
      "CVE": []
    },
    "CVSSv3": "",
    "severity": "",
    "creationTime": "",
    "modificationTime": "",
    "publicationTime": "",
    "disclosureTime": "",
    "id": "",
    "packageName": "",
    "from": [],
    "upgradePath": [],
    "version": "",
    "name": "",
    "isUpgradable": false,
    "isPatchable": false
 }

All of that information provides us with plenty of different ways to customize Snyk test results.

Custom sorting of vulnerabilities

By default, snyk test will report vulnerabilities in the order that it discovers them through the generated dependency tree.

There are a few different tools you could use to massage the results and reorder them, but we’ll use jq. jq is a command-line JSON processor. It lets you pipe JSON data in, filter the JSON, and then pipe the resulting data back out.

Using jq, you can sort the results in whatever way you would like. For example, you could sort the vulnerabilities by publication date so that the newest vulnerabilities appear first.

snyk test --json | jq '.vulnerabilities |= sort_by(.publicationTime) | .vulnerabilities |= reverse'

Or, with a few more lines, you could sort the vulnerabilities by severity so that the most critical vulnerabilities are listed first.

snyk test --json | jq '.vulnerabilities|= map(. + {severity_numeric: (if(.severity) == "high" then 1 else (if(.severity) == "medium" then 2 else (if(.severity) == "low" then 3 else 4 end) end) end)}) |.vulnerabilities |= sort_by(.severity_numeric) | del(.vulnerabilities[].severity_numeric)'

Custom vulnerability severity

You can also use jq to change the severity for a vulnerability that, for whatever reason, you decide should differ from the severity Snyk provides.

For example, maybe your site depends on a version of Nokogiri that contains a high-severity Arbitrary Code Execution vulnerability, but your team has concluded that the way Nokogiri is used makes the issue less severe. You could use jq to change the vulnerability severity in your reports.

snyk test --json | jq '. | (.vulnerabilities[] | select(.id == "SNYK-RUBY-NOKOGIRI-20367").severity |= "low")

Generate a local HTML report

The online dashboard for your project details each vulnerability: its severity, a description, vulnerable paths and much more. If you want a local copy based on snyk test results, you can use our open-source Snyk JSON to HTML Mapper.

The mapper accepts snyk test --json and generates a local HTML report, with no external resources. To use it, you can install it globally using npm install -g snyk-to-html. Then when you run the test command, you can pipe the results directly to the module, like so:

snyk test --json | snyk-to-html -o results.html

The above command will create a nicely styled local report, with no external dependencies.

If you’re customizing the JSON output with jq, you can pipe the altered JSON results as well. For example, the following command will result in a local HTML report with the vulnerabilities sorted by publication date.

snyk test --json | jq '.vulnerabilities |= sort_by(.publicationTime) | .vulnerabilities |= reverse' | snyk-to-html -o results.html

Bespoke reporting with JSON

Running snyk test by itself will give you a lot of useful information. If you need a little more flexibility, snyk test --json has you covered. With a few free tools and a little bit of creativity, you can create Snyk results customized to your specific needs.

If you are using the JSON output to handle any custom reports or functionality, let us know. We would love to hear what you’ve come up with!