Check for Vulnerabilities via the API

The following provides step-by-step instructions for searching for a product, determining its latest version, and checking for any vulnerabilities that affect that product.

If you are new to using the API, it is recommended that you read the API Overview or try the steps here first.

Getting Started

To start, you will need an API token. You can find information on generating an API token here.

In all of the following API command examples, you will replace TOKEN with your API token.

Step 1: Search for a Product

The Search endpoint allows you to search for software products, package repositories, and GitHub repositories. In this case, we are going to search for lodash in software products. The simplest search will return the top 10 product results matching a given search term.

curl -H "Authorization: Bearer TOKEN" \
https://api.ionchannel.io/v1/search?q=lodash

In this case, we don't need more than one result. So, instead, we are going to limit the response to a single product. You can accomplish this by adding the limit parameter to the query:

curl -H "Authorization: Bearer TOKEN" \
https://api.ionchannel.io/v1/search?q=lodash&limit=1

This request gives us the following response.

{
  "data": [
    {
      "id": 0,
      "name": "lodash",
      "org": "lodash",
      "version": "4.17.21",
      "up": "",
      "edition": "",
      "aliases": null,
      "created_at": "2021-04-03T22:31:44Z",
      "updated_at": "2021-04-03T22:31:44Z",
      "title": "",
      "references": null,
      "part": "",
      "language": "",
      "external_id": "cpe:/a:lodash:lodash:4.17.21::~~~node.js~~",
      "source": null,
      "confidence": 0.8966666666666666,
      "vulnerability_count": 1,
      "mttr_seconds": null,
      "vulnerabilities": null
    }
  ],
  "meta": {
    "total_count": 388,
    "limit": 1,
    "offset": 0,
    "duration_ms": 112
  }
}

Step 2: Verify the most recent version

To verify that version 4.17.21 in the previous response is the most recent, we can use the getLatestVersionForDependency endpoint. This endpoint requires the product name and dependency type. Lodash exists in the npm ecosystem, so we will use that as the type.

curl -H "Authorization: Bearer TOKEN" \
https://api.ionchannel.io/v1/dependency/getLatestVersionForDependency?name=lodash&type=npm

The response verifies that 4.17.21 is the most recent version. Your results will likely differ in the future.

{
  "meta": {
    "copyright": "Copyright 2017 - Ion Channel Corp (ionchannel.io)",
    "authors": [
      "tlpinney",
      "Matthew Mayer"
    ],
    "version": "v1",
    "total_count": 1
  },
  "links": {
    "self": "https://api.ionchannel.io/v1/dependency/getLatestVersionForDependency?name=lodash&type=npm"
  },
  "timestamps": {
    "created": "2021-11-02T23:24:43.534Z",
    "updated": "2021-11-02T23:24:43.664Z"
  },
  "data": {
    "version": "4.17.21"
  }
}

Step 3: Get the vulnerability information

Now that we know that we are using the most recent version, we can obtain the vulnerability data for that version of lodash. In this step, we will use the external_id that we got from step 1.

curl -H "Authorization: Bearer TOKEN" \
https://api.ionchannel.io/v1/vulnerability/getVulnerabilities?product=lodash&version=4.17.21

At the time of this writing, this will return information indicating that lodash 4.17.21 is affected by CVE-2021-41720. The summary, however, notes that the vulnerability is disputed. Therefore, this may change in the future.

{
  "data": [
    {
      "id": 312404287,
      "external_id": "CVE-2021-41720",
      "source": [
        {
          "id": 0,
          "name": "NVD",
          "description": "National Vulnerability Database",
          "created_at": "2017-02-09T20:18:35.385658Z",
          "updated_at": "2017-02-13T20:12:05.342693Z",
          "attribution": "Copyright © 1999–2017, The MITRE Corporation. CVE and the CVE logo are registered trademarks and CVE-Compatible is a trademark of The MITRE Corporation.",
          "license": "Submissions: For all materials you submit to the Common Vulnerabilities and Exposures (CVE®), you hereby grant to The MITRE Corporation (MITRE) and all CVE Numbering Authorities (CNAs) a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute such materials and derivative works. Unless required by applicable law or agreed to in writing, you provide such materials on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.\n\nCVE Usage: MITRE hereby grants you a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Common Vulnerabilities and Exposures (CVE®). Any copy you make for such purposes is authorized provided that you reproduce MITRE's copyright designation and this license in any such copy.\n",
          "copyright_url": "http://cve.mitre.org/about/termsofuse.html"
        }
      ],
      "title": "CVE-2021-41720",
      "summary": "** DISPUTED ** A command injection vulnerability in Lodash 4.17.21 allows attackers to achieve arbitrary code execution via the template function. This is a different parameter, method, and version than CVE-2021-23337. NOTE: the vendor's position is that it's the developer's responsibility to ensure that a template does not evaluate code that originates from untrusted input.",
      "score": "9.8",
      "score_version": "3.1",
      "score_system": "CVSS",
      "score_details": {
        "cvssv2": {
          "vectorString": "AV:N/AC:L/Au:N/C:P/I:P/A:P",
          "accessVector": "NETWORK",
          "accessComplexity": "LOW",
          "authentication": "NONE",
          "confidentialityImpact": "PARTIAL",
          "integrityImpact": "PARTIAL",
          "availabilityImpact": "PARTIAL",
          "baseScore": 7.5
        },
        "cvssv3": {
          "vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
          "attackVector": "NETWORK",
          "attackComplexity": "LOW",
          "privilegesRequired": "NONE",
          "userInteraction": "NONE",
          "scope": "UNCHANGED",
          "confidentialityImpact": "HIGH",
          "integrityImpact": "HIGH",
          "availabilityImpact": "HIGH",
          "baseScore": 9.8,
          "baseSeverity": "CRITICAL"
        }
      },
      "vector": "",
      "access_complexity": "",
      "vulnerability_authentication": "",
      "confidentiality_impact": "",
      "integrity_impact": "",
      "availability_impact": "",
      "vulnerabilty_source": "",
      "assessment_check": null,
      "scanner": null,
      "recommendation": "",
      "dependencies": null,
      "references": null,
      "modified_at": "2021-10-07T17:41:00Z",
      "published_at": "2021-09-30T14:15:00Z",
      "created_at": "2021-10-07T18:13:00.724986Z",
      "updated_at": "2021-11-02T09:42:07.381661Z",
      "mttr_seconds": null
    }
  ],
  "meta": {
    "total_count": 1,
    "limit": 10,
    "offset": 0,
    "last_update": "2018-10-11T21:23:06.164046Z",
    "duration_ms": 63
  }
}