# 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](/administration/role-management.md).

***

## 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.interlynk.io/product-guides/insights/tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.