Skip to main content

​
Prerequisites

Before using the SCANOSS API, ensure you have:
  • A SCANOSS API key
  • curl: command-line tool (pre-installed on Linux/macOS)
  • jq (optional): JSON processor for readable output

​
Authentication Setup

Configure your API key as an environment variable: 
# Set API key
export SCANOSS_API_KEY="your-api-key-here"

# Verify configuration
echo $SCANOSS_API_KEY
Persistent Configuration (Optional): 
# Add to shell profile for persistence
echo 'export SCANOSS_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

​
GetComponentCpes

Retrieves Common Platform Enumeration (CPE) identifiers for a single software component identified by Package URL (PURL). CPE identifiers are used to identify IT platforms in vulnerability databases, enabling vulnerability scanning and assessment.

​
Request Format

See Common API Types for ComponentRequest documentation.

​
HTTP Request Example

curl -X GET 'https://api.scanoss.com/v2/vulnerabilities/cpes/component?purl=pkg:github/scanoss/engine&requirement=>=5.0.0' \
  -H "X-Api-Key: $SCANOSS_API_KEY" | jq

​
Response Example

{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "requirement": ">=5.0.0",
    "version": "5.0.0",
    "cpes": ["cpe:2.3:a:scanoss:engine:5.0.0:*:*:*:*:*:*:*"]
  },
  "status": {
    "status": "SUCCESS",
    "message": "CPEs successfully retrieved"
  }
}

​
GetComponentsCpes

Batch version of GetComponentCpes. Retrieves CPE identifiers for multiple components in a single request.

​
Request Format

See Common API Types for ComponentsRequest documentation.

​
HTTP Request Example

curl -X POST 'https://api.scanoss.com/v2/vulnerabilities/cpes/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SCANOSS_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=5.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq

​
GetComponentVulnerabilities

Analyses a single software component and returns known vulnerabilities, including CVE details, severity scores, publication dates, and additional security metadata. Vulnerability data is sourced from the NVD (National Vulnerability Database) and other security feeds.

​
Request Format

See Common API Types for ComponentRequest documentation.

​
HTTP Request Example

curl -X GET 'https://api.scanoss.com/v2/vulnerabilities/component?purl=pkg:github/scanoss/engine&requirement=>=5.0.0' \
  -H "X-Api-Key: $SCANOSS_API_KEY" | jq

​
Response Format

The response contains a component object with the following fields:
FieldDescription
purlThe requested component’s Package URL
requirementThe version constraint provided in the request
versionThe specific version that was analysed
vulnerabilitiesArray of known vulnerabilities affecting the component (may be empty)
Each object in the vulnerabilities array contains:
FieldDescription
idCVE identifier
cveCVE identifier (same as id)
urlReference URL for the CVE entry
summaryDescription of the vulnerability
severitySeverity rating (Low, Medium, High, Critical)
publishedISO 8601 timestamp of initial publication
modifiedISO 8601 timestamp of last modification
sourceSource database (e.g. NVD)
cvssArray of CVSS scoring objects (see below)

​
CVSS Information

The cvss field is an array of CVSS (Common Vulnerability Scoring System) objects. Multiple entries may be present where more than one CVSS version or source applies. Each object contains:
FieldDescription
cvssThe CVSS vector string (e.g. CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H)
cvss_scoreNumerical CVSS score (range: 0.0 to 10.0)
cvss_severitySeverity rating derived from the score (None, Low, Medium, High, Critical)
Note: The field name cvss is used both for the array itself and for the vector string field within each array object. Take care to distinguish between these when parsing the response.

​
Response Examples

​
Component with Vulnerabilities

{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "requirement": ">=5.0.0",
    "version": "5.0.0",
    "vulnerabilities": [
      {
        "id": "CVE-2024-12345",
        "cve": "CVE-2024-12345",
        "url": "https://nvd.nist.gov/vuln/detail/CVE-2024-12345",
        "summary": "Buffer overflow vulnerability in input processing",
        "severity": "High",
        "published": "2024-01-15T10:30:00Z",
        "modified": "2024-01-16T14:20:00Z",
        "source": "NVD",
        "cvss": [
          {
            "cvss": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
            "cvss_score": 7.5,
            "cvss_severity": "High"
          }
        ]
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Vulnerabilities successfully retrieved"
  }
}

​
Component with No Known Vulnerabilities

{
  "component": {
    "purl": "pkg:github/scanoss/scanoss.py",
    "requirement": ">1.30.0",
    "version": "1.31.0",
    "vulnerabilities": []
  },
  "status": {
    "status": "SUCCESS",
    "message": "Vulnerabilities successfully retrieved"
  }
}

​
GetComponentsVulnerabilities

Batch version of GetComponentVulnerabilities. Analyses multiple components and returns vulnerability information for each in a single request.

​
Request Format

See Common API Types for ComponentsRequest documentation.

​
HTTP Request Example

curl -X POST 'https://api.scanoss.com/v2/vulnerabilities/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SCANOSS_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=5.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq