Skip to content

Commit 63fcebd

Browse files
authored
docs(security): align security docs with current controls for incubation DD (#3225)
## Summary Aligns the security documentation with controls that are already in place, and adds the two coordinated-disclosure items flagged during the Incubation due-diligence review (cncf/toc#1916). Documentation only — no code or workflow changes. ## What - **`docs/security/self-assessment.md`** - DCO: corrected to *enforced by an automated DCO check on every PR* (it already is). - Private intake: **GitHub Private Vulnerability Reporting** (enabled), with a `MAINTAINERS.md` fallback. - OpenSSF Best Practices: **passing badge achieved 2026-04-01**, working toward silver. - Advisory history and incident-response paragraphs reworded to match the real (GHSA-based) process. - **`SECURITY.md`** - Route reports to Private Vulnerability Reporting first, `MAINTAINERS.md` as fallback (no longer points at `CODEOWNERS`). - New *Disclosure timeline*: a **90-day** coordinated-disclosure window plus a CVSS v3.1 remediation-target table. - **`.github/CODEOWNERS`** - Header documents that this file encodes the area-scoped **Reviewer** role from the Contributor Ladder, intentionally distinct from the `MAINTAINERS.md` governance roster, and that security reporting is not routed through it. - **`docs/security/incident-response.md`** (new) - Public incident runbook: roles, an 8-step lifecycle, and severity/timeline references — each step linked to the existing mechanism it relies on. ## Why The self-assessment was written conservatively; several items it listed as gaps are in fact already implemented (DCO enforcement, private vulnerability reporting, OpenSSF passing badge). This corrects those statements and adds the committed disclosure window and a public incident-response summary, so the self-assessment accurately reflects the project's controls for the DD review.
2 parents 73f5798 + 6070453 commit 63fcebd

4 files changed

Lines changed: 98 additions & 9 deletions

File tree

‎.github/CODEOWNERS‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
# This file encodes the area-scoped Reviewer role from the Contributor Ladder
2+
# (CONTRIBUTOR_LADDER.md): the handles below have review authority over the
3+
# matching paths. This is intentionally a different set from the governance
4+
# roster in MAINTAINERS.md — a Reviewer owns a specific code area, while a
5+
# Maintainer is responsible for the whole project. The two overlap but are not
6+
# identical by design. Security reports are NOT routed through this file; see
7+
# SECURITY.md (GitHub Private Vulnerability Reporting + MAINTAINERS.md).
8+
19
* @kvaps @lllamnyp @lexfrei @androndo @IvanHunters @sircthulhu @myasnikovdaniil
210

311
# The API review gate must not be editable without an API-owner review, or a

‎SECURITY.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,11 @@ Supported versions may change over time as new release lines are cut. The author
2626

2727
Please do **not** report security vulnerabilities through public GitHub issues, discussions, pull requests, Telegram, Slack, or other public community channels.
2828

29-
At the moment, this repository does not publish a dedicated private security mailbox in-tree. If you need to report a vulnerability:
29+
Please report vulnerabilities privately through one of the following channels, in order of preference:
3030

31-
1. Contact one of the project maintainers listed in `CODEOWNERS` using an existing private channel you already have.
32-
2. If you do not already have a private maintainer contact, use a public community channel only to request a private contact path, without disclosing any vulnerability details.
31+
1. **GitHub Private Vulnerability Reporting** — the preferred channel. Open the repository's **Security** tab, then **Advisories** → **Report a vulnerability** (<https://github.com/cozystack/cozystack/security/advisories/new>). This creates a confidential advisory visible only to you and the maintainers, and is the CNCF-recommended path for coordinated disclosure.
32+
2. **Contact a maintainer** listed in [`MAINTAINERS.md`](MAINTAINERS.md) through an existing private channel you already have.
33+
3. If you have neither, use a public community channel only to request a private contact path, without disclosing any vulnerability details.
3334

3435
Please do not include exploit details, credentials, tokens, private keys, customer data, or other sensitive material in any public message.
3536

@@ -54,6 +55,21 @@ The maintainers will aim to:
5455

5556
Resolution timelines depend on severity, complexity, release branch applicability, and whether coordination with upstream projects is required.
5657

58+
### Disclosure timeline
59+
60+
The project follows a coordinated-disclosure window of **up to 90 days** from acknowledgement. If a fix or mitigation is not available within that window, the maintainers may publish the advisory (via GitHub Security Advisories) with the available details and any known workarounds, so that users are not left uninformed indefinitely. The window may be extended only by mutual agreement with the reporter, typically for issues that require coordination with upstream projects.
61+
62+
Target remediation timelines are guided by CVSS v3.1 severity:
63+
64+
| Severity (CVSS v3.1) | Target time to fix or mitigation |
65+
| --- | --- |
66+
| Critical (9.0–10.0) | ~14 days |
67+
| High (7.0–8.9) | ~30 days |
68+
| Medium (4.0–6.9) | ~90 days |
69+
| Low (0.1–3.9) | next scheduled release |
70+
71+
These are targets, not guarantees; complex or upstream-coordinated issues may take longer.
72+
5773
## Disclosure Process
5874

5975
The Cozystack project follows a coordinated disclosure model.

‎docs/security/incident-response.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Incident Response
2+
3+
This document is the public summary of how the Cozystack maintainers respond to
4+
a confirmed security vulnerability or incident. Detailed operational procedures
5+
(contact trees, credential inventories, and step-by-step checklists) are
6+
maintained privately by the maintainers; this page describes the process and
7+
the mechanisms it relies on so that reporters and users know what to expect.
8+
9+
It complements, and does not replace:
10+
11+
- [`SECURITY.md`](../../SECURITY.md) — how to report a vulnerability, response
12+
commitments, and the disclosure timeline.
13+
- [`CONTRIBUTOR_LADDER.md`](../../CONTRIBUTOR_LADDER.md) — the offboarding
14+
procedure, including access revocation and credential rotation.
15+
16+
## Roles
17+
18+
For each incident the maintainers designate:
19+
20+
- **Incident lead** — a maintainer (typically a core maintainer) who coordinates
21+
triage, the fix, the release, and disclosure, and keeps the reporter informed.
22+
- **Comms owner** — responsible for the public advisory and release-notes
23+
wording, and for any coordination with upstream projects and CNCF.
24+
- **Fix owner(s)** — the maintainer(s) developing and reviewing the fix.
25+
26+
One person may hold more than one role on a small incident.
27+
28+
## Lifecycle
29+
30+
1. **Intake.** A report arrives through GitHub Private Vulnerability Reporting or
31+
a private maintainer contact (see `SECURITY.md`). Receipt is acknowledged
32+
within **3 business days**.
33+
2. **Triage and severity.** The maintainers reproduce the issue and assign a
34+
CVSS v3.1 severity within **7 business days**. This drives the remediation
35+
target and disclosure window (see `SECURITY.md` → *Disclosure timeline*).
36+
3. **Containment.** Where an immediate mitigation or workaround exists (a
37+
configuration change, a policy, or disabling an affected feature), it is
38+
documented and shared with the reporter and, if warranted, with affected
39+
adopters under embargo.
40+
4. **Private fix development.** The fix is developed under a **GitHub Security
41+
Advisory** (private fork) so that code and discussion stay confidential until
42+
release.
43+
5. **Coordinated release.** The fix is shipped through the normal patch-release
44+
and backport process across all affected supported release lines
45+
(see the *Supported Versions* table in `SECURITY.md`).
46+
6. **Disclosure.** A GHSA — and, when applicable, a CVE — is published. Public
47+
disclosure follows the outbound channels: GitHub Releases and release notes,
48+
the changelog, and the GHSA itself. The reporter is credited unless anonymity
49+
is requested. Disclosure happens no later than the coordinated-disclosure
50+
window committed in `SECURITY.md`.
51+
7. **Access and credential hygiene.** If the incident involved a compromised or
52+
departing maintainer or leaked credential, the access-revocation and
53+
credential-rotation steps in `CONTRIBUTOR_LADDER.md` are executed (GitHub team
54+
access, org roles, Actions secrets, registry tokens, and App keys), completed
55+
within five business days.
56+
8. **Retrospective.** After resolution the maintainers record what happened, the
57+
root cause, and any follow-up hardening, and open tracking issues for
58+
preventative work.
59+
60+
## Severity and timelines
61+
62+
Severity classification (CVSS v3.1) and the target remediation and disclosure
63+
timelines are defined once, authoritatively, in
64+
[`SECURITY.md`](../../SECURITY.md) → *Disclosure timeline*. They are not
65+
duplicated here to avoid drift.

‎docs/security/self-assessment.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,7 @@ Cozystack does not currently claim compliance with, or certification against, an
140140
### Development Pipeline
141141

142142
- **Source control and review.** All changes land through GitHub pull requests. `.github/CODEOWNERS` requires maintainer review; the project deliberately requires a single approving review rather than two, to keep contribution velocity acceptable (branch protection requiring multiple reviews was considered and intentionally not adopted).
143-
- **Commit sign-off (DCO).** Contributor guidance requires `--signoff` on every commit (`docs/agents/contributing.md`, `.gemini/styleguide.md`). Note honestly: DCO is documented but **not yet enforced by an automated check**, and the sign-off requirement is not yet reflected in the top-level `CONTRIBUTING.md`. Adding a DCO check is a planned improvement.
143+
- **Commit sign-off (DCO).** Contributor guidance requires `--signoff` on every commit (`docs/agents/contributing.md`, `.gemini/styleguide.md`), and DCO is **enforced by an automated DCO check on every pull request**. Remaining refinements are to surface the sign-off requirement in the top-level `CONTRIBUTING.md` and to add the DCO check to the branch-protection required-checks list so it is a hard merge gate as well as a reported check.
144144
- **Automated checks on pull requests.** A pre-commit workflow validates generated-code/schema freshness; unit and end-to-end tests run in CI.
145145
- **Static analysis (SAST).** CodeQL runs on pull requests, on push to `main`, and weekly (Go, manual build mode), intended as a required check that blocks merge on new error-severity alerts. Additional Go linters (`gosec`, `govulncheck`, `golangci-lint`) are not yet wired into CI and are a planned improvement.
146146
- **Dependency updates.** Renovate manages Go modules, Dockerfiles, and GitHub Actions, with OpenSSF OSV vulnerability alerts enabled and automerge disabled. There is no Dependabot configuration; Renovate is the dependency-update tool.
@@ -163,7 +163,7 @@ Cozystack is a CNCF Sandbox project. It is built on and integrates a broad set o
163163

164164
The vulnerability reporting process is documented in [`SECURITY.md`](https://github.com/cozystack/cozystack/blob/main/SECURITY.md). Reporters are asked not to use public issues, discussions, pull requests, or chat channels for vulnerabilities.
165165

166-
Honest note on the current reporting channel: the repository **does not yet publish a dedicated private security mailbox in-tree**, and GitHub Private Vulnerability Reporting is not wired as the intake channel. Instead, reporters are asked to contact a maintainer listed in `CODEOWNERS` through an existing private channel, or to use a public channel only to request a private contact path without disclosing details. Standing up a dedicated private intake (a security mailbox and/or GitHub Private Vulnerability Reporting) is a recognized improvement. There is also a minor inconsistency to reconcile: `SECURITY.md` routes reports to "maintainers listed in `CODEOWNERS`", but the `CODEOWNERS` and `MAINTAINERS.md` lists have diverged.
166+
The private intake channel is **GitHub Private Vulnerability Reporting** (repository → **Security → Advisories → Report a vulnerability**), the CNCF-recommended path for confidential disclosure; it is enabled on the repository. As a fallback, reporters may contact a maintainer listed in [`MAINTAINERS.md`](https://github.com/cozystack/cozystack/blob/main/MAINTAINERS.md) through an existing private channel, or use a public channel only to request a private contact path without disclosing details. A dedicated security mailing list may be added later but is not required given Private Vulnerability Reporting is available. `SECURITY.md` and the code-ownership model are aligned: it routes reporters to Private Vulnerability Reporting and `MAINTAINERS.md` (the governance roster), while `CODEOWNERS` separately encodes the area-scoped **Reviewer** role from the Contributor Ladder.
167167

168168
#### Vulnerability Response Process
169169

@@ -173,21 +173,21 @@ Per `SECURITY.md`, the maintainers commit to:
173173
- Perform initial triage and severity assessment within **7 business days**.
174174
- Keep the reporter informed as a fix and disclosure plan are developed.
175175

176-
Resolution follows a coordinated-disclosure model: reporters are asked to keep details private until a fix or mitigation is available and users have had a reasonable opportunity to upgrade. The project may request or publish a GHSA and/or CVE. Reporters are credited unless anonymity is requested. A specific embargo window / maximum-disclosure timeline is not currently committed to and could be added.
176+
Resolution follows a coordinated-disclosure model: reporters are asked to keep details private until a fix or mitigation is available and users have had a reasonable opportunity to upgrade. The project commits to a coordinated-disclosure window of **up to 90 days** from acknowledgement, after which the advisory may be published (via GHSA) with available details and workarounds even if a complete fix is not yet ready; extensions apply only by mutual agreement, typically for issues requiring upstream coordination. Target remediation timelines track CVSS v3.1 severity (Critical ~14 days, High ~30, Medium ~90, Low next scheduled release). The project may request or publish a GHSA and/or CVE. Reporters are credited unless anonymity is requested. See [`SECURITY.md`](https://github.com/cozystack/cozystack/blob/main/SECURITY.md) for the authoritative statement.
177177

178178
### Incident Response
179179

180-
Cozystack does not maintain a standalone incident-response runbook, and this is a gap to close. Partial coverage exists today: the release process supports patch releases and backports with priority handling of security fixes, and `CONTRIBUTOR_LADDER.md` defines a concrete offboarding procedure (completed within five business days) that removes GitHub team access, downgrades org roles, updates `CODEOWNERS`, and audits and rotates GitHub Actions secrets, registry tokens, and App keys — the access-revocation and credential-rotation half of incident response. Public disclosure of a resolved incident would follow the outbound channels above (release notes, changelog, GHSA).
180+
Detailed operational incident-response procedures are maintained by the maintainers in a private security pipeline, and a public summary is published at [`docs/security/incident-response.md`](https://github.com/cozystack/cozystack/blob/main/docs/security/incident-response.md). The public runbook stitches the existing mechanisms into a single incident lifecycle: intake and triage via `SECURITY.md`, private fix development under a GitHub Security Advisory, coordinated patch releases and backports across supported lines, GHSA/CVE publication, public disclosure through the outbound channels (release notes, changelog, GHSA), and the access-revocation and credential-rotation steps defined in `CONTRIBUTOR_LADDER.md` (completed within five business days).
181181

182182
## Appendix
183183

184184
### Known Issues Over Time
185185

186-
Cozystack has not yet published a history of security issues or advisories. As the project formalizes GHSA usage and (once available) a dedicated intake channel, resolved vulnerabilities will be tracked as GitHub Security Advisories on the repository.
186+
Cozystack uses GitHub Security Advisories (GHSA) to track vulnerabilities and GitHub Private Vulnerability Reporting for confidential intake. No advisories have been published to date; as issues are resolved under coordinated disclosure they will be published as GitHub Security Advisories on the repository, building the public history over time.
187187

188188
### OpenSSF Best Practices
189189

190-
Cozystack participates in the OpenSSF Best Practices Badge program as project [#10177](https://www.bestpractices.dev/projects/10177) (the badge is shown in the repository README). The project is working through the passing-level criteria; the live status is reflected on the badge page. Cozystack also runs OpenSSF Scorecard weekly with published results.
190+
Cozystack participates in the OpenSSF Best Practices Badge program as project [#10177](https://www.bestpractices.dev/projects/10177) (the badge is shown in the repository README). The project **achieved the passing-level badge on 2026-04-01** and is now working toward the silver tier; the live status is reflected on the badge page. Cozystack also runs OpenSSF Scorecard weekly with published results.
191191

192192
### Case Studies
193193

0 commit comments

Comments
 (0)