[Feature] Machine-readable project metadata, so a third party can attest without asking #555

New issue

Closed

opened 2026-07-22 13:44:35 +00:00 by brenno · 0 comments

brenno commented

2026-07-22 13:44:35 +00:00

Owner

One recommendation in proposals/gen-two-tier-approach.md (orcwg/cra-attestations) is easy to miss and is the most useful idea in the document. Attestations may be issued by unaffiliated third parties — researchers, manufacturers, national bodies — and for that to work without pestering the maintainer, the project's information should be public in a form that lets third parties generate an attestation through machine automatable means.

Why this is worth doing even though we already publish everything. All the facts exist: SECURITY.md, CONTRIBUTING.md, LICENSE.md, sbom/, docs/BUILD.md, docs/CHECKS.md. They exist as prose in a dozen files, in two languages, written for humans. A downstream user who wants to know our disclosure terms has to read SECURITY.md and tool/check_service_norms.dart. That is a burden we impose on them and, when they ask by e-mail, a burden that comes straight back to us.

The form. OpenSSF Security Insights is the existing specification for this: a SECURITY-INSIGHTS.yml in the repository root carrying the project's contacts, disclosure terms, dependency policy, build and release facts, and links to the artefacts. It is machine-readable, versioned, and already consumed by third-party tooling — which beats inventing our own JSON. Check the current spec version before adopting; it has moved.

What this issue delivers

SECURITY-INSIGHTS.yml (or whatever the current spec names it), filled in from the files that already hold the facts.
A gate that keeps it true. A metadata file that silently drifts from SECURITY.md is worse than none, because it is the copy a machine reads. This repository's habit applies: a test that fails when the two disagree — at minimum the security contact, the disclosure terms, and the licence. Same reflex as docs_registration_test and sbom_test.
A pointer from COMPLIANCE.md (#549) and SECURITY.md, so a human finds it too.

Second-order benefit. Writing the facts in a schema forces the gaps into the open — support period, release cadence, signing — which are exactly the fields #520, #551 and #552 are about. Expect this issue to find things.

Judgement call to make first: whether one more root-level file earns its place, or whether this is compliance decoration. The argument for is that it removes work rather than adding it — every field a third party can read is a question nobody has to send us.

One recommendation in `proposals/gen-two-tier-approach.md` ([orcwg/cra-attestations](https://github.com/orcwg/cra-attestations)) is easy to miss and is the most useful idea in the document. Attestations may be issued by unaffiliated third parties — researchers, manufacturers, national bodies — and for that to work without pestering the maintainer, the project's information should be public in a form that lets third parties generate an attestation **through machine automatable means**. **Why this is worth doing even though we already publish everything.** All the facts exist: `SECURITY.md`, `CONTRIBUTING.md`, `LICENSE.md`, `sbom/`, `docs/BUILD.md`, `docs/CHECKS.md`. They exist as prose in a dozen files, in two languages, written for humans. A downstream user who wants to know our disclosure terms has to read `SECURITY.md` and `tool/check_service_norms.dart`. That is a burden we impose on them and, when they ask by e-mail, a burden that comes straight back to us. **The form.** [OpenSSF Security Insights](https://github.com/ossf/security-insights-spec) is the existing specification for this: a `SECURITY-INSIGHTS.yml` in the repository root carrying the project's contacts, disclosure terms, dependency policy, build and release facts, and links to the artefacts. It is machine-readable, versioned, and already consumed by third-party tooling — which beats inventing our own JSON. Check the current spec version before adopting; it has moved. **What this issue delivers** - `SECURITY-INSIGHTS.yml` (or whatever the current spec names it), filled in from the files that already hold the facts. - **A gate that keeps it true.** A metadata file that silently drifts from `SECURITY.md` is worse than none, because it is the copy a machine reads. This repository's habit applies: a test that fails when the two disagree — at minimum the security contact, the disclosure terms, and the licence. Same reflex as `docs_registration_test` and `sbom_test`. - A pointer from `COMPLIANCE.md` (#549) and `SECURITY.md`, so a human finds it too. **Second-order benefit.** Writing the facts in a schema forces the gaps into the open — support period, release cadence, signing — which are exactly the fields #520, #551 and #552 are about. Expect this issue to find things. **Judgement call to make first:** whether one more root-level file earns its place, or whether this is compliance decoration. The argument for is that it *removes* work rather than adding it — every field a third party can read is a question nobody has to send us.

brenno added the

triage

enhancement

labels

2026-07-22 13:44:35 +00:00

brenno referenced this issue from a commit

2026-07-22 16:12:21 +00:00

docs: voeg security-insights.yml toe, met een poort erop

brenno referenced this issue from a pull request that will close it,

2026-07-22 16:12:22 +00:00

docs: security-insights.yml (OpenSSF v2.2.0), met een poort erop (#555) #569

brenno closed this issue