Vulnerability Database APIs

Vulnerability Database APIs

This reference documents the vulnerability databases used by the scanner and their APIs.

OSV.dev (Open Source Vulnerabilities)

URL: https://osv.dev API: https://api.osv.dev/v1/query

Overview

OSV.dev is a distributed vulnerability database for open source projects. It aggregates data from multiple sources including:

• GitHub Security Advisories
• PyPI Advisory Database
• RustSec Advisory Database
• Go Vulnerability Database
• And many more

Supported Ecosystems

• npm - Node.js/JavaScript
• PyPI - Python
• Maven - Java
• Go - Go modules
• crates.io - Rust
• NuGet - .NET
• RubyGems - Ruby
• Packagist - PHP

Query API

Endpoint: POST https://api.osv.dev/v1/query

Request format:

{
  "package": {
    "name": "lodash",
    "ecosystem": "npm"
  },
  "version": "4.17.20"
}

Response format:

{
  "vulns": [
    {
      "id": "GHSA-xxxx-xxxx-xxxx",
      "summary": "Prototype Pollution in lodash",
      "published": "2021-02-15T00:00:00Z",
      "modified": "2021-02-15T00:00:00Z",
      "affected": [
        {
          "package": {
            "name": "lodash",
            "ecosystem": "npm"
          },
          "ranges": [
            {
              "type": "SEMVER",
              "events": [
                {"introduced": "0"},
                {"fixed": "4.17.21"}
              ]
            }
          ]
        }
      ],
      "severity": [
        {
          "type": "CVSS_V3",
          "score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
        }
      ]
    }
  ]
}

Key Fields

• id: Vulnerability identifier (CVE, GHSA, etc.)
• published: Publication date (ISO 8601 format)
• modified: Last modification date
• summary: Brief description
• affected[].ranges[].events: Version ranges affected
  • introduced: First affected version
  • fixed: First fixed version
• severity: CVSS scores and severity ratings

Rate Limits

OSV.dev API has no authentication and no strict rate limits for reasonable use.

NVD (National Vulnerability Database)

URL: https://nvd.nist.gov API: https://services.nvd.nist.gov/rest/json/cves/2.0

Overview

NVD is the U.S. government repository of standards-based vulnerability management data. It provides comprehensive CVE information with CVSS scores.

API Access

Requires API key for higher rate limits. Get one at: https://nvd.nist.gov/developers/request-an-api-key

Endpoint: GET https://services.nvd.nist.gov/rest/json/cves/2.0

Query parameters:

• cveId: Specific CVE ID
• pubStartDate: Filter by publication start date (YYYY-MM-DD)
• pubEndDate: Filter by publication end date
• lastModStartDate: Filter by last modification date

Example:

GET https://services.nvd.nist.gov/rest/json/cves/2.0?pubStartDate=2023-01-01T00:00:00.000&pubEndDate=2023-12-31T23:59:59.999

Response Format

{
  "vulnerabilities": [
    {
      "cve": {
        "id": "CVE-2023-12345",
        "published": "2023-06-15T10:15:00.000",
        "lastModified": "2023-06-15T10:15:00.000",
        "descriptions": [
          {
            "lang": "en",
            "value": "Vulnerability description..."
          }
        ],
        "metrics": {
          "cvssMetricV31": [
            {
              "cvssData": {
                "baseScore": 7.5,
                "baseSeverity": "HIGH"
              }
            }
          ]
        }
      }
    }
  ]
}

Rate Limits

• Without API key: 5 requests per 30 seconds
• With API key: 50 requests per 30 seconds

GitHub Security Advisory Database

URL: https://github.com/advisories API: GitHub GraphQL API

Overview

GitHub's curated database of security vulnerabilities affecting open source packages.

API Access

Requires GitHub Personal Access Token with public_repo scope.

Endpoint: POST https://api.github.com/graphql

Query:

query($package: String!, $ecosystem: SecurityAdvisoryEcosystem!) {
  securityVulnerabilities(first: 100, package: $package, ecosystem: $ecosystem) {
    nodes {
      advisory {
        ghsaId
        summary
        severity
        publishedAt
        cvss {
          score
          vectorString
        }
      }
      vulnerableVersionRange
      firstPatchedVersion {
        identifier
      }
    }
  }
}

Variables:

{
  "package": "lodash",
  "ecosystem": "NPM"
}

Supported Ecosystems

• NPM - Node.js
• PIP - Python
• MAVEN - Java
• RUBYGEMS - Ruby
• NUGET - .NET
• COMPOSER - PHP
• GO - Go
• RUST - Rust

Rate Limits

• 5,000 requests per hour with authentication

Comparing Data Sources

Best Practices

Query Strategy

1. Start with OSV.dev: No auth required, broad coverage, version-aware
2. Supplement with GitHub: For GitHub-hosted projects
3. Use NVD for research: When you need official CVE details

Handling Rate Limits

• Implement exponential backoff
• Cache results locally
• Batch queries when possible
• Use API keys/tokens for higher limits

Date Filtering

Different databases use different date fields:

• OSV.dev: published field (ISO 8601)
• NVD: published field (ISO 8601 with milliseconds)
• GitHub: publishedAt field (ISO 8601)

Always filter on the publication date, not the modification date, to identify newly disclosed vulnerabilities.

Version Matching

OSV.dev provides the most robust version matching:

• Supports semantic versioning
• Handles version ranges automatically
• Returns only vulnerabilities affecting the specific version

For other databases, you may need to manually parse version ranges and check if your version falls within the affected range.