Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions Governance/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
90 changes: 90 additions & 0 deletions Governance/SECURITY_RESPONSE_TEAM.md
Original file line number Diff line number Diff line change
@@ -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) |
91 changes: 91 additions & 0 deletions Governance/policies/GOOD_FIRST_ISSUE.md
Original file line number Diff line number Diff line change
@@ -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) |
87 changes: 87 additions & 0 deletions Governance/processes/COORDINATED_DISCLOSURE.md
Original file line number Diff line number Diff line change
@@ -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) |
91 changes: 91 additions & 0 deletions Governance/processes/VULN_DISCLOSURE.md
Original file line number Diff line number Diff line change
@@ -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) |
Loading