# Tools

The Tools page provides utility functions for SBOM analysis and component investigation. Two tools are available: **SBOM Compare** for identifying drift between Versions, and **PURL Lookup** for investigating individual packages by their Package URL.

***

## Overview

Tools complement the core SBOM management workflow with ad-hoc analysis capabilities:

* **SBOM Compare** — compare two Versions side-by-side to identify added, removed, and modified components. Useful for release validation, drift detection, and change review.
* **PURL Lookup** — query package metadata, vulnerability data, and ecosystem information for any Package URL. Useful for component investigation, pre-adoption review, and incident response.

***

## SBOM Compare

SBOM Compare analyzes the differences between two Versions of the same or different Products. The comparison identifies component-level changes to help you understand what changed between releases.

### Running a Comparison

1. Navigate to the **Tools** page in the main navigation.
2. Select the **Compare** tab.
3. Select the **Source Version**:
   * Choose a Product.
   * Choose an Environment.
   * Choose a Version.
4. Select the **Target Version**:
   * Choose a Product (can be the same or different).
   * Choose an Environment.
   * Choose a Version.
5. Click **Compare**.

### Comparison Results

The comparison results display:

| Category      | Description                                                     |
| ------------- | --------------------------------------------------------------- |
| **Added**     | Components present in the target but not in the source          |
| **Removed**   | Components present in the source but not in the target          |
| **Modified**  | Components present in both but with version or metadata changes |
| **Unchanged** | Components identical in both Versions                           |

For each changed component, the comparison shows:

| Field              | Description                       |
| ------------------ | --------------------------------- |
| **Component Name** | Name of the affected component    |
| **Source Version** | Version string in the source SBOM |
| **Target Version** | Version string in the target SBOM |
| **Change Type**    | Added, Removed, or Modified       |

### Via MCP

The `lynk-mcp` server also supports version comparison:

```
compare_versions       # Shows added, removed, and modified components between two versions
```

### Use Cases

| Scenario                   | How to Use Compare                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| **Release validation**     | Compare the previous production version with the new candidate to review dependency changes |
| **Drift detection**        | Compare the same version across Development and Production environments to identify drift   |
| **Incident response**      | Compare a known-good version with the current version to identify recently added components |
| **Upgrade tracking**       | Compare before and after a dependency upgrade to confirm expected changes                   |
| **Cross-product analysis** | Compare two related Products to understand shared vs. unique dependencies                   |

***

## PURL Lookup

PURL Lookup queries package metadata and vulnerability data for a specific Package URL (PURL). Use it to investigate components before adoption, during incident response, or for ad-hoc analysis.

### Running a Lookup

1. Navigate to the **Tools** page in the main navigation.
2. Select the **PURL** tab.
3. Enter the **Package URL** in PURL format.
4. Click **Lookup**.

### PURL Format

Package URLs follow the format: `pkg:type/namespace/name@version`

| Component   | Description                  | Example                                   |
| ----------- | ---------------------------- | ----------------------------------------- |
| `type`      | Package ecosystem            | `npm`, `pypi`, `maven`, `golang`, `nuget` |
| `namespace` | Package namespace (optional) | `@angular`, `org.apache`                  |
| `name`      | Package name                 | `express`, `log4j-core`                   |
| `version`   | Package version (optional)   | `4.18.2`, `2.17.1`                        |

**Examples:**

```
pkg:npm/%40angular/core@16.2.0
pkg:pypi/django@4.2.0
pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1
pkg:golang/github.com/gin-gonic/gin@v1.9.1
pkg:nuget/Newtonsoft.Json@13.0.3
```

### Lookup Results

The lookup returns available data for the package:

| Data                  | Description                                          |
| --------------------- | ---------------------------------------------------- |
| **Package metadata**  | Name, version, description, homepage, repository URL |
| **Vulnerabilities**   | Known CVEs affecting this package version            |
| **License**           | License expression from the package registry         |
| **Support status**    | Deprecation, archive, and maintenance indicators     |
| **Health score**      | Aggregated health score (age, community, security)   |
| **OpenSSF Scorecard** | Security posture evaluation (if available)           |
| **Version history**   | Available versions and release dates                 |

### Use Cases

| Scenario                        | How to Use PURL Lookup                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Pre-adoption review**         | Look up a package before adding it as a dependency to check for vulnerabilities and maintenance status |
| **Incident response**           | Quickly check if a specific package version is affected by a newly published CVE                       |
| **Component investigation**     | Research an unfamiliar component found in a vendor SBOM                                                |
| **License review**              | Check the license of a package before adding it to a project with specific license requirements        |
| **Dependency upgrade planning** | Compare vulnerability counts across versions to find a safe upgrade target                             |

***

## Permission Matrix

| Permission                            | Admin | Operator | Viewer |
| ------------------------------------- | :---: | :------: | :----: |
| View products (includes Tools access) |   ✓   |     ✓    |    ✓   |

Tools are read-only. All roles with product visibility can use the Tools page.

For full permission details, see [Role Management](https://docs.interlynk.io/administration/role-management).

***

## Common Misconfigurations

| Issue                                 | Symptom                                      | Fix                                                                                                                                     |
| ------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Compare shows no differences          | Identical components in both Versions        | The Versions may contain the same SBOM; verify different SBOMs were uploaded                                                            |
| PURL lookup returns no results        | "Not found" for a valid package              | Verify the PURL format is correct; the package may not be in a supported ecosystem registry                                             |
| PURL format invalid                   | Lookup fails with validation error           | Ensure the PURL follows the `pkg:type/namespace/name@version` format; URL-encode special characters (e.g., `%40` for `@` in namespaces) |
| Compare across Products not available | Cannot select a different Product for target | Select the target Product from the Product dropdown in the target section                                                               |

***

## Recommended Best Practices

* **Compare Versions before every production release** to validate that only expected dependency changes are included.
* **Use PURL Lookup for pre-adoption review** before adding new dependencies to your projects.
* **Look up PURLs during incident response** to quickly assess if your portfolio contains a vulnerable package version.
* **Compare across Environments** to detect configuration drift between development and production builds.
* **Use Compare results to validate automation rules** — confirm that automation rule changes produce the expected SBOM modifications.
* **URL-encode PURL namespaces** that contain special characters (e.g., use `%40` for `@` in npm scoped packages).