Structured SECURITY.md - Brainstorming

[scovetta]

Based on 7/21/2021 WG meeting, we should consider advocating for a structured security.md file. Not necessarily Markdown, but something that can be introspected and validated.

[mrutkows]

As ante-up/table stakes I liked the idea of having a markdown (prose) file (with recommended H1-Hx structured sections), but also a file (like a ".oss-security[.yaml]) file that enables automation to enable various security & compliance tools and is schema based. This file could codify required/optional fields that yield to more deterministic scans (by OSSF scorecard for example), be used to disambiguate and/or reference other security process docs., as well as an artifact we can present/solicit to foundations, such as CNCF, Apache, CD Foundation, etc., for possible adoption and a clear means to improve any "scores" we produce. Please note we ack'ed that we cannot infer the intentions of existing SECURITY.md, nor evaluate/compare completeness of contents without manual inspection.

Key complex objects should exist that describe project IDs that can be used NVD lookup/reference as well as (direct) reference (and schema based inclusion) in popular SBOM formats (i.e., SPDX2.2/3.0+security profile or CycloneDX). This would support legacy SWID, deprecated CPE as well as forward thinking pURLs.

For example, CycloneDX supports metadata that allows decription of almost any domain-based information, but also supports "contact" info. for contacting the owner in relation to license compliance issues or known CVEs (and can point to corrective information like patches, versions, etc.).

I can provide discrete schema ref. as I have time... and I am not sure of the status of the SPDX 3.0 security profile as it seems 3.0T base spec. contents is still in debate (from root element/structure on-down). Still happy to speculate on how SPDX could likewise incorporate using their current draft schema.

[scovetta]

We're using a hybrid YAML/Markdown layout for security reviews, which seems to work reasonably well, example: https://github.com/ossf/security-reviews/blob/main/reviews/npm/iter-server/review-1.md

Some thoughts/questions:

• Having Package URLs to distribution points (e.g. pkg:github/foo/bar as well as pkg:npm/bar) would be useful, but not purely security.
• CPEs would be great, too -- AFAIK, there are only fuzzy matches or commercial vendors that have done the matching themselves somehow.
• Any of the contact data could be direct (e.g. email) or indirect ("see our contact page at ").
• Project Archetype - Don't know if it belongs here, but I'd really like to be able to filter projects into buckets like, "small library that does one basic function", "general purpose library", "framework", "platform", "standalone product", "extension", etc. I don't know how to confidently determine this automatically.

[mrybczyn]

From the discussion and my experiences the items includes should be:

• CPE or equivalent
• contact information (might be multiple ones: general email, security email, contact form, bug tracker with instructions link...)
• official URL (on GitHub it's sometimes hard to find out what is the official repository, and what is some developer's fork)
• supported SBOM formats (eg. the project follows SPDX)

[david-a-wheeler]

To me, the key is that something has to be simple to apply. If it's too hard/complicated it won't get used.

[david-a-wheeler]

All:

We put our thoughts into the WG notes from today, but I don’t think that will work well long-term to create a specification.

So I’ve created a separate Google document with the draft name“Project security information specification” at: https://docs.google.com/document/d/1Hqks2J0wVqS_YFUQeIyjkLneLfo3_9A-pbU-7DZpGwM/edit# Currently it’s just a copy/paste of our notes from today.

The idea is that we’d work to improve it & see if we can get anywhere with it.

It has exactly the same author rights as the WG notes. If there’s an issue, please let me know & I’ll fix it.

If people object to working this way, please let me know!

[Amir-Montazery]

On a related note in the interest of connecting the dots between efforts, the OpenSSF Allstar tool (https://github.com/ossf/allstar) does a check to see if a given repository has a SECURITY.md file. From the Allstar github: SECURITY.md This policy's config file is named security.yaml, and the config definitions are here. This policy checks that the repository has a security policy file in SECURITY.md and that it is not empty. The created issue will have a link to the GitHub tab that helps you commit a security policy to your repository.