SBOM Diff Reporter

Compare normalized SBOM components by stable name while reporting versions, package URLs, licenses, scope, hashes, additions, and updates.

Use this actor to turn structured records or supported text evidence into a normalized Apify dataset. Each paid row represents one SBOM component; blocked and no-result diagnostics remain free so invalid evidence does not look like successful extraction.

What It Returns

Every dataset row includes stable source and record identifiers, a checked timestamp, current and previous hashes, a change classification, issue codes, a concise recommendation, the charged event name, and strict actor-specific data. The data object contains only fields relevant to SBOM component records.

Change classifications are observed when no prior snapshot is supplied, added for a new key, updated when normalized metadata changed, and unchanged when the normalized record matches. Diagnostic rows use diagnostic, contain no paid event name, and explain how to supply usable evidence.

Input Sources

• Inline currentText, text, or html for deterministic runs.
• items for structured current records and previousItems for structured history.
• previousText for snapshot comparison.
• targets to process several bounded sources in one run.
• urls or sourceUrl only when allowUrlFetch is explicitly enabled.

Public URL retrieval accepts HTTP and HTTPS only. It rejects credentials, redirects, localhost, private and reserved addresses, and DNS results that resolve privately. Responses have timeout and streamed byte limits. Defaults use bounded records from the stated public source, process one target, and make no network request.

Quick Start

{
  "sourceId": "cyclonedx-dropwizard-sbom",
  "sourceUrl": "https://raw.githubusercontent.com/CycloneDX/bom-examples/master/SBOM/dropwizard-1.3.15/bom.json",
  "items": [
    {
      "componentId": "pkg:maven/com.fasterxml.jackson.core/jackson-annotations@2.9.10",
      "name": "jackson-annotations",
      "version": "2.9.10",
      "purl": "pkg:maven/com.fasterxml.jackson.core/jackson-annotations@2.9.10?type=jar",
      "licenses": [
        {
          "license": {
            "id": "Apache-2.0"
          }
        }
      ],
      "hashes": [
        {
          "alg": "SHA-256",
          "content": "c876f2e85d0f108a34cdd11ccc9d8d7875697367efc75bf10a89c2c26aee994c"
        }
      ]
    }
  ],
  "text": "",
  "currentText": "",
  "previousText": "",
  "maxItems": 1,
  "maxRecordsPerTarget": 5,
  "maxTextBytes": 250000,
  "fetchTimeoutMs": 15000,
  "allowUrlFetch": false,
  "includeDigest": false,
  "includeReport": true,
  "dryRun": false,
  "debug": false
}

Set maxItems to cap source targets, maxRecordsPerTarget to cap normalized records, maxTextBytes to cap each supplied or fetched body, and fetchTimeoutMs to cap public retrieval time. dryRun validates input without charges or dataset output.

Data Quality

The parser normalizes and deduplicates SBOM component records by the actor's stable identity field. It never fabricates missing titles, dates, authors, links, guests, journals, or categories. Missing values stay null or empty and produce explicit issue codes.

Possible issue codes include: missing-component-name, missing-version, missing-license, review-license, source-unavailable. Review warning rows before using them in downstream publishing, outreach, reporting, or alerting.

Reports And Digests

The default key-value store receives a results JSON file, summary JSON, and Markdown report after the corresponding report charge succeeds. Recurring monitor actors also produce JSON and Markdown change digests. Report artifacts are skipped when the run budget cannot cover the report event.

Pay Per Event

Event	Price	Purpose
actor-start	$0.00500	Sbom Diff Reporter Actor Start
operation-tested	$0.00650	Sbom Diff Reporter Operation Tested
contract-rule-checked	$0.00390	Sbom Diff Reporter Contract Rule Checked
report-generated	$0.05000	Sbom Diff Reporter Report Generated

Platform usage is included in these event prices. The actor charges before paid dataset rows or report artifacts are written. If Apify rejects a charge because the run limit is reached, the actor records billing status and stops before the affected paid output.

Operational Guidance

Use stable sourceId values across scheduled runs, retain the prior normalized source snapshot, and compare changes by recordId and changeType. Start with one source and inspect the dataset before increasing limits. Keep URL retrieval disabled when inline or structured evidence is available.

How Parsing Works

This actor accepts structured records or supported text evidence. Structured records take priority when they are supplied. Otherwise, the parser reads the source format directly, normalizes whitespace and identifiers, resolves supported links, removes duplicate identities, and stops at maxRecordsPerTarget.

The actor-specific data fields are: componentId, name, version, purl, licenses, scope, hashCount, issues. These fields are validated by the strict dataset schema. Unknown top-level output fields and unknown fields inside data are not part of the contract.

Record identity is based on the strongest stable public identifier available for each SBOM component. Links and official IDs are preferred; a deterministic content identity is used only when the source omits a stronger identifier. Reordering a feed or inserting a new record does not turn unchanged historical records into updates.

Comparison Workflow

1. Save the prior source body or structured records after a successful run.
2. Supply that evidence as previousText or previousItems on the next run.
3. Supply the current evidence through currentText, items, or an explicitly enabled public URL.
4. Read added and updated rows as detected events. unchanged rows preserve the current normalized inventory.
5. Store the current source evidence for the following run.

Comparisons use normalized record hashes, not timestamps generated by the actor. This keeps reruns deterministic and prevents a new checkedAt value from creating false changes.

Scheduling And Delivery

For scheduled monitoring, use one stable target per public source and conservative caps. Send alerts from rows whose changeType is added or updated; keep all rows in the dataset when a complete current inventory is required. The JSON summary is suitable for automation, while the Markdown report and optional digest are suitable for review or delivery.

Do not treat an empty paid dataset as a successful zero-change result without checking diagnostics. A blocked diagnostic indicates missing evidence, disabled URL retrieval, an invalid public URL, a private address, a timeout, an oversized response, or an unsupported source shape.

Limits And Failure Handling

• maxItems limits targets before retrieval or analysis.
• maxRecordsPerTarget limits normalized records per target.
• maxTextBytes limits inline and fetched source bodies.
• fetchTimeoutMs limits each explicitly enabled public request.
• Redirects and credentialed URLs are rejected.
• Charge-limit failures stop before the affected paid rows or report artifacts.
• Parser failures produce explicit diagnostics rather than invented records.

Use debug only when investigating source parsing or billing decisions. Avoid logging source bodies that may contain information you do not intend to retain.

Only process public, authorized, or owned sources. Do not use this actor to bypass access controls, collect private data, or make unsupported legal or compliance claims.