# Components

## Definition

A Component represents a unit of software — a library, package, framework, container, or application — that makes up a Product Version. Components are extracted from SBOMs during upload and enriched with data from open-source ecosystems and vulnerability databases.

## Component Types

The platform supports 14 component kinds:

| Kind                     | Description                  |
| ------------------------ | ---------------------------- |
| `library`                | Reusable software library    |
| `framework`              | Application framework        |
| `application`            | Standalone application       |
| `container`              | Container image              |
| `platform`               | Operating system or platform |
| `device`                 | Hardware device              |
| `device-driver`          | Device driver                |
| `firmware`               | Firmware binary              |
| `file`                   | Individual file              |
| `operating-system`       | Operating system             |
| `machine-learning-model` | ML model                     |
| `data`                   | Data asset                   |
| `cryptographic-asset`    | Cryptographic material       |

## Component Metadata

| Field                   | Description                                                         | Required |
| ----------------------- | ------------------------------------------------------------------- | -------- |
| **Name**                | Component name                                                      | Yes      |
| **Version**             | Component version                                                   | Yes      |
| **Type**                | Component kind (see above)                                          | Yes      |
| **PURL**                | Package URL — canonical identifier for package ecosystem lookup     | No       |
| **CPE**                 | Common Platform Enumeration — identifier for vulnerability matching | No       |
| **Supplier**            | Organization or individual that supplies the component              | No       |
| **License**             | SPDX license expression (e.g., `MIT`, `Apache-2.0 OR MIT`)          | No       |
| **Group**               | Component grouping (e.g., Maven groupId)                            | No       |
| **Scope**               | Usage scope (`required`, `optional`, `excluded`)                    | No       |
| **Description**         | Human-readable description                                          | No       |
| **Copyright**           | Copyright statement                                                 | No       |
| **Support Level**       | Maintenance status (see below)                                      | No       |
| **End-of-Support Date** | Date when support ends                                              | No       |
| **Primary**             | Whether this is the primary (top-level) component                   | No       |
| **Internal**            | Whether this is an internal (first-party) component                 | No       |

## Component Identification

Components are identified and matched to vulnerability databases using:

1. **PURL (Package URL)**: The primary identifier. Encodes ecosystem, namespace, name, version, and qualifiers. Example: `pkg:npm/@express/express@4.18.2`
2. **CPE (Common Platform Enumeration)**: Used for matching against NVD and other CVE databases. Example: `cpe:2.3:a:expressjs:express:4.18.2:*:*:*:*:node.js:*:*`

{% hint style="warning" %}
Components without PURL or CPE identifiers may not be matched against vulnerability databases. Ensure your SBOM generation tooling produces accurate identifiers.
{% endhint %}

## Component Support Levels

| Level                  | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `actively_maintained`  | Component is actively developed and supported   |
| `no_longer_maintained` | Component is no longer receiving updates        |
| `abandoned`            | Component has been abandoned by its maintainers |
| `unspecified`          | Support status is unknown                       |

The platform can analyze component support status automatically when the **Run Component Support Analysis** setting is enabled.

## Component Enrichment

After upload, the platform enriches components with:

| Data Source                | Information Added                                                              |
| -------------------------- | ------------------------------------------------------------------------------ |
| **OpenSSF Scorecard**      | Security posture scoring for open-source projects                              |
| **Component Health Score** | Aggregated health metric based on maintenance, security, and community signals |
| **Package Insights**       | Deprecation status, archive status, download counts                            |
| **Version Insights**       | Whether the component version is outdated, latest available version            |
| **Source Code Insights**   | Repository activity, contributor metrics                                       |

## Component Relationships

Components can have dependency relationships:

* **Direct dependencies**: Components explicitly declared in the project manifest.
* **Transitive dependencies**: Components pulled in indirectly through direct dependencies.

The platform tracks these relationships as a dependency graph, which is visible in the Version's **Relations** tab.

## Querying Components

**Via CLI:**

```bash
# List vulnerabilities (includes component info)
pylynk vulns --prod "my-backend-service" --env "production" \
  --columns "component_name,component_version,severity,cvss"
```

**Via MCP:**

```
list_components        # List components with filtering by kind, direct dependencies
get_component          # Get component details with PURL, CPE, licenses
```

## Best Practices

* **Ensure accurate PURL and CPE identifiers.** Use mature SBOM generation tools (Syft, Trivy, CycloneDX CLI) that produce complete identifiers. Poor identifiers lead to missed vulnerability matches.
* **Label internal components.** Enable "Run Internal Labeling" so that first-party components are distinguished from third-party dependencies. This improves policy targeting and reduces false positives.
* **Monitor component support status.** Enable "Run Component Support Analysis" to identify abandoned or deprecated components before they become security liabilities.
* **Track transitive dependencies.** Vulnerabilities in transitive dependencies are just as exploitable as those in direct dependencies. Do not ignore them.
* **Review unknown components.** Components with no PURL, no CPE, and no supplier are difficult to track. Investigate and enrich them manually or improve your SBOM tooling.

## Common Misconfigurations

| Issue                                          | Symptom                                                              | Fix                                                                                   |
| ---------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Missing PURL/CPE in SBOM                       | Components show zero vulnerabilities despite being known-vulnerable  | Improve SBOM generation tooling; use tools that produce complete identifiers          |
| Internal components flagged as vulnerable      | False positives from internal packages matching public package names | Enable Internal Labeling; configure policies to exclude internal components           |
| Transitive dependencies excluded from policies | Vulnerabilities in transitive deps not flagged                       | Review policy exclusions; remove `exclude_transitive_dependencies` unless intentional |
| Component support analysis disabled            | No deprecation/abandonment warnings                                  | Enable "Run Component Support Analysis" in Environment settings                       |