> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCANOSS API

> Provides vulnerability intelligence for software components including CPE enumeration and vulnerability analysis.

## Prerequisites

Before using the SCANOSS API, ensure you have:

* 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:

```bash theme={null}
# Set API key
export SCANOSS_API_KEY="your-api-key-here"

# Verify configuration
echo $SCANOSS_API_KEY
```

**Persistent Configuration (Optional)**:

```bash theme={null}
# 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. CPEs are used to identify IT platforms in vulnerability databases and enable vulnerability scanning and assessment.

### Request Format

See [Common API Types](https://github.com/scanoss/papi/blob/49b124f3075fc8776630ba1e068646bda23f174a/protobuf/scanoss/api/common/v2/README.md#componentrequest) for `ComponentRequest` documentation.

### HTTP Request Example

```bash theme={null}
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

```json theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "requirement": ">=5.0.0",
    "version": "5.0.0",
    "cpes": ["cpe:2.3:a:scanoss:engine:1.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](https://github.com/scanoss/papi/blob/49b124f3075fc8776630ba1e068646bda23f174a/protobuf/scanoss/api/common/v2/README.md#componentsrequest) for `ComponentsRequest` documentation.

### HTTP Request Example

```bash theme={null}
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 other security metadata. Vulnerability data is sourced from various security databases and feeds.

### Request Format

See [Common API Types](https://github.com/scanoss/papi/blob/49b124f3075fc8776630ba1e068646bda23f174a/protobuf/scanoss/api/common/v2/README.md#componentrequest) for `ComponentRequest` documentation.

### HTTP Request Example

```bash theme={null}
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 method returns comprehensive vulnerability information including:

* `purl` field: the requested component
* `vulnerabilities` array: List of known vulnerabilities affecting the component
* `version` field: Shows the specific version that was analyzed
* `requirement` field: Echoes the client's version constraint from the request

Each vulnerability object contains:

* CVE identifier and reference URL
* Severity classification and CVSS information
* Publication and modification dates
* Summary description
* Source database information
* CVSS array with detailed scoring information (vector, score, and severity)

### CVSS Information

The `cvss` field is an array of CVSS (Common Vulnerability Scoring System) objects, allowing for multiple CVSS versions or sources. Each CVSS object contains:

* `cvss`: The 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_score`: The numerical CVSS score (0.0 to 10.0)
* `cvss_severity`: The severity rating based on the score ("None", "Low", "Medium", "High", "Critical")

### Response Examples

#### Component with Vulnerabilities

```bash theme={null}
{
  "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

```bash theme={null}
{
  "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](https://github.com/scanoss/papi/blob/49b124f3075fc8776630ba1e068646bda23f174a/protobuf/scanoss/api/common/v2/README.md#componentsrequest) for `ComponentsRequest` documentation.

### HTTP Request Example

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