# Vulnerabilities

## Definition

A Vulnerability represents a known security issue that affects one or more Components in a Version. The platform maps vulnerabilities to Components using their identifiers (PURL, CPE) and correlates them against multiple vulnerability databases.

Each vulnerability record includes the CVE ID, severity, and description, and is scoped per organization. When a vulnerability is linked to a specific Component, additional context is tracked — including VEX status, fix availability, and custom CVSS adjustments.

## Source Databases

The platform aggregates vulnerability data from:

* **NVD** (National Vulnerability Database)
* **GitHub Security Advisories**
* **OSV** (Open Source Vulnerabilities)
* **Other ecosystem-specific databases**

## Vulnerability Mapping

```
Component (PURL/CPE) → Vulnerability Database Lookup → Affected Version Range Check → Vulnerability Record
```

The platform:

1. Extracts identifiers (PURL, CPE) from each Component.
2. Queries vulnerability databases for known issues.
3. Checks whether the Component's version falls within the affected version range.
4. Creates a vulnerability record linking the Component to the Vulnerability.

## Severity and Scoring

| Metric              | Description                                                                                                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **CVSS Score**      | Common Vulnerability Scoring System (v3.1). Base score from 0.0 to 10.0.                                                   |
| **CVSS Vector**     | Detailed attack vector string (e.g., `CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H`).                                      |
| **Severity**        | Derived classification: Critical (9.0–10.0), High (7.0–8.9), Medium (4.0–6.9), Low (0.1–3.9).                              |
| **EPSS Score**      | Exploit Prediction Scoring System — probability (0–1) that the vulnerability will be exploited in the wild within 30 days. |
| **EPSS Percentile** | Relative ranking among all scored vulnerabilities.                                                                         |
| **KEV**             | Whether the vulnerability appears in CISA's Known Exploited Vulnerabilities catalog.                                       |
| **CWE**             | Common Weakness Enumeration classification.                                                                                |

### Custom Scoring Adjustments

Administrators can adjust vulnerability scoring per component:

* **Adjusted CVSS Score**: Override the base CVSS score based on organizational context.
* **Temporal Vector**: Apply temporal metrics (exploit maturity, remediation level).
* **Environmental Vector**: Apply environmental metrics specific to your deployment context.

## Vulnerability Lifecycle (VEX)

The platform supports the [Vulnerability Exploitability eXchange (VEX)](https://www.cisa.gov/resources-tools/resources/minimum-requirements-vulnerability-exploitability-exchange-vex) standard for tracking vulnerability disposition:

| Status                  | Description                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------- |
| **Affected**            | The vulnerability applies to this component in this context. Remediation is required. |
| **Not Affected**        | The vulnerability does not apply. A justification must be provided.                   |
| **Under Investigation** | The applicability of the vulnerability is being assessed.                             |
| **Fixed**               | The vulnerability has been remediated.                                                |

When marking a vulnerability as **Not Affected**, a justification is required:

| Justification                                       | Meaning                                                                               |
| --------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `component_not_present`                             | The vulnerable component is not actually present.                                     |
| `vulnerable_code_not_present`                       | The specific vulnerable code path is not included.                                    |
| `vulnerable_code_not_in_execute_path`               | The vulnerable code exists but cannot be reached.                                     |
| `vulnerable_code_cannot_be_controlled_by_adversary` | The vulnerable code is present and reachable, but cannot be exploited by an attacker. |
| `inline_mitigations_already_exist`                  | Compensating controls are in place.                                                   |

## Querying Vulnerabilities

**Via CLI:**

```bash
# List vulnerabilities for a product
pylynk vulns --prod "my-backend-service" --env "production"

# With full details
pylynk vulns --prod "my-backend-service" --vuln-details --vex-details --output json

# Custom columns
pylynk vulns --prod "my-backend-service" \
  --columns "id,component_name,component_version,severity,cvss,epss,status,justification"

# Export for compliance reporting
pylynk vulns --prod "my-backend-service" --env "production" \
  --vuln-details --vex-details --output csv > vuln-report.csv

# List all available column names
pylynk vulns --list-columns
```

**Via API:**

```bash
curl -X POST https://api.interlynk.io/lynkapi \
  -H "Authorization: Bearer $INTERLYNK_SECURITY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { organization { projectGroups(first: 5) { nodes { name projects { nodes { name sboms(first: 1) { nodes { id componentVulns(first: 10) { nodes { vuln { vulnId sev cvssScore } component { name version } } } } } } } } } } }"
  }'
```

**Via MCP:**

```
list_vulnerabilities       # List vulnerabilities with severity/VEX/KEV filtering
get_vulnerability          # Get vulnerability by CVE ID or UUID
search_vulnerabilities     # Search vulnerabilities across all products
```

## Integration Impact

Vulnerabilities interact with other platform features:

| Feature              | Impact                                                                                                     |
| -------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Policies**         | Policies can trigger on vulnerability severity, EPSS score, KEV status, VEX status, and more.              |
| **Automation Rules** | Rules can auto-assign VEX status, create tickets, or send notifications based on vulnerability attributes. |
| **Ticketing**        | Jira/Linear tickets can be created automatically for new vulnerabilities matching policy conditions.       |
| **Notifications**    | Slack, Teams, and email notifications can be triggered for vulnerability events.                           |
| **Health Scoring**   | Open vulnerabilities reduce the Product/Version health score.                                              |
| **Compliance**       | Vulnerability disposition status affects compliance evaluations (NTIA, FDA, CRA).                          |

## Best Practices

* **Prioritize by exploitability, not just severity.** Use EPSS scores and KEV status to focus on vulnerabilities most likely to be exploited. A high-EPSS, KEV-listed medium-severity vulnerability may be more urgent than a critical vulnerability with no known exploit.
* **Triage systematically.** Establish a workflow: new vulnerabilities → under investigation → affected/not affected → fixed. Record justifications for all "not affected" dispositions.
* **Use environment-aware prioritization.** A vulnerability in a `production` Environment is more urgent than the same vulnerability in `development`. Configure policies accordingly.
* **Enable "Copy VEX Across Versions on Import"** to avoid re-triaging the same vulnerabilities when SBOMs are re-uploaded.
* **Use Custom Fields** to track organization-specific metadata (e.g., assigned engineer, remediation deadline, business impact assessment).
* **Review KEV-listed vulnerabilities immediately.** CISA's KEV catalog contains vulnerabilities known to be actively exploited. These should be remediated with the highest priority.
* **Automate ticket creation** for vulnerabilities that match your triage thresholds (e.g., critical severity + KEV = auto-create Jira ticket).

## Common Misconfigurations

| Issue                                    | Symptom                                                   | Fix                                                                                                      |
| ---------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Vulnerability scanning disabled          | No vulnerabilities appear after upload                    | Enable "Run Vulnerability Scan" in Environment settings                                                  |
| Components lack identifiers              | Known-vulnerable components show no vulnerabilities       | Improve SBOM tooling to produce PURL/CPE identifiers                                                     |
| VEX status not preserved across versions | Triage work lost on each upload                           | Enable "Retain Vulnerability Status with Version" and "Copy VEX Across Versions on Import"               |
| EPSS/KEV data missing                    | EPSS and KEV columns empty                                | EPSS/KEV enrichment is automatic; if missing, the vulnerability may be too new or not in the KEV catalog |
| Overly broad automation rules            | Non-critical vulnerabilities generating excessive tickets | Narrow rule conditions — target specific severities, EPSS thresholds, or KEV status                      |