feat(tools/osv): query OSV.dev for vulnerability cross-references during security triage (#311)

[Kaap10]

Summary

• Implements tools/osv/ (contract:security-cross-ref) as a read-only adapter bridging the Open Source Vulnerability (OSV.dev) database to Magpie.
• Provides POSIX curl + jq operations to resolve vulnerability aliases (CVE ↔ GHSA ↔ OSV IDs), query advisories by package/version, and verify commit fixes without leaking embargoed reports.
• Closes the open contract:security-cross-ref extension point across the registry, taxonomy docs, validator, and vendor-neutrality score.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)

Test plan

• validate_tools(), validate_adapter_authoring(), and validate_capability_taxonomy_coverage() return [] (0 errors)
• vendor-neutrality-score doc block in docs/vendor-neutrality.md verified in sync (Docs in sync: True)
• git diff --check passes with zero whitespace/formatting defects
• Live OSV.dev REST API endpoints tested and verified end-to-end:
  • GET /v1/vulns/GHSA-7rjr-3q55-vv33 → resolves alias CVE-2021-45046
  • POST /v1/query with {"package": {"name": "jinja2", "ecosystem": "PyPI"}, "version": "2.11.2"} → returns 10 advisory records
  • POST /v1/query with commit SHA → returns 0 vulns (valid empty result)
  • POST /v1/querybatch with 2 packages → returns batch results (10 + 63 vulns)

RFC-AI-0004 compliance

• HITL — read-only query operations; skills propose matches to human triagers for confirmation
• Sandbox — network reach explicitly declared (api.osv.dev and osv.dev); no credentials or privileged access required
• Vendor neutrality — standard placeholders used throughout; backend is swappable via <project-config>/project.md (security_cross_ref.tool: osv)
• Conversational + correctable — per-project ecosystem and tool selection documented for adopter configuration
• Write-access discipline — strictly read-only adapter; no state mutations or external reporting
• Privacy LLM — explicit confidentiality and embargo boundaries documented per PRINCIPLES.md §3 (private reproducer commits, draft CVE copy, and embargoed tracker numbers are forbidden from being sent to OSV.dev)

Linked issues

Closes #311

Notes for reviewers (optional)

• Follows the read-only documentation-adapter pattern established by tools/cve-org/.
• Complements tools/cve-org/ (authoritative MITRE publication states) and tools/cve-tool-vulnogram/ (ASF CNA record editing) by providing ecosystem advisory packages and alias resolution graphs during security-issue-triage, security-issue-deduplicate, security-cve-allocate, and dependency-audit.

[potiuk]

Thanks — the adapter doc is clear and the confidentiality boundaries are exactly what this tool needs. Three things to fix before this lands, two nits, and one note.

Blocking

• security_cross_ref.tool / .ecosystem are documented as <project-config>/project.md keys but projects/_template/project.md does not define them (AGENTS.md § Placeholder convention: values are threaded through the project manifest). Please add them to the template, or drop the configuration section until a skill reads them.
• tool.md § Consuming skills names four skills; none of them references tools/osv today, and the PR touches no skill or eval. Please reword as "intended consumers, not yet wired" — or wire one skill together with its eval suite in a follow-up, per AGENTS.md § Reusable skills.
• docs/adapters/registry.md lists "NVD direct, GHSA direct" as open extension points without tracking issues; the registry defines an extension point as "a documented, labelled slot with a tracking issue". Open the issues, or leave the column as —.

Nits

• The PR description ticks "Python package (tools/*/ with pyproject.toml)"; this is a docs-only adapter.
• Every other tools/*/README.md starts with the SPDX comment before the doctoc block.

Note on the score: the vendor-neutrality block regenerates correctly — I re-ran vendor-neutrality-score against this branch and it is in sync — and the drop to 10/11 is the right reading of a one-vendor contract, not something to paper over.

---

This review was drafted by an AI-assisted tool and confirmed by an Apache Magpie maintainer. After you've addressed the points above and pushed an update, an Apache Magpie maintainer — a real person — will take the next look at the PR. The findings cite the project's review criteria; if you think one of them is mis-applied, please reply on the PR and a maintainer will weigh in.

More on how Apache Magpie handles maintainer review: CONTRIBUTING.md § Opening a pull request.

[Kaap10]

Thanks for the review, @potiuk! I've addressed all the feedback in the latest commit (added template config & vocabulary, reframed consuming skills as intended/not yet wired, cleaned registry extension points, fixed SPDX header, and updated the PR checklist).

[onlyarnav]

Reviewed the current changes. The adapter registration, project-template configuration, and vendor-neutrality updates look consistent, and the earlier scope concerns appear to be addressed.

One small documentation point: the commit query uses OSV’s commit field, which establishes an association with a published vulnerability but doesn’t necessarily mean the commit is the fixing commit. I’d suggest wording this as “vulnerabilities associated with a public upstream commit hash” for precision.

Other than that, I don’t see any blocking issues in the current scope.

[potiuk]

Rebased onto current main and re-reviewed. One change requested — the curl recipes cannot run under the framework's own recommended permission baseline — plus three nits inline.

All three blocking items from the previous round are genuinely fixed. I checked each against the tree rather than the description:

• security_cross_ref.tool / .ecosystem are now declared in projects/_template/project.md, with the Tools-enabled row and the TOC entry to match.
• tool.md § Consuming skills is reframed as an intended roadmap that is not yet wired, and all four skill links resolve — including skills/dependency-audit/, which I confirmed exists.
• The registry row no longer advertises untracked extension points.

Both nits are fixed too: the SPDX header now precedes the doctoc block, and the PR checklist no longer claims a Python package.

Verified rather than assumed. I ran the documented example against the live API: GHSA-7rjr-3q55-vv33 returns exactly the aliases and summary the doc prints, and looking the record up by its CVE alias also returns 200, so the "(or alias)" claim in get-vuln holds. The vendor-neutrality block regenerates correctly at 10/11, and a full prek run against the rebased branch is green, lychee included.

Two notes that are not requests.

• The new contract ships an implementation with no tools/security-cross-ref/ spec directory. That is not a rule violation — six of the eleven contracts have no directory either — so it is a maintainer call whether the NVD extension point wants something to implement against before a second backend arrives.
• Related: tool.md § When to replace this tool with another still offers "NVD Direct" as an option, while the registry now tracks no extension point for it. Worth reconciling whichever way you prefer.

The branch has been rebased onto current main and force-pushed, so CI is re-running against the post-merge tree.

---

This review was drafted by an AI-assisted tool and confirmed by an Apache Magpie maintainer. After you've addressed the points above and pushed an update, an Apache Magpie maintainer — a real person — will take the next look at the PR. The findings cite the project's review criteria; if you think one of them is mis-applied, please reply on the PR and a maintainer will weigh in.

More on how Apache Magpie handles maintainer review: CONTRIBUTING.md § Opening a pull request.

[Kaap10]

Thanks for the detailed review! All inline comments have been addressed in commit 4b48520:

1. Semantic line breaks: Broken down paragraphs and configuration blocks in tools/osv/README.md and tools/osv/tool.md into 1 sentence per line per AGENTS.md.
2. Commit query precision: Updated descriptions in docs/labels-and-capabilities.md and tools/osv/README.md to "vulnerabilities associated with a public upstream commit" per @onlyarnav's suggestion.
3. Diff hygiene: Restored original wrapping on line 171 of docs/vendor-neutrality.md to keep the diff minimal.
4. Reconciled NVD Direct: Removed the NVD Direct bullet from tool.md to align with the registry entry (—).

Regarding the curl sandbox recipes and vetted-ops dispatcher: let's track that in a follow-up issue across both tools/osv/ and tools/cve-org/ so this PR stays strictly focused.

[potiuk]

Approving. Everything from the previous two rounds is fixed, and I've taken the two remaining items myself as fixups on this branch rather than send you a fourth round for six lines.

Verified against the tree, not the description:

• Semantic line breaks — longest line in tools/osv/README.md is now 306 characters, down from 627, one sentence per line.
• The unrelated reflow in docs/vendor-neutrality.md is restored to a two-line change.
• commit fix references is reworded to "vulnerabilities associated with a public upstream commit" in both docs/labels-and-capabilities.md and the README lead — which also closes the precision point onlyarnav raised.
• "NVD Direct" is gone from When to replace this tool, reconciling with the registry.

I withdraw my own blocking finding from round two. I said the curl recipes couldn't run under the framework's recommended permission baseline. The Bash(curl *) deny is real, but tools/cve-org/tool.md — the precedent this adapter explicitly follows — ships the same bare curl … | jq recipes with no caveat, and no documented rule requires a tool doc to route HTTP elsewhere. That was me holding this PR to a bar the repository doesn't apply. The deny-versus-adapter-recipes inconsistency is real but repo-wide, and belongs in its own issue covering both adapters. My calibration in that thread was also wrong: I said 318 characters was the longest line in any tools/*/README.md; it's 2114.

Two fixups pushed, explained inline. I also rebased the branch onto current main and force-pushed, so CI re-runs against the post-merge tree — the same thing I did in round two.

Thanks for the patience through three rounds.

---

This review was drafted by an AI-assisted tool and confirmed by an Apache Magpie maintainer. The maintainer approving this PR has read the findings and signed off. If something feels off, please reply on the PR and a maintainer will follow up.

More on how Apache Magpie handles maintainer review: CONTRIBUTING.md § Opening a pull request.

[Kaap10]

Follow-up tracking issue created as discussed: #1320. Thanks again for the review and merge, @potiuk!