# OSV Package Advisory Monitor

Monitor known OSV advisories for explicit package versions. Compare affected ranges, fix events and source corrections, with bounded checks of previously saved IDs for explicit withdrawals.

Canonical product page: https://mayd-it.com/data-tools/actors/osv-package-advisory-monitor/
Public Actor: https://apify.com/maydit/osv-package-advisory-monitor

## Example input

```json
{
  "packages": [
    {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.20"
    }
  ],
  "maxResults": 5,
  "maxAdvisoriesPerPackage": 20
}
```

## Full guide

![OSV Package Advisory Monitor — illustrative watchlist workflow](https://api.apify.com/v2/key-value-stores/cCyrofyNNh9lwffXB/records/osv-package-advisory-monitor-a6b1ba75260e.png?signature=8mxDG7KwZPOaIIZwPt0W)

## Keep a reviewable package advisory watchlist

Give this Actor the package versions your workflow tracks. It queries the official OSV API and exports source advisory IDs, affected ranges, published fix events and saved corrections. Repeated comparisons also check previously saved IDs for explicit withdrawal evidence.

**One result is one package/version plus advisory observation.** A match reports OSV's evidence; it does not prove your running application is exploitable, inspect installed code or certify a version as safe.

[First run](#try-a-small-watchlist) · [Output preview](#output-preview) · [Saved comparisons](#save-a-comparison-baseline) · [Pricing](#pricing)

## Try a small watchlist

Paste this exact input into Console's JSON editor. No source API key is required. These historical examples demonstrate the fields; they are not recommendations to install these versions.

```json
{
  "packages": [
    {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.20"
    }
  ],
  "maxResults": 5,
  "maxAdvisoriesPerPackage": 20
}
```

Open **Dataset** for saved observations and **Run report** for coverage. **SUMMARY** is the machine-readable record. Empty API input and the Console prefill use the documented sample inventory; the maximum is a cap, not a promised result count.

## Output preview

| Review question | Fields | Interpretation |
| --- | --- | --- |
| Which inventory entry? | `watchKey`, `ecosystem`, `packageName`, `requestedVersion` | Stable identity of the exact normalized package/version query |
| Which source advisory? | `advisoryId`, `aliases`, `advisoryUrl` | Source IDs remain separate; aliases do not prove two records should be merged |
| Why was it returned? | `queryMatched`, `watchStatus`, `matchingAffected` | OSV query match or a checked previously saved ID; not code-level reachability proof |
| What versions are mentioned? | `fixedVersionEvents`, `matchingAffected` | Publisher fix events and range evidence, not an upgrade recommendation or a universally safe version |
| Was it withdrawn? | `withdrawnAt`, `withdrawalNewlyObserved` | Explicit publisher withdrawal timestamp, never an inference from absence |
| What changed? | `changedFields`, `previous`, `addedAliases`, `addedFixedVersionEvents` | Observed record corrections against the last confirmed saved row |
| Where and when? | `sourceUrl`, `publishedAt`, `modifiedAt`, `observedAt` | API evidence, publisher timestamps and retrieval time |

`watchStatus` is `query_match`, `withdrawn` or `not_in_current_query`. The last value means a previously saved ID was retrieved successfully but was absent from a completed current query. It does **not** mean the package is fixed. Raw source severity vectors are preserved in `severity`; no severity score or exploit prediction is invented. Empty optional arrays and null optional fields are honest missing source metadata.

## Inspect a second inventory

Inspect known OSV advisory records matching a specific Maven Log4j version, with publisher ranges and fix events.

```json
{
  "packages": [
    {
      "ecosystem": "Maven",
      "name": "org.apache.logging.log4j:log4j-core",
      "version": "2.14.1"
    }
  ],
  "maxResults": 5,
  "maxAdvisoriesPerPackage": 20
}
```

## Save a comparison baseline

Save current lodash advisory evidence and compare later source corrections, ranges and explicit withdrawals.

```json
{
  "packages": [
    {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.20"
    }
  ],
  "comparePrevious": true,
  "snapshotName": "lodash-advisory-review",
  "maxResults": 50,
  "maxAdvisoriesPerPackage": 20
}
```

1. Run once to save `new` observations.
2. Repeat with the same inventory, `snapshotName` and named history store. Rows become `changed` or `unchanged`, with `previous`, `previousObservedAt` and `changedFields`.
3. Add `onlyChanges: true` to suppress unchanged source observations. This also enables comparison. A healthy repeat can save zero rows.
4. In Sheets, Make or n8n, wait for completion, check SUMMARY, then upsert by `observationId`. Keep the run ID for replay and deduplicate deliveries with `observationId + contentHash`.

The versioned history scope contains the exact sorted inventory and namespace. Changing that inventory starts a separate comparison. Only confirmed dataset writes advance history. Errors, unsaved capped rows and unchanged skips preserve prior observations; missing sources never imply deletion. Use **one writer per scope**: a pre-commit check detects existing concurrent changes, but is not an atomic lock. The named store holds at most 20,000 saved identities per scope.

The Actor supplies observations and a report. You configure schedules, alerts and downstream accounts. A history failure can leave valid saved rows; inspect `historyUpdated` and `failedSources.history`. Comparisons cover last saved observations, not every upstream change between runs.

## Coverage and interpretation

- **Exact inventory:** up to 20 package/version entries from npm, PyPI, Maven, Go, crates.io or RubyGems. PyPI names use normalized lowercase hyphen spelling. No repository cloning, transitive dependency resolution, lockfile parsing or installed-code inspection.
- **Publisher matching:** OSV performs version matching, documented as fuzzy upstream matching. Returned records must have matching package evidence. A successful no-match query saves zero rows and does not certify safety.
- **Bounded results:** default 20 current advisories and three query pages per package; maximum 100 and ten. Per-package source truncation is marked incomplete. The separate `maxResults` output cap is an intentional sample and can leave selected output or packages unreached.
- **Withdrawal checks:** OSV excludes withdrawn records from query results but retains individual records by ID. Comparison runs check up to 100 absent, previously saved IDs per package after current rows. Incomplete pagination, output limits, unavailable IDs or deadlines leave explicit coverage gaps. No missing ID becomes a removal/resolution event.
- **Evidence only:** no exploit instructions, security certification, installation, remediation action or automatic upgrade. The official free OSV-Scanner is a strong option for repository and SBOM scanning.
- **Access and budgets:** public documented APIs only, sequential requests, pinned public DNS and no cross-host redirect following. Responses are capped at 2 MiB. One bounded retry is allowed for 502/503/504; rate/access refusals are reported without bypass.
- **Run bounds:** `maxRunSeconds` defaults to 240 and also respects the platform deadline minus 25 seconds. Configure Apify's maximum total charge as well as `maxResults`.

SUMMARY includes saved/observed counts, per-source coverage, unreached entries, history outcome and time/spending limits. Intentional output caps are bounded samples. Source, source-window, time and history failures are partial or failed. All-source or all-output failures fail the run. Errors and no-match diagnostics are never paid data rows.

## Pricing

Base FREE-tier rate: **$2 per 1,000 saved observations**, plus the listed **Actor Start** charge. The [Pricing tab](https://apify.com/maydit/osv-package-advisory-monitor/pricing) is authoritative for your plan. Saved unchanged observations are billable; unchanged rows suppressed by `onlyChanges` have no dataset-item charge. Platform and storage charges may apply under your plan.

## Sources and support

[OSV query API](https://google.github.io/osv.dev/post-v1-query/) · [Individual record API](https://google.github.io/osv.dev/get-v1-vulns/) · [Withdrawal and source behavior](https://google.github.io/osv.dev/faq/) · [OSV schema](https://ossf.github.io/osv-schema/) · [OSV-Scanner](https://google.github.io/osv-scanner/)

OSV aggregates records from multiple publishers. Retain the advisory and reference URLs when using exported evidence. This community Actor is not affiliated with Google, OSV or the upstream advisory publishers.

For help, open **Issues** with the run URL and expected public field, or contact **bmay@mayd-it.com**. Remove credentials and private inventory information before posting.