diff --git a/Governance/CHANGELOG.md b/Governance/CHANGELOG.md index 8dfb6484..2c00a342 100644 --- a/Governance/CHANGELOG.md +++ b/Governance/CHANGELOG.md @@ -10,6 +10,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added +- `Governance/policies/GOOD_FIRST_ISSUE.md` — criteria for the `good first issue` label, who may apply it, and mentorship expectations (issue #1610) +- `Governance/processes/VULN_DISCLOSURE.md` — private reporting channels, triage steps, and coordinated-disclosure timeline (issue #1612) +- `Governance/processes/COORDINATED_DISCLOSURE.md` — reporter coordination, public-disclosure timing, and credit policy (issue #1616) +- `Governance/SECURITY_RESPONSE_TEAM.md` — security response team membership, responsibilities, and on-call rotation (issue #1614) - `Governance/SECURITY_POLICY.md` — supported versions, private vulnerability reporting channels, and response-time commitments (issue #1611) - `Governance/templates/ADVISORY_TEMPLATE.md` — security advisory sections including severity, CVSS, and remediation fields (issue #1615) - `Governance/policies/EMBARGO.md` — default embargo durations by severity, embargo list membership, and early-disclosure exceptions (issue #1613) diff --git a/Governance/SECURITY_RESPONSE_TEAM.md b/Governance/SECURITY_RESPONSE_TEAM.md new file mode 100644 index 00000000..abb0095e --- /dev/null +++ b/Governance/SECURITY_RESPONSE_TEAM.md @@ -0,0 +1,90 @@ +# Security Response Team Charter + +- **Status:** Active +- **Version:** 1.0.0 +- **Owner:** Maintainers (see [Roles & membership](README.md#structure)) +- **Last reviewed:** 2026-09-28 +- **Review cadence:** Every 6 months, or when membership changes + +This charter defines the Security Response Team (SRT) for TeachLink Backend: +membership, responsibilities, and on-call expectations. It lives entirely +inside the `Governance/` folder and does not change application code. + +Related documents: + +- [`SECURITY_POLICY.md`](SECURITY_POLICY.md) +- [`processes/VULN_DISCLOSURE.md`](processes/VULN_DISCLOSURE.md) +- [`processes/COORDINATED_DISCLOSURE.md`](processes/COORDINATED_DISCLOSURE.md) +- [`policies/EMBARGO.md`](policies/EMBARGO.md) +- Operational on-call domain notes: [`domains/ON_CALL.md`](domains/ON_CALL.md) + +## 1. Purpose + +The SRT is the accountable group for receiving, triaging, remediating, and +disclosing security vulnerabilities that affect this repository’s supported +version lines. It coordinates with maintainers and, when needed, downstream +operators on the embargo list. + +## 2. Membership + +| Role | Who | Privileges | +|------|-----|------------| +| **SRT Lead** | A designated maintainer | Final escalation for severity/timing disputes; ensures coverage | +| **SRT Members** | Maintainers (and optionally trusted security reviewers) granted GitHub Security Advisory access | Triage, private advisory drafts, fix coordination | +| **On-call rotator** | Subset of SRT Members | First responder for new private reports during their shift | + +Membership changes are recorded in the Governance changelog and, when +appropriate, the decision log. Access to private security advisories must be +revoked when someone leaves the team. + +The public-facing contact remains the channels in `SECURITY_POLICY.md`; +individual personal emails are not required to be published. + +## 3. Responsibilities + +SRT Members collectively: + +1. **Monitor** private reporting channels (GitHub Security Advisories and the + security inbox). +2. **Acknowledge and triage** reports per `processes/VULN_DISCLOSURE.md`. +3. **Coordinate fixes** on supported branches with code owners. +4. **Uphold embargo rules** in `policies/EMBARGO.md`. +5. **Prepare advisories** using `templates/ADVISORY_TEMPLATE.md` and run + coordinated disclosure per `processes/COORDINATED_DISCLOSURE.md`. +6. **Post-incident** — ensure lessons learned feed into postmortems when an + issue reached production impact (`domains/POSTMORTEM_POLICY.md`). + +The SRT Lead additionally ensures the on-call rotation is published to members +and that no report sits unacknowledged beyond policy targets. + +## 4. On-Call Rotation + +- **Cadence:** Weekly shifts (timezone coverage as agreed among members; default + is calendar-week UTC). +- **Primary duty:** First acknowledgement of new private reports; escalate to + additional members for validation and fix ownership. +- **Handoff:** Outgoing on-call summarizes open private cases to the incoming + member (private channel or advisory comments). +- **Backup:** If the primary cannot respond, the SRT Lead is the default + backup. +- **Alignment with product on-call:** Security on-call may overlap engineering + on-call (`domains/ON_CALL.md`) but security triage priority follows this + charter and the security policy response times. + +Rotation schedule is maintained by the SRT Lead in the team’s private ops +channel (not required to be public). + +## 5. Decision Authority + +| Decision | Authority | +|----------|-----------| +| Severity rating | SRT Member performing triage; escalate to Lead on disagreement | +| Embargo extension beyond defaults | SRT Lead + documented reporter agreement (`EMBARGO.md`) | +| Public disclosure timing | SRT Lead within coordinated disclosure + embargo rules | +| Membership changes | Maintainers per project charter | + +## 6. Change History + +| Version | Date | Notes | +|---------|------|-------| +| 1.0.0 | 2026-09-28 | Initial security response team charter (issue #1614) | diff --git a/Governance/policies/GOOD_FIRST_ISSUE.md b/Governance/policies/GOOD_FIRST_ISSUE.md new file mode 100644 index 00000000..203287d7 --- /dev/null +++ b/Governance/policies/GOOD_FIRST_ISSUE.md @@ -0,0 +1,91 @@ +# Good First Issue Policy + +- **Status:** Active +- **Version:** 1.0.0 +- **Owner:** Maintainers (see [Roles & membership](../README.md#structure)) +- **Last reviewed:** 2026-09-28 +- **Review cadence:** Every 6 months, or after contributor onboarding feedback + +This policy defines when the `good first issue` label may be applied, who may +apply it, and what mentorship the project owes first-time contributors. It +lives entirely inside the `Governance/` folder and does not change application +code. + +Related documents: + +- Label catalog: [`LABEL_TAXONOMY.md`](../LABEL_TAXONOMY.md) +- Review expectations: [`REVIEW_SLA.md`](REVIEW_SLA.md) +- Communication norms: [`COMMUNICATION_NORMS.md`](COMMUNICATION_NORMS.md) + +## 1. Purpose of the Label + +`good first issue` signals that a task is suitable for someone new to this +repository. It is a mentorship commitment, not a backlog priority flag. Issues +with this label should be completable without deep historical context of the +codebase. + +## 2. Criteria for Applying `good first issue` + +An issue may receive the label only when **all** of the following hold: + +1. **Scope is small** — typically one focused change (roughly a single PR that + a new contributor can finish in a few focused hours, not multi-day design). +2. **Clear acceptance criteria** — the issue body states what “done” means in + concrete, testable terms. +3. **Pointers provided** — the issue links or names relevant files, modules, or + docs so the contributor is not left hunting. +4. **Low risk** — does not require production secret access, irreversible data + migrations, or emergency hotfixes. +5. **Self-contained** — is not blocked on unmerged work or private design + decisions. +6. **Mentorship available** — at least one maintainer or designated mentor is + willing to answer questions within the review SLA for the duration the label + remains applied. + +Do **not** apply the label when the issue is mainly “help wanted” for an +experienced contributor, or when the description is still at the idea stage. + +## 3. Who Applies the Label + +| Actor | May apply? | Notes | +|-------|------------|--------| +| Maintainers | Yes | Primary owners of triage | +| Triagers with write access | Yes | After confirming criteria above | +| Automated bots | Only if configured by maintainers | Must still satisfy human-reviewable criteria | +| External contributors | No | May **request** the label in a comment | + +Removing the label is appropriate when scope grows, blockers appear, or no +mentor can support the issue. Prefer explaining the removal in a short comment. + +## 4. Mentorship Expectation + +When `good first issue` is applied, the project commits to: + +1. **Responsive answers** — questions from the assignee or first poster receive + a substantive reply within the contributor-facing review SLA (see + `REVIEW_SLA.md`), or a clear “we need more time” note. +2. **Constructive first review** — the first PR review focuses on guidance, not + only rejection; request changes with specific next steps. +3. **No silent takeover** — maintainers should not silently implement the fix + while a newcomer is actively working the issue; coordinate in comments if + timelines slip. +4. **Credit** — merged work from first-time contributors is attributed normally + (commit author, release notes as applicable). + +Mentorship does not require pair-programming; async guidance is the default. + +## 5. Issue Template Checklist (Recommended) + +Before labeling, confirm the issue includes: + +- [ ] Problem statement in plain language +- [ ] Acceptance criteria (bullet list) +- [ ] Suggested starting files or search terms +- [ ] How to test locally (command or suite name) +- [ ] Links to related docs or prior PRs if useful + +## 6. Change History + +| Version | Date | Notes | +|---------|------|-------| +| 1.0.0 | 2026-09-28 | Initial good-first-issue policy (issue #1610) | diff --git a/Governance/processes/COORDINATED_DISCLOSURE.md b/Governance/processes/COORDINATED_DISCLOSURE.md new file mode 100644 index 00000000..ede32c74 --- /dev/null +++ b/Governance/processes/COORDINATED_DISCLOSURE.md @@ -0,0 +1,87 @@ +# Coordinated Disclosure Process + +- **Status:** Active +- **Version:** 1.0.0 +- **Owner:** Security Response Team (see [`SECURITY_RESPONSE_TEAM.md`](../SECURITY_RESPONSE_TEAM.md)) +- **Last reviewed:** 2026-09-28 +- **Review cadence:** Every 6 months, or after advisory process changes + +This process defines how TeachLink Backend coordinates with vulnerability +reporters before public disclosure, when information becomes public, and how +credit is assigned. It lives entirely inside the `Governance/` folder and does +not change application code. + +Related documents: + +- [`VULN_DISCLOSURE.md`](VULN_DISCLOSURE.md) — private reporting and triage +- [`policies/EMBARGO.md`](../policies/EMBARGO.md) — embargo duration and list +- [`templates/ADVISORY_TEMPLATE.md`](../templates/ADVISORY_TEMPLATE.md) +- [`SECURITY_POLICY.md`](../SECURITY_POLICY.md) + +## 1. Coordination Steps with Reporters + +After triage (see `VULN_DISCLOSURE.md`), the assigned security owner will: + +1. **Confirm shared understanding** — impact, affected versions, and whether a + public write-up by the reporter is planned. +2. **Agree a working timeline** — target fix windows within the severity-based + embargo maxima; document any mutually agreed shorter or longer period. +3. **Share status updates** — at least when severity changes, when a fix is + merged to a supported line, and when public disclosure is scheduled. +4. **Exchange draft advisory text** — invite reporter feedback on technical + accuracy (not a veto on whether to disclose after embargo rules are met). +5. **Confirm credit line** — how the reporter wishes to be named (name, handle, + team, or anonymous). + +Coordination happens on the private channel used for the original report +(GitHub Security Advisory discussion or email thread). + +## 2. Public-Disclosure Timing + +Public disclosure (GitHub Security Advisory publication, release notes, and any +CVE request) occurs when **either**: + +- A fix is available for all **supported** version lines that are materially + affected, **and** the Security Response Team is ready to publish; or +- The applicable **embargo maximum** in `policies/EMBARGO.md` is reached, + +whichever comes first, unless an exception in the embargo policy applies +(e.g. issue already fully public). + +**Prefer** disclosing with a fixed release. When disclosing without a complete +fix (embargo expiry or active exploitation), the advisory must state residual +risk and mitigations clearly. + +Pre-announcement to the embargo list may occur shortly before publication so +downstream operators can prepare; it is not a substitute for the public +advisory. + +## 3. Credit Policy + +| Situation | Credit practice | +|-----------|-----------------| +| Valid, in-scope report leading to a fix or advisory | Named in the advisory “Credits” section per reporter preference | +| Duplicate of an already-tracked private issue | Optional “additional reporters” credit if they added material new information | +| Out-of-scope or invalid | No public credit; polite private explanation | +| Reporter requests anonymity | Honor anonymity in all public materials | +| Reporter declines credit | Omit name; internal notes may retain contact for follow-up | + +Credit does not imply employment by or endorsement of TeachLink. CVE assignment, +when pursued, follows the same credit preferences where the issuing CNA allows. + +Maintainers who discover issues internally are credited as “TeachLink +maintainers” or by name at their option; internal finds still follow embargo +and advisory quality standards. + +## 4. Disputes + +Disagreements about severity, timing, or credit are escalated to the Security +Response Team lead (see charter). The project’s final call on publication timing +follows this process and the embargo policy after good-faith consultation with +the reporter. + +## 5. Change History + +| Version | Date | Notes | +|---------|------|-------| +| 1.0.0 | 2026-09-28 | Initial coordinated disclosure process (issue #1616) | diff --git a/Governance/processes/VULN_DISCLOSURE.md b/Governance/processes/VULN_DISCLOSURE.md new file mode 100644 index 00000000..ee0428a1 --- /dev/null +++ b/Governance/processes/VULN_DISCLOSURE.md @@ -0,0 +1,91 @@ +# Vulnerability Disclosure Process + +- **Status:** Active +- **Version:** 1.0.0 +- **Owner:** Security Response Team (see [`SECURITY_RESPONSE_TEAM.md`](../SECURITY_RESPONSE_TEAM.md)) +- **Last reviewed:** 2026-09-28 +- **Review cadence:** Every 6 months, or after any change to reporting channels + +This process describes how vulnerabilities in TeachLink Backend are reported +privately, triaged, and handled through coordinated disclosure. It lives +entirely inside the `Governance/` folder and does not change application code. + +Related documents: + +- [`SECURITY_POLICY.md`](../SECURITY_POLICY.md) — supported versions and response commitments +- [`COORDINATED_DISCLOSURE.md`](COORDINATED_DISCLOSURE.md) — public timing and credit +- [`policies/EMBARGO.md`](../policies/EMBARGO.md) — embargo durations +- [`templates/ADVISORY_TEMPLATE.md`](../templates/ADVISORY_TEMPLATE.md) + +## 1. Private Reporting Channel + +**Do not** file public GitHub issues for security vulnerabilities. + +Use one of the following private channels (preferred order): + +1. **GitHub Security Advisories** — *Report a vulnerability* on this repository + (visible only to maintainers with security access). +2. **Email** — `security@teachlink.example` (or the address published in + `SECURITY_POLICY.md` if updated), subject prefix `[SECURITY]`. + +Reports should include, when available: + +- Product / component and affected version(s) +- Reproduction steps or proof-of-concept +- Impact (confidentiality, integrity, availability) +- Whether the issue is already public or actively exploited +- Preferred contact method and any disclosure constraints + +## 2. Triage Steps + +Upon receipt of a private report, the Security Response Team (or on-call +security maintainer) will: + +| Step | Action | Target | +|------|--------|--------| +| 1 | **Acknowledge** the reporter | Within **3 business days** | +| 2 | **Validate** reproducibility and affected versions | As soon as practical after acknowledgement | +| 3 | **Severity triage** (Critical / High / Medium / Low) | Using impact and exploitability; CVSS optional but preferred for High+ | +| 4 | **Assign owner** | A maintainer responsible for the fix path | +| 5 | **Open private tracking** | GitHub Security Advisory draft or private issue; not a public bug ticket | +| 6 | **Notify embargo list** as needed | Per `policies/EMBARGO.md` | +| 7 | **Plan fix and advisory** | Track against supported version lines in `SECURITY_POLICY.md` | + +If the report is out of scope (e.g. social engineering of end users, or a +third-party service outside this repository), respond with a brief explanation +and, where possible, a pointer to the correct vendor. + +Duplicate reports are linked to the existing private case; later reporters may +still receive credit per the coordinated disclosure policy when appropriate. + +## 3. Coordinated-Disclosure Timeline + +Default timeline from **acknowledgement**: + +| Phase | Target | +|-------|--------| +| Initial assessment | ≤ 7 days | +| Fix development for supported lines | Severity-driven; align with embargo maxima in `EMBARGO.md` | +| Pre-disclosure notice to reporter | ≥ 3 days before public advisory when practical | +| Public advisory + release notes | When fix is available **or** embargo maximum is reached (see `COORDINATED_DISCLOSURE.md`) | + +Active exploitation or public leak may compress this timeline; the team documents +deviations in the private advisory notes. + +## 4. Reporter Expectations + +Reporters are asked to: + +- Keep technical details confidential until the embargo ends or maintainers agree + to earlier disclosure +- Avoid accessing other users’ data beyond the minimum needed to demonstrate impact +- Not degrade production availability as part of testing + +The project will not pursue legal action against good-faith research that +follows this process and applicable law. + +## 5. Change History + +| Version | Date | Notes | +|---------|------|-------| +| 1.0.0 | 2026-09-28 | Initial vulnerability disclosure process (issue #1612) |