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

docs/adapters/registry.md

@@ -56,7 +56,7 @@ extension point = a documented, labelled slot with a tracking issue.
 | [`tools/vcs`](../../tools/vcs/) | Git, Mercurial, Fossil | Subversion [\#602](https://github.com/apache/magpie/issues/602), Jujutsu [\#603](https://github.com/apache/magpie/issues/603), Perforce [\#605](https://github.com/apache/magpie/issues/605) |
 | Forge / tracker | [`github`](../../tools/github/), [`jira`](../../tools/jira/), [`bitbucket`](../../tools/bitbucket/) `partial-read-only` foundation, [`sourcehut`](../../tools/sourcehut/), [`fossil`](../../tools/fossil/) | GitLab [\#305](https://github.com/apache/magpie/issues/305), Forgejo/Gitea [\#310](https://github.com/apache/magpie/issues/310), Pagure [\#312](https://github.com/apache/magpie/issues/312), deeper Bitbucket/Jira coverage [\#606](https://github.com/apache/magpie/issues/606), Bugzilla [\#302](https://github.com/apache/magpie/issues/302) |
 | Agent harness | Claude Code, [Codex](codex.md) `experimental` ([#313](https://github.com/apache/magpie/issues/313)), [Gemini CLI](gemini.md) `experimental` ([#314](https://github.com/apache/magpie/issues/314)), [Local LLM (Ollama / llama.cpp / vLLM)](local-llm.md) ([#315](https://github.com/apache/magpie/issues/315)), [Cursor](cursor.md) ([#316](https://github.com/apache/magpie/issues/316)), [Goose](goose.md) `guide only` ([#319](https://github.com/apache/magpie/issues/319)), [Aider](aider.md) `guide only` ([#317](https://github.com/apache/magpie/issues/317)), [GitHub Copilot](copilot.md) `guide only` ([#318](https://github.com/apache/magpie/issues/318)) | Amazon Q [#320](https://github.com/apache/magpie/issues/320)–OpenHands [#322](https://github.com/apache/magpie/issues/322) |
-| Security cross-ref | — | OSV.dev [#311](https://github.com/apache/magpie/issues/311) |
+| Security cross-ref | [`tools/osv`](../../tools/osv/) | — |
 
 ## In-tree organizations
 

docs/labels-and-capabilities.md

@@ -139,6 +139,7 @@ framework substrate:
 | `contract:report-relay` | contract | Inbound security-report relay detection. |
 | `contract:scan-format` | contract | Security-scanner report parsing. |
 | `contract:project-metadata` | contract | Governance rosters / people / releases. |
+| `contract:security-cross-ref` | contract | Vulnerability database / cross-reference alias lookup (OSV.dev / NVD). |
 | `substrate:analytics` | substrate | Read-only metrics / dashboards / renderers. |
 | `substrate:sandbox` | substrate | Agent isolation, egress control, settings audit. |
 | `substrate:action-guard` | substrate | Deterministic pre-tool-use command guards. |
@@ -321,6 +322,7 @@ or a contract-free mix of substrates (e.g. `tools/spec-inventory` is
 | [`tools/mail-patch`](../tools/mail-patch/) | `contract:change-request` | `[PATCH]`-mail change-request backend: a `[PATCH]` thread on `dev@` as the proposal, reviewed via drafted replies (`contract:mail-create`), read via `contract:mail-archive`, landed via `contract:source-control` (`svn patch` + `svn commit`). Implements the `tools/change-request/` contract |
 | [`tools/mail-source`](../tools/mail-source/) | `contract:mail-source` | Mail-source backend abstraction (mbox / IMAP / Mailman 3) feeding a uniform inbound thread/message view to the intake pipeline |
 | [`tools/maildir`](../tools/maildir/) | `contract:mail-source` + `contract:mail-create` | Local **Maildir** backend (Vendor: Maildir) — the offline, credential-free counterpart of `tools/gmail`. Implements `mail-create` by filing editable outbound drafts into a local Maildir for any mail client to send (never sends itself); its `mail-source` side is the local mbox/Maildir archive reader (`tools/mail-source/mbox`). The second, non-Google `mail-create` backend — closes the outbound-mail vendor-neutrality gap |
+| [`tools/osv`](../tools/osv/) | `contract:security-cross-ref` | OSV.dev vulnerability cross-reference client (Vendor: OSV.dev): queries vulnerability records, alias cross-references (CVE ↔ GHSA ↔ OSV IDs), affected package versions, and vulnerabilities associated with a public upstream commit via OSV.dev REST API v1 |
 | [`tools/ponymail`](../tools/ponymail/) | `contract:mail-archive` + `contract:mail-source` | PonyMail public mail-archive substrate (ASF `lists.apache.org`); implements the `tools/mail-archive/` contract for archive reads and the `tools/mail-source/` contract for inbound list-traffic ingestion |
 | [`tools/scan-format`](../tools/scan-format/) | `contract:scan-format` | Adapter contract for security-scanner report formats (ASVS reference); reads a scan's finding index + per-finding evidence for the `security-issue-import-from-scan` pipeline. |
 | [`tools/permission-audit`](../tools/permission-audit/) | `substrate:sandbox` | Audit + atomically edit Claude Code `permissions.allow[]` entries; backs `/magpie-setup verify --apply-permission-audit` (check 8d) |

docs/vendor-neutrality.md

@@ -171,8 +171,8 @@ behind [`tools/cve-tool`](../tools/cve-tool/) (the ASF Vulnogram adapter
 reference), inbound report relays behind
 [`tools/forwarder-relay`](../tools/forwarder-relay/), scanner formats
 behind [`tools/scan-format`](../tools/scan-format/), and an OSV.dev
-vulnerability cross-reference bridge is the open extension point
-([#311](https://github.com/apache/magpie/issues/311)).
+vulnerability cross-reference client [`tools/osv`](../tools/osv/)
+implements the `contract:security-cross-ref` capability.
 
 The distinction Magpie enforces: **vendor-specific *integrations* are
 expected and welcome; vendor-specific *workflows* are forbidden.** A
@@ -564,7 +564,7 @@ generated block below.
 
 <!-- BEGIN vendor-neutrality-score — generated by `uv run --project tools/vendor-neutrality-score vendor-neutrality-score --markdown`; do not edit by hand -->
 
-**Overall vendor-neutrality score: 10/10 capability contracts (100%).** Generated by [`tools/vendor-neutrality-score`](../tools/vendor-neutrality-score/); re-run it to refresh this section.
+**Overall vendor-neutrality score: 10/11 capability contracts (91%).** Generated by [`tools/vendor-neutrality-score`](../tools/vendor-neutrality-score/); re-run it to refresh this section.
 
 | Capability contract | Neutral? | Class | Backends today | Basis |
 |---|---|---|---|---|
@@ -578,6 +578,7 @@ generated block below.
 | `contract:report-relay` | ✅ | agnostic | — | vendor-neutral by construction — one spec serves every backend |
 | `contract:scan-format` | ✅ | agnostic | — | vendor-neutral by construction — one spec serves every backend |
 | `contract:project-metadata` | ✅ | single-org | ASF | single-organisation capability (ASF); no vendor choice to make |
+| `contract:security-cross-ref` | ❌ | vendor-backed | OSV.dev | only 1 backend vendor (OSV.dev); needs 1 more |
 
 **Per-skill assessment: 75/75 skills carry no vendor lock-in.** A skill is *capability-pure* when it names no backend at all, *portable* when every backend it names has an alternative (its contract is green), and *vendor-coupled* only when it reaches for a backend that is the sole implementation of a capability.
 

projects/_template/project.md

@@ -24,6 +24,7 @@
     - [Mail provider](#mail-provider)
     - [Archive system](#archive-system)
     - [Project metadata](#project-metadata)
+    - [Security cross-reference](#security-cross-reference)
     - [Tracker](#tracker)
     - [Scope detection](#scope-detection)
     - [Release process](#release-process)
@@ -121,6 +122,7 @@ for ASF projects) is org-level — inherited from your organization's
 | Source control (VCS) | `github` (Git) — replaceable with a non-Git VCS | [`../../tools/github/source-control.md`](../../tools/github/source-control.md) | `upstream_repo`, `default_branch`; for a non-Git VCS declare the sibling tool + its working-copy URL |
 | Inbound email / drafts | `<one or more mail-source backends>` | [`../../tools/mail-source/contract.md`](../../tools/mail-source/contract.md) (abstract) + per-backend adapter dirs (`tools/gmail/`, `tools/ponymail/`, `tools/mail-source/imap/`, `tools/mail-source/mbox/`, ...) | See [Mail sources](#mail-sources) below — declare each backend's role (primary / preferred-for-`<op>` / fallback / optional) and `mandatory` flag |
 | CVE allocation + record mgmt | *org-level* — inherited from `organizations/<org>/organization.md → cve_authority.tool`; for ASF: `vulnogram` ([`tools/cve-tool-vulnogram/`](../../tools/cve-tool-vulnogram/)), for independent: `mitre-form` | — | override in [CVE authority](#cve-authority) only if this project differs from its org |
+| Security cross-ref | `osv` | [`../../tools/osv/`](../../tools/osv/) | `security_cross_ref.tool`, `security_cross_ref.ecosystem` |
 | Project metadata (rosters / people / releases) | *org-level* — inherited from `organizations/<org>/organization.md → project_metadata.kind`; for ASF: `apache-projects` ([`tools/apache-projects/`](../../tools/apache-projects/)), for independent: `none` | — | override in [Project metadata](#project-metadata) only if this project differs from its org |
 | Release comms | TODO: the backend that carries release announcements — for ASF: `dev_list` / `announce_list` / `users_list`; for GitHub Releases leave blank | — | whichever release-comms keys the org default or per-project override declares |
 
@@ -361,6 +363,19 @@ Org-level — inherited from your organization's `project_metadata` block
 (roster / people / releases backend + whether it is mandatory). Override
 here only if this project uses a different metadata source.
 
+### Security cross-reference
+
+Vulnerability cross-referencing and alias lookup configuration (OSV.dev / NVD).
+Declare this project's default package ecosystem and tool adapter:
+
+```yaml
+security_cross_ref:
+  # Tool adapter: osv (tools/osv/) | none
+  tool: osv
+  # Default package ecosystem for vulnerability queries (e.g. PyPI, Maven, npm, Go, crates.io)
+  ecosystem: PyPI
+```
+
 ### Tracker
 
 The tracker `platform`, `board`, `visibility`, and `skill_url_template`

tools/egress-gateway/src/egress_gateway/allowlist.py

@@ -46,6 +46,9 @@
         "cve.org",
         "www.cve.org",
         "cveawg.mitre.org",
+        # OSV.dev REST API (tools/osv). The osv.dev web UI is a browser
+        # destination, not a tool egress, so it is deliberately not listed.
+        "api.osv.dev",
         "issues.apache.org",
     }
 )

tools/egress-gateway/tests/test_allowlist.py

@@ -41,6 +41,7 @@
         "files.pythonhosted.org",
         "nvd.nist.gov",
         "cveawg.mitre.org",
+        "api.osv.dev",
     ],
 )
 def test_allowed_hosts(host: str) -> None:

tools/egress-gateway/tool.md

@@ -138,6 +138,7 @@ The declared egress surfaces as of this writing:
 | `gmail` | `contract:mail-source + contract:mail-create + contract:mail-archive` | Gmail API |
 | `jira`, `jira-patch` | `contract:tracker` / `contract:change-request` | Jira REST API |
 | `maildir`, `mail-source`, `mail-archive`, `mail-patch` | `contract:mail-*` | local maildir / IMAP |
+| `osv` | `contract:security-cross-ref` | OSV.dev REST API |
 | `ponymail` | `contract:mail-archive + contract:mail-source` | PonyMail REST API |
 | `sourcehut` | `contract:tracker + contract:source-control + contract:mail-archive` | sourcehut API |
 | `vcs` | `contract:source-control` | generic VCS host |

tools/osv/README.md

@@ -0,0 +1,38 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [`tools/osv/`](#toolsosv)
+  - [Prerequisites](#prerequisites)
+  - [Configuration](#configuration)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# `tools/osv/`
+
+**Capability:** contract:security-cross-ref
+
+**Kind:** implementation
+
+**Vendor:** OSV.dev
+
+OSV.dev vulnerability cross-reference client.
+Queries the [OSV.dev REST API v1](https://api.osv.dev/v1/) for vulnerability records, aliases (CVE ↔ GHSA ↔ OSV IDs), affected package versions, and vulnerabilities associated with a public upstream commit.
+Complements [`tools/cve-org/`](../cve-org/) and [`tools/cve-tool-vulnogram/`](../cve-tool-vulnogram/) by providing cross-ecosystem vulnerability records for intended triage consumers (`security-issue-triage`, `security-issue-deduplicate`, `security-cve-allocate`, and `dependency-audit` — not yet wired).
+See [`tool.md`](tool.md) for endpoint recipes, payload structures, and confidentiality boundaries.
+
+## Prerequisites
+
+- **Runtime:** None of its own — this directory documents a read-only adapter; queries are `curl` + `jq` recipes (see `tool.md`).
+- **CLIs:** `curl` and `jq`.
+- **Credentials / auth:** None — OSV.dev is a public vulnerability database with an open, unauthenticated REST API.
+- **Network:** `api.osv.dev` (OSV.dev REST API v1) and `osv.dev` (public web UI).
+
+## Configuration
+
+Adopters select this backend with `<project-config>/project.md` → `security_cross_ref.tool: osv` when performing automated vulnerability cross-referencing.
+The default ecosystem (e.g. `PyPI`, `Maven`, `npm`, `Go`, `crates.io`, `NuGet`, `RubyGems`, `Packagist`) can be configured via `security_cross_ref.ecosystem`.
+The adopter-facing configuration block is declared in [`projects/_template/project.md`](../../projects/_template/project.md#security-cross-reference).