docs: add security guidelines and SECURITY.md template#7
docs: add security guidelines and SECURITY.md template#7morri-son wants to merge 12 commits intoneonephos:mainfrom
Conversation
- Replace cryptic version placeholder table in SECURITY.md template with flexible options (single branch vs. multiple releases) - Clarify SLA targets are calendar days, add transparency-over-speed guidance - Add practical notes to security-guidelines.md: incremental supply chain adoption, CVE deferral for early-stage projects, communication over deadlines - Mark Past Security Advisories section as optional for new projects
Change resolution for artifact signing, SLSA provenance, and SBOM from 'By next minor release' to 'When publishing artifacts to external consumers' — avoids artificial pressure on early-stage projects that do not yet distribute artifacts externally.
|
Should we also move the Operational Security aspects from here: https://github.com/neonephos/guidelines-development/blob/main/project-guidelines/project-guidelines.md#153-security-and-compliance into this document? |
|
I think it would be a lot easier to just adopt using the OpenSSF Scorecard, which will do checks to align with best practices. |
I created a section |
…SSF Scorecard, and template improvements - Relax SECURITY.md link requirement to support org-level .github repos (nexus49) - Clarify supported versions as a version support policy, not branch names (nexus49) - Add §10 Operational Security Controls reworked from Project Guidelines §15.3: authentication, CI/CD security, access governance, code scanning, data retention - Frame maintainer vetting criteria as supply-chain trust controls (§10.3) - Add §10.6 OpenSSF Scorecard recommendation (jmertic) - Update scope, introduction, and TOC; renumber Acknowledgements to §11 - Add org-level SECURITY.md guidance note to template
I copied the content over from §15.3 and reworked with conformance tables, cross-references to §8, and proper MUST/SHOULD language |
|
@morri-son Good question. Generally we see projects adopt the OpenSSF Best Practices Badge ( https://www.bestpractices.dev/ ) and map to the various tiers ( for example, Passing Badge for Incubation, Gold for Graduated ). The Scorecard could be then a tool to manage ongoing alignment, just in the same way LFX Insights is used for measuring contributions. Let me know your thoughts... |
| |----------|-----------------|-------| | ||
| | **MUST** | ASAP (≤30 days) | TSC | | ||
|
|
||
| Projects **MUST** enable [GitHub Private Vulnerability Reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability) on all repositories that contain publishable code or artifacts. This is the primary channel for receiving vulnerability reports. |
There was a problem hiding this comment.
We should also consider the possibility that projects are not on GitHub. For those, this can't be a MUST.
There was a problem hiding this comment.
You're right. I changed the section 5.1 and make it generic and placed git platform specific solutions below. Since the GH way was refered to in other section, too, I needed to also update those. Pls check the commit to see the diffs.
I added https://github.com/neonephos/guidelines-development/pull/7/changes#diff-1c57ac02b0e896c0a58ee0a4467770159c4a4c5b0e2c6c0e7b2ad989c4d73cd0R353-R364. Pls check if this fits your idea. |
Restructure Section 5.1 from GitHub-only "Private Vulnerability Reporting" to platform-agnostic "Private Vulnerability Intake Channel" with subsections for GitHub, GitLab, and other/self-hosted platforms. Update all downstream references in Sections 6, 7, 9, and 11 that previously hard-coded GitHub Security Advisories to use platform-agnostic language with platform-specific guidance blocks. Update SECURITY.md template with reporting options for GitHub (Private Vulnerability Reporting), GitLab (confidential issues), and email/ security.txt fallback. Addresses review feedback from fmui noting that not all projects may be hosted on GitHub (PR neonephos#7, comment r3064032552). Signed-off-by: Gerald Morrison <gerald.gm.morrison@gmail.com>
|
Hi @morri-son I still think we are just restating things already covered in existing materials. Take a look at the TAC site in progress ( https://special-couscous-6qv9rv3.pages.github.io/best_practices/repo.html ) and let me know your thoughts. |
link gives 404. But apart from anything proposed there, I guess we can keep best-practices in topic specific repos instead of always linking them to a central best practices doc, or? I would vote for keeping it in the SECURITY.md for the time being, getting it merged and evolve it over time. |
|
@morri-son Sorry - changed the URL to https://neonephos.github.io/tac/. LMK if that doesn't work for you. |
…ctions Add §8.5 and §8.6 to supply chain security guidelines, aligned with OpenSSF Security Baseline controls (OSPS-VM-05.01–05.03, OSPS-LE-02). Recommends Trivy, Grype, OSV-Scanner for image scanning and Trivy, Anchore Grant, REUSE for license compliance.
Add branch protection (MUST), secret scanning (MUST), CI/CD input sanitization, action pinning, SAST thresholds, security assessment, and provenance verification guidance. Strengthen existing sections with OpenSSF Baseline control references (OSPS-AC-03, BR-01, BR-07, VM-06, SA-03, DO-03, BR-04). All additions link to upstream docs rather than duplicating content.
OpenSSF Security Baseline Alignment (commit d7b21b0)Cross-referenced the security guidelines against the OpenSSF Security Baseline (OSPS), the OpenSSF Concise Guide, and the OpenSSF SCM Best Practices. Added the following based on identified gaps: New sections
Strengthened existing sections
Design decisions
|
|
@jmertic yes, that was a working link :-) And yes, you're right, the doc mentions things that are available at various other places. I took over many things from OpenSSF docs. But I'm not sure, what an enduser should do with https://neonephos.github.io/tac/best_practices/documentation.html#security or with looking at the mentioned OpenSSF docs when it comes to understand what needs to be done to onboard to Neonephos. I'm fine with cross referencing docs, either in the NeoNephos repo and external ones like OpenSSF, whenever possible we should deduplicate docs. But if I would be an enduser that needs to secure his repo(s) for joining the NeoNephos foundation, then I would like to have one central security guide that I can follow start to end. |
|
I'd advise against "NeoNephos" specific security guidance; this world is fast moving, and leaning on a group with expertise in this space is best advised versus doing work in silo. What I have seen done, which could be helpful, is showcasing a few projects who have done this well that could be an inspiration to others. But overindexing on specific requirements is going to be a neverending cycle, and most projects I work with tend to yield that to expert guidance and focus more on the domain expertise they have. |
…oject references - Add paragraph in introduction clarifying relationship to OpenSSF standards - Add industry rationale for SLAs (benchmarked against Envoy, GitLab, Chainguard) - Trim §8.2 (SLSA), §8.5 (container scanning), §8.6 (license scanning): replace verbose tool/implementation details with concise requirements + OpenSSF references - Condense §10.6 (SAST) from 9 lines to 3, keeping requirement and threshold concept - Add exemplary project references: Gardener (SECURITY.md), OCM (CI/CD, Scorecard)
|
@jmertic, sorry for the longer answer, but there are quite some things to explain :-) Adopted from your feedback:
What remains NeoNephos-specific are things OpenSSF explicitly delegates to adopting organizations: severity-based response SLAs (§7, benchmarked against Envoy/GitLab/Chainguard), a conformance model tied to lifecycle stages, and platform-specific guidance (GitHub/GitLab/other) that abstract standards can't provide. Why not the TAC site today: Most of the 13 NeoNephos projects have no SECURITY.md or use vendor boilerplate. The TAC site's security section lists three badge links with no actionable path for maintainers. Happy to revisit when that evolves — today, projects need a self-contained guide to actually get this done. |
Signed-off-by: Gerald Morrison <gerald.gm.morrison@gmail.com>
Major restructuring to make the guidelines actionable and easy to adopt: - Add Quick-Start Checklist (Section 4) with deep-links to exact MUSTs - Go platform-agnostic: remove GitHub/GitLab/Other subsections, defer to SECURITY.md template for platform-specific setup - Merge Conformance Model into Introduction, Security Transparency into Vulnerability Response Process (Section 6) - Drop Data Retention section (no OpenSSF precedent) - Replace 13 inline conformance tables with single Conformance Matrix - Add 60-day dependency remediation SLA (OpenSSF Best Practices) - Add explicit low-severity (<4.0) informal tracking clause - Soften maintainer vetting from fixed "6 months" to "sustained history" - Drop fixed ">=2 security contacts" requirement (delegate to project) - Remove all "Related sections" footers, "Exemplary implementation" callouts, and "Practical note" boxes - Update SECURITY.md template: add link-adjustment note, default "Past Security Advisories" to present Signed-off-by: Gerald Morrison <gerald.gm.morrison@gmail.com>
|
@jmertic I tried to incorporate your feedback again and cut the doc by a lot (from ~500 to ~300 lines) 🙂 The guidelines now state what NeoNephos requires and link to OpenSSF for the how — no more restating existing materials. Removed: all platform-specific subsections (deferred to SECURITY.md template), Data Retention (no OpenSSF precedent), 13 inline conformance tables (single matrix appendix) Added: Quick-Start Checklist with 12 MUSTs deep-linked to exact subsections — a team can scan it in 30 seconds. Conformance table that sums up all requirements at the end, moving them from tables scattered inline throughout each section. On strictness: Audited all MUSTs against OpenSSF. 20 of 24 align directly. The 4 that are stricter (SECURITY.md file, CVSS in advisories, non-author review, 90-day embargo ceiling) are things OpenSSF delegates to adopting organizations. They are best practices from other large OS project like Google's Project Zero. On Scorecard: Referenced in Section 9.7 as a SHOULD. It covers repo config checks; the guidelines cover process (response SLAs, disclosure). Complementary, not alternatives. Pls check if this now comes closer to what you envisioned. I still stand to my point that especially for security requirements teams and projects should have a single entry point/doc with an easy to copy template that they can adopt. |
4 participants
Initial proposal for security guidelines and SECURITY.md template to be used in every repository.