Skip to content

cve-correlation.md

Latest commit

 

History

History
175 lines (130 loc) · 4.9 KB

cve-correlation.md

File metadata and controls

175 lines (130 loc) · 4.9 KB

CVE Correlation

RTOSploit includes an offline-first CVE database covering known vulnerabilities in FreeRTOS, ThreadX, and Zephyr. It correlates firmware fingerprints against this database to surface applicable CVEs without requiring a network connection.

Database Overview

The CVE database is stored as rtosploit/cve/bundled_cves.json. It is pre-populated at install time and can be updated incrementally from the NIST NVD API.

CVE Entry Schema

{
  "cve_id": "CVE-2021-31571",
  "description": "A heap buffer overflow in prvCopyDataToQueue...",
  "cvss_score": 8.8,
  "severity": "HIGH",
  "affected_product": "freertos",
  "affected_versions": ["10.3.x", "10.4.0", "10.4.1"],
  "references": [
    "https://nvd.nist.gov/vuln/detail/CVE-2021-31571"
  ],
  "published_date": "2021-05-17",
  "has_exploit": true
}

Severity Levels

Level CVSS Range
CRITICAL 9.0 – 10.0
HIGH 7.0 – 8.9
MEDIUM 4.0 – 6.9
LOW 0.1 – 3.9
NONE 0.0

How Correlation Works

The CVECorrelator receives the RTOSFingerprint from static analysis and returns matching CVEs:

  1. RTOS type matching — Filter by affected_product matching the detected RTOS (freertos, threadx, zephyr)
  2. Version matching — Compare the detected version against affected_versions patterns (supports wildcards: 10.4.x, *)
  3. Ranking — Sort by CVSS score descending
  4. Exploitable filter — Tag entries where has_exploit == true
RTOSFingerprint(rtos_type="freertos", version="10.4.1")
  ↓
CVECorrelator.correlate()
  ↓
CorrelationResult(
  matching_cves=[CVE-2021-31571, CVE-2021-31572, ...],
  exploitable=[CVE-2021-31571],
  highest_severity="HIGH"
)

Commands

Scan Firmware

Fingerprint the firmware and return applicable CVEs:

rtosploit cve scan --firmware firmware.bin

# Override detection if fingerprinting fails
rtosploit cve scan --firmware firmware.bin --rtos freertos --version "10.4.1"

# JSON output
rtosploit --json cve scan --firmware firmware.bin

Example output:

CVE Scan Results for firmware.bin
──────────────────────────────────────────────────────────────────────
CVE ID           CVSS  Severity  Exploit  Description
CVE-2021-31571   8.8   HIGH      ✓        Heap overflow in prvCopyDataToQueue
CVE-2021-31572   8.8   HIGH      ✓        Heap overflow in prvCopyDataToQueue (2)
CVE-2018-16599   9.8   CRITICAL  ✗        TCP/IP stack integer overflow
──────────────────────────────────────────────────────────────────────
3 CVEs found. 2 have known exploits. Highest severity: CRITICAL.

Search the Database

Free-text search across CVE IDs, descriptions, and product names:

rtosploit cve search "heap overflow"
rtosploit cve search CVE-2021-31571
rtosploit cve search freertos
rtosploit --json cve search "tcp" | jq '.[].cve_id'

Update from NVD

Pull the latest CVE entries from the NIST National Vulnerability Database:

# Without API key (subject to rate limits)
rtosploit cve update

# With API key (higher rate limits)
NVD_API_KEY=your-key rtosploit cve update

# Update only FreeRTOS entries
rtosploit cve update --product freertos

The update is incremental — only new entries are added. Existing entries are not overwritten.

Offline Operation

The bundled database works with no internet access. The cve update command is optional and only needed to incorporate CVEs published after your install date.

In air-gapped environments:

  1. Run rtosploit cve update on an internet-connected machine to download the latest database
  2. Copy ~/.config/rtosploit/cve_db.json to the air-gapped system

Or commit the updated bundled_cves.json to your repository to freeze the database at a known state.

NVD API Key

Obtain a free API key at https://nvd.nist.gov/developers/request-an-api-key to:

  • Increase rate limits from 5 requests/30s to 50 requests/30s
  • Avoid delays when fetching large product CVE lists

Set it as an environment variable:

export NVD_API_KEY=your-key-here

Or in your shell profile (~/.bashrc, ~/.zshrc).

JSON Output Schema

{
  "firmware": "firmware.bin",
  "rtos_detected": "freertos",
  "version_detected": "10.4.1",
  "cves": [
    {
      "cve_id": "CVE-2021-31571",
      "cvss_score": 8.8,
      "severity": "HIGH",
      "has_exploit": true,
      "description": "A heap buffer overflow...",
      "affected_versions": ["10.3.x", "10.4.0", "10.4.1"],
      "references": ["https://nvd.nist.gov/vuln/detail/CVE-2021-31571"]
    }
  ],
  "summary": {
    "total": 3,
    "exploitable": 2,
    "highest_severity": "CRITICAL"
  }
}