docs: add a consumer guide for using the reports#1329
Open
DevamShah wants to merge 1 commit into
Open
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
docs/consuming.md, a quickstart for consuming this dataset — scanning aproject 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
docs/consuming.mdcovering five consumption paths, each with copy-pastecommands:
and read a
MAL-hit in the output./v1/query,/v1/vulns/{id}, and/v1/querybatchexamples.
denylist with
jq, and check a single package, with an explicit note toexclude withdrawn reports under
./osv/withdrawn/.google/osv-scanner-actionreusable workflow.osvVulnerabilityAlerts/vulnerabilityAlertsconfig.(rotate secrets, treat the host as compromised), reusing the project's own
report language, and points back to the README's False Positives process.
the guide.
The doc follows the existing
docs/style (single-#section headings, nolicense header, as with
docs/schema_additions.mdanddocs/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:
paths (
CONTRIBUTING.md,osv/withdrawn/,osv/malicious/npm/,docs/consuming.md); the referenced README anchors (#false-positives,#scope) exist./v1/querybody, the/v1/querybatchbody, and the
renovate.json) parses cleanly underjq.jq/grepcommands the doc teaches were run against the realdataset: the per-ecosystem denylist command produces names, and the
single-package lookup returns
MAL-2022-6113forshubholic-test(positive)and nothing for a benign name (negative). That record carries CWE-506.
google/osv-scanner-actiontag (v2.3.8, the latest release) and itsosv-scanner-reusable.ymlpath were confirmed to exist.README.md(+8 lines) and a newdocs/consuming.md. The Go test/lint CI is unaffected (it ignoresosv/**and
docs/**).Fixes #110