415 Vulnerability Databases 01d8449e

# 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**:
```json
{
  "package": {
    "name": "lodash",
    "ecosystem": "npm"
  },
  "version": "4.17.20"
}
```

**Response format**:
```json
{
  "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

```json
{
  "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**:
```graphql
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**:
```json
{
  "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

| Feature | OSV.dev | NVD | GitHub Advisory |
|---------|---------|-----|-----------------|
| Authentication | None | Optional (API key) | Required (token) |
| Rate Limit | Generous | 5-50 req/30s | 5000 req/hour |
| Ecosystems | 15+ | All (via CPE) | 8 major |
| Data Freshness | Real-time | Daily updates | Real-time |
| Version Matching | Built-in | Manual | Built-in |
| Best For | Open source | CVE research | GitHub projects |

## 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.