docs: add security guidelines and SECURITY.md template#7
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... |
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)
Skarlso
left a comment
There was a problem hiding this comment.
I would like to clarify a couple of things here. The more pressing one is the timeline, the templating with italic and the discrepancies between MUST and SHOULD for CVEs. The rest if UX.
- Resolve CVE MUST/SHOULD contradiction: advisory links MUST be in release notes, CVE identifier MUST only when assigned (Section 6.4 stays SHOULD) - Align all timelines to report receipt (Day 0), matching Google Project Zero practice; remove "from triage completion" phrasing - Clarify embargo starts from report receipt, not acknowledgement - Fix conformance matrix: split secret scanning (MUST) from push protection (SHOULD) into separate rows - Make CI/CD section platform-neutral: generic requirements with "On GitHub:"/"On GitLab:" implementation guidance - Quick-start checklist: fix item neonephos#10 (secret scanning only, push protection is SHOULD) and neonephos#12 (platform-neutral wording) - Template: convert italic instructions to HTML comments - Template: add PVR enablement reminder before GitHub section - Template: use absolute URLs for cross-repo portability - Template: add "What to Include" section for reporters - Template: make security contacts table platform-neutral - Template: clarify attribution (OpenSSF vs NeoNephos) per item - Template: add footnote explaining 90-day ceiling vs fix targets Signed-off-by: Gerald Morrison <gerald.gm.morrison@gmail.com>
ScheererJ
left a comment
There was a problem hiding this comment.
Thanks a lot for adding the security guidelines.
|
|
||
| - **Vulnerability disclosure and response**: How projects receive, handle, and disclose security vulnerabilities. | ||
| - **Supply chain security**: Requirements for signing, provenance, SBOMs, and dependency management of released artifacts. | ||
| - **Operational security controls**: Authentication, CI/CD security, access governance, and code scanning requirements. |
There was a problem hiding this comment.
Just to clarify: This is just about operational security controls during development or also about the security controls during actual operation?
There was a problem hiding this comment.
Good catch — added a sentence to §3 making clear the doc covers the development/build/release lifecycle, not runtime security of deployed services.
|
|
||
| ## 7. Severity Classification and Response Targets | ||
|
|
||
| Projects **MUST** classify vulnerabilities using [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document) or later. Maintainers **MAY** exercise judgment when the CVSS score does not fully reflect practical impact. |
There was a problem hiding this comment.
Maintainers MAY exercise judgment when the CVSS score does not fully reflect practical impact.
What does this mean?
There was a problem hiding this comment.
Reworded — maintainers may adjust severity up or down for real-world context (mitigating defaults, active exploitation), and any deviation has to be documented in the advisory with rationale.
|
|
||
| ### 8.4 Software Composition Analysis (SCA) | ||
|
|
||
| - Projects **MUST** scan direct and transitive dependencies for known vulnerabilities. |
There was a problem hiding this comment.
What happens with the results? Are they supposed to be publicly visible? If not how can anyone ensure it really happens?
What is the recommended/required frequency? Can I scan once per year?
There was a problem hiding this comment.
Both were under-specified. Aligned with OpenSSF Baseline OSPS-VM-05.03 instead of inventing a calendar cadence: scan on every change against a documented threshold and block on violations.
Added a SHOULD that scan results are surfaced via the platform's native mechanism (Dependabot alerts / GitLab Security dashboard) so conformance is externally verifiable.
| - Projects **SHOULD** configure automated dependency update pull requests to reduce time-to-remediation. | ||
| - Projects **SHOULD** remediate known vulnerabilities of medium or higher severity within 60 calendar days of public disclosure, per [OpenSSF Best Practices](https://www.bestpractices.dev/). | ||
| - Projects that publish container images **SHOULD** scan all images for known vulnerabilities before pushing them to a registry. | ||
| - Projects **SHOULD** automate license scanning of all dependencies and define an allowlist of acceptable licenses. |
There was a problem hiding this comment.
Can every project define their own list of allowed licenses?
There was a problem hiding this comment.
Yes, each TSC defines its own allowlist — but it has to be compatible with the project's own license and Project Guidelines §6. Added that constraint
|
|
||
| ### 9.1 Authentication | ||
|
|
||
| Projects **MUST** enforce Two-Factor Authentication (2FA) for all organization members. |
There was a problem hiding this comment.
Should we not be more specific for what we want to enforce two factor authentication? I would expect we mean version control and CI systems here, e.g. github.com. I doubt that we want to enforce two factor authentication also on the actual software being developed, e.g. Gardener.
There was a problem hiding this comment.
Agreed. Narrowed to "all members of the project's source-control, CI/CD, and artifact-publishing accounts (GitHub/GitLab org, container/package registries)".
| - Use pull requests for all repository changes. | ||
| - Maintain an up-to-date inventory of maintainer permissions across all platforms used by the project. | ||
|
|
||
| Projects **SHOULD** require that maintainer candidates have a sustained history of contributions, are vouched for by an existing maintainer, and have verified their real identity with an existing maintainer, preferably in person. Vetting contributors before granting commit or release access mitigates supply chain risks from compromised or malicious accounts (cf. the [xz-utils incident](https://en.wikipedia.org/wiki/XZ_Utils_backdoor)). |
There was a problem hiding this comment.
This seems to be very far from the reality. Should this not rather be a SHALL instead?
There was a problem hiding this comment.
I checked before changing the priority. OpenSSF Scorecard has no maintainer-vetting check at all, and the OpenSSF Vulnerability Disclosure maintainer guide just says "select trusted maintainers" without any normative wording.
The OpenSSF Baseline access controls are at organization level, not individual onboarding — so there's no upstream MUST/SHALL to anchor on. I'd rather not get out ahead of OpenSSF/CNCF on a NeoNephos-specific upgrade.
I kept the priority at SHOULD but restructured the three criteria into a numbered list so each is auditable. Happy to revisit if the TAC explicitly wants NeoNephos to lead here.
|
|
||
| ### 9.7 Security Assessment and Posture Verification | ||
|
|
||
| Projects **SHOULD** perform an initial security assessment when entering the Growth or Graduated lifecycle stage, covering trust boundaries, a lightweight threat model, and documentation of known security assumptions and residual risks. |
There was a problem hiding this comment.
Please add links, e.g. with regards to threat modelling.
There was a problem hiding this comment.
Added STRIDE, OWASP Threat Modeling Process, and the CNCF Cloud Native Security Whitepaper as accepted methodologies, plus the OpenSSF security-reviews repo for examples.
| Each requirement carries a conformance priority and a resolution timeframe. The TSC of each project is the responsible owner for all requirements. | ||
|
|
||
| | Section | Requirement | Priority | Resolution | Owner | | ||
| |---------|-------------|----------|------------|-------| | ||
| | Section 5 | Private vulnerability intake channel | **MUST** | ≤30 days | TSC | |
There was a problem hiding this comment.
I do not understand the timeline. Could you please clarify? Do projects need to implement this once the PR is merged within this timeline (or if they reach a certain stage in the lifecycle)?
There was a problem hiding this comment.
😊
Right, the matrix didn't say what the clock measured from. Added one line: Resolution is from the latest of (a) the requirement's effective date, (b) project onboarding, or (c) the lifecycle stage where it applies. Effective dates for new requirements are set by the TAC.
| - For projects with multiple repositories, each repository containing | ||
| publishable code or artifacts MUST have its own SECURITY.md. On GitHub, | ||
| a SECURITY.md placed in the organization's `.github` repository serves | ||
| as the default for all repositories that do not have their own — this | ||
| satisfies the per-repository requirement, but cannot include | ||
| repository-specific direct links (see Option A below). |
There was a problem hiding this comment.
What does this mean now? Is a single SECURITY.md on the organisation level enough for a multi-repo project or not?
There was a problem hiding this comment.
Clarified in both places. On GitHub, an org-level .github/SECURITY.md legitimately covers any repo without its own (GitHub's documented fall-through); per-repo file only needed when the repo wants its own intake link or contacts. GitLab has no fall-through, so each GitLab project needs its own.
Co-authored-by: Johannes Scheerer <johannes.scheerer@sap.com> Signed-off-by: Gerald Morrison <67469729+morri-son@users.noreply.github.com>
Addresses ScheererJ review comment on §3 (PR neonephos#7): "operational security controls" was ambiguous. Adds an explicit sentence stating the doc covers the development, build, and release lifecycle, and that runtime security of services deployed by consumers is out of scope. Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Addresses ScheererJ review comment on §7 (PR neonephos#7). Replaces vague "maintainers MAY exercise judgment" with concrete examples (mitigating default configurations, evidence of active exploitation) and requires any deviation from the raw CVSS score to be documented in the published advisory together with the original score and rationale. Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Addresses ScheererJ review comment on §8.4 (PR neonephos#7). The previous "projects MUST scan dependencies" did not specify frequency or whether results have to be visible. Aligns with OpenSSF Baseline OSPS-VM-05.03 (per-change evaluation against a documented threshold, with blocking on violations) instead of inventing a calendar cadence. Adds a SHOULD that scan results are surfaced via the platform's native mechanism (Dependabot alerts, GitLab Security dashboard) so conformance is externally verifiable. Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Addresses ScheererJ review comment on §8.4 (PR neonephos#7). Each TSC defines its own allowlist, but the allowlist must be compatible with the project's own license and Project Guidelines §6. Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Addresses ScheererJ review comments on §9.1 (PR neonephos#7). "Organization members" and "organization level" were too generic. Restricts both controls to the project's source-control, CI/CD, and artifact-publishing accounts (GitHub/GitLab organizations, container and package registries) — i.e., the systems where unauthorized access could lead to malicious code or artifacts being shipped. Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Addresses ScheererJ review comment on §9.2 (PR neonephos#7). SHA pinning is compatible with automated update tooling — Dependabot updates the SHA and keeps a version comment, Renovate has pinDigests. Adds links to both so it's clear automation is not lost. Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Addresses ScheererJ review comments on §9.5 (PR neonephos#7). "Small number" and "limit admin permissions" were not actionable. - Organization owners: anchored to a concrete range (2-5), required to be human named accounts with 2FA enforced. - Repository admin: reframed around intent — admin is for repository configuration (branch protection, secrets, releases); routine review/merge work belongs in the maintain or write role. Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Addresses ScheererJ review comment on §9.5 (PR neonephos#7) which suggested upgrading SHOULD to SHALL. Priority kept at SHOULD: OpenSSF Scorecard has no maintainer-vetting check, the OpenSSF Vulnerability Disclosure maintainer guide only says "select trusted maintainers" without normative wording, and OpenSSF Baseline access controls (OSPS-AC-*) are at the organization level rather than individual onboarding. There is no upstream MUST/SHALL for this control today, so the priority is not upgraded ahead of OpenSSF or peer foundations. Restructured the three criteria (sustained contributions, vouching, identity verification) into a numbered list so each is auditable, and allowed video-call verification against a previously verified identity as an equivalent to in-person verification. Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Addresses ScheererJ review comment on §9.7 (PR neonephos#7). Lists STRIDE, the OWASP Threat Modeling Process, and the CNCF Cloud Native Security Whitepaper as accepted methodologies, and points to the OpenSSF security-reviews repository for example reviews. Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Addresses ScheererJ review comment on §10 (PR neonephos#7). The Resolution timeline is measured from the latest of: the requirement's effective date, the project's onboarding date, or the lifecycle stage at which the requirement applies. Effective dates for new or amended requirements are set by the TAC. Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Addresses ScheererJ review comment on templates/SECURITY.md (PR neonephos#7): "Is a single SECURITY.md on the organisation level enough for a multi-repo project or not?" On GitHub, a SECURITY.md in the organization's .github repository is automatically used by every repository without its own — this satisfies the per-repository requirement, except where a repository needs its own intake link or contacts. GitLab has no equivalent fall-through, so each GitLab project needs its own SECURITY.md. Spelled out in both the security guidelines (§5.2) and the templates/SECURITY.md comment block. Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Initial proposal for security guidelines and SECURITY.md template to be used in every repository.