Skip to content

docs: add a consumer guide for using the reports#1329

Open
DevamShah wants to merge 1 commit into
ossf:mainfrom
DevamShah:docs/consuming-guide
Open

docs: add a consumer guide for using the reports#1329
DevamShah wants to merge 1 commit into
ossf:mainfrom
DevamShah:docs/consuming-guide

Conversation

@DevamShah

Copy link
Copy Markdown

Summary

Adds docs/consuming.md, a quickstart for consuming this dataset — scanning a
project with osv-scanner, querying osv.dev, using the raw reports offline, and
wiring detection into CI and Renovate — and links it from the README's "Get
Involved" section. Closes #110.

Problem / motivation

The repository is an excellent OSV-formatted database of malicious packages, but
the docs only cover how to contribute reports, not how to use them. #110
(open since 2023) asked for exactly this: guidance on consuming the data via
osv-scanner, osv.dev, and Renovate. Without it, a defender who finds this repo
has no documented path from "here is the dataset" to "my dependency tree is
checked against it," which limits the protective value of the data the project
works hard to curate.

Change

  • New docs/consuming.md covering five consumption paths, each with copy-paste
    commands:
    1. osv-scanner (recommended) — install, scan a directory or a lockfile,
      and read a MAL- hit in the output.
    2. osv.dev API/v1/query, /v1/vulns/{id}, and /v1/querybatch
      examples.
    3. Raw dataset, offline — clone / sparse-checkout, build a per-ecosystem
      denylist with jq, and check a single package, with an explicit note to
      exclude withdrawn reports under ./osv/withdrawn/.
    4. CI — a ready-to-use GitHub Actions workflow using the official
      google/osv-scanner-action reusable workflow.
    5. RenovateosvVulnerabilityAlerts / vulnerabilityAlerts config.
  • A "Responding to a match" section that frames a hit as incident response
    (rotate secrets, treat the host as compromised), reusing the project's own
    report language, and points back to the README's False Positives process.
  • README: a new "Consume the Reports" subsection under "Get Involved" linking to
    the guide.

The doc follows the existing docs/ style (single-# section headings, no
license header, as with docs/schema_additions.md and docs/aws_s3_auth.md)
and uses only relative links to in-repo files. No code, schema, or data changes.

Security rationale

Malicious packages map to CWE-506: Embedded Malicious
Code
— the same classification
the reports already carry — and a confirmed dependency on one is, by this
project's own definition, a full host compromise requiring incident response
(MITRE ATT&CK T1195.002, Compromise Software Supply
Chain
). Software supply chain
compromise is OWASP Top 10 2021 A06: Vulnerable and Outdated
Components

and A08: Software and Data Integrity
Failures
.
A curated malware dataset only reduces risk if defenders can apply it; this guide
turns the database into an enforceable control at the two points that matter —
pre-merge in CI and continuously via Renovate — and the "Responding to a match"
section keeps remediation aligned with proper incident response rather than a
routine version bump.

Testing / validation

Documentation-only change; validated locally against a fresh clone:

  • All relative links in the new doc and the README addition resolve to existing
    paths (CONTRIBUTING.md, osv/withdrawn/, osv/malicious/npm/,
    docs/consuming.md); the referenced README anchors (#false-positives,
    #scope) exist.
  • Every JSON snippet in the doc (the /v1/query body, the /v1/querybatch
    body, and the renovate.json) parses cleanly under jq.
  • The offline jq/grep commands the doc teaches were run against the real
    dataset: the per-ecosystem denylist command produces names, and the
    single-package lookup returns MAL-2022-6113 for shubholic-test (positive)
    and nothing for a benign name (negative). That record carries CWE-506.
  • The google/osv-scanner-action tag (v2.3.8, the latest release) and its
    osv-scanner-reusable.yml path were confirmed to exist.
  • Change scope confirmed minimal: README.md (+8 lines) and a new
    docs/consuming.md. The Go test/lint CI is unaffected (it ignores osv/**
    and docs/**).

Fixes #110

Adds docs/consuming.md, a quickstart for consuming this dataset:
scanning a project with osv-scanner, querying osv.dev, using the raw
reports offline, and wiring detection into CI and Renovate. Links it
from the README's Get Involved section.

Closes ossf#110.

Signed-off-by: Devam Shah <devamshah91@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add docs for how to make use of the OSV reports

1 participant