Component Change Monitoring API

Important
This API is only available in SaaS Firewall. It is not supported in other Sonatype deployments.

The Component Catalog API enables monitoring of software components for security vulnerabilities, malware threats, and license obligations. Sonatype maintains a catalog of your components and provides updates when changes are detected in malicious state, vulnerability information, or licensing requirements.

Note
The Component Catalog API requires activation. Contact your Sonatype account team to enable access for your instance.

Overview

The Component Catalog API provides an automated monitoring approach as an alternative to full nightly re-evaluations of all components. When enabled, Sonatype:

Maintains a catalog of your registered components.
Evaluates components on a recurring basis (every 24 hours) for changes in malicious state, vulnerability information, and license obligations.
Provides updates through the API only when changes are detected.

This approach is more efficient than nightly full re-evaluations, particularly for large component catalogs.

Important
To ensure optimal performance, Sonatype initially limits the catalog size. Monitor the count of cataloged components and contact Sonatype if you need to increase limits based on performance validation.

Workflow

The typical workflow for using the Component Catalog API involves:

Submit Components: Add components to your catalog using the configuration API with either SHA-1 hash or Package URL (purl) identifiers.
Automatic Evaluation: Sonatype evaluates cataloged components on a recurring schedule (every 24 hours) for changes in malware, vulnerabilities, and licensing.
Retrieve Updates: Poll the API for unacknowledged changes (recommended: daily polling).
Acknowledge Updates: Confirm receipt and processing of updates to remove them from the pending queue.
Manage Catalog: Remove stale components when the catalog reaches capacity limits.

Updates are provided for the following data points:

Malware: Changes in malicious state and malware detection status.
Vulnerabilities: New or updated security vulnerability information (CVE data, CVSS scores).
Licensing: Changes in license obligations and requirements.

Endpoints

Add component to Catalog

POST /api/v2/malware-defense/component-change-detection/configuration

Adds a component to your catalog for monitoring. Components can be identified by SHA-1 hash or Package URL (purl).

Parameters:

hash: SHA-1 hash of the component (40-character hexadecimal string)
packageUrl: Package URL (purl) identifier conforming to the purl specification (e.g., pkg:maven/group/artifact@version)

Curl Example (by Hash)

curl -X POST "https://your-instance.sonatype.com/api/v2/malware-defense/component-change-detection/configuration" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "356a192b7913b04c54574d18c28d46e6395428ab"
  }'

Curl Example (by Package URL)

curl -X POST "https://your-instance.sonatype.com/api/v2/malware-defense/component-change-detection/configuration" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "packageUrl": "pkg:maven/com.example/my-component@1.0.0"
  }'

Retrieve Component Updates

GET /api/v2/component-change-detection/event

Retrieves all unacknowledged component changes from your catalog. This endpoint returns updates for malware, vulnerabilities, and licensing changes that have been detected since the last acknowledgment.

Curl Example

curl -X GET "https://your-instance.sonatype.com/api/v2/component-change-detection/event" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response Fields

Field	Description
`updates`	Array of component change events
`componentId`	Unique identifier for the component in the catalog
`packageUrl`	Package URL identifier (if provided during registration)
`hash`	SHA-1 hash (if available)
`eventType`	Type of change: `vulnerability`, `malware`, or `license`
`eventDate`	ISO 8601 timestamp of when the change was detected
`details`	Event-specific details (structure varies by eventType)
`totalCount`	Total number of unacknowledged updates available
`retrievedAt`	ISO 8601 timestamp of when this response was generated

Acknowledge Component Updates

POST /api/v2/component-change-detection/event

Acknowledges that updates have been processed. All updates with event dates older than the specified date will be removed from the pending queue.

Note
Regularly acknowledge processed updates to keep your update queue manageable. It's recommended to acknowledge updates after successfully processing and storing them in your system. This prevents the queue from growing indefinitely and ensures you only receive new updates on subsequent API calls.

Parameters: acknowledgedDate: ISO 8601 timestamp - updates with event dates before this timestamp will be removed from the queue

Curl Example

curl -X POST "https://your-instance.sonatype.com/api/v2/component-change-detection/event" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "acknowledgedDate": "2025-02-01T00:00:00.000Z"
  }'