From e026aa91133efa2e712e1916dea90a79812c399f Mon Sep 17 00:00:00 2001 From: Ulises Gascon Date: Mon, 2 Jun 2025 14:25:28 +0200 Subject: [PATCH 1/3] docs: handle OSSF Scorecard analysis --- docs/scorecard_review.md | 138 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 docs/scorecard_review.md diff --git a/docs/scorecard_review.md b/docs/scorecard_review.md new file mode 100644 index 0000000..6d95d61 --- /dev/null +++ b/docs/scorecard_review.md @@ -0,0 +1,138 @@ +# Scorecard Handling and Review Process +**Version:** 1.0 +**Last Updated:** June 2025 +**Maintainers:** Express.js Security WG + +--- + +## Introduction + +This document defines the formal process for handling and reviewing the OpenSSF Scorecard reports in the Express.js organization. The process ensures continuous monitoring of the security posture of our repositories and encourages action when reasonable improvements can be made. + +## Scope + +This process applies to all repositories listed under [packages in scope](../docs/packages-in-scope.md), which defines the minimum required scope for Scorecard monitoring by the Security WG. Additional repositories may be monitored at the discretion of the team but are not required. + +The process is managed and executed by the [Security WG](../README.md#team-members-expressjssecurity-wg). + +--- + +## Scorecard Monitoring Flowchart + +```mermaid +flowchart TD + A[Scorecard Job Runs — Scheduled or Manual] --> B[Automation Generates Report & PR] + B --> C[Issue Created with Summary] + C --> D[Review Deltas Against Previous Report] + + D --> E{Any Significant Regression or Warning?} + + E -- No --> G[Mark Issue as Reviewed — No Action Needed] + + E -- Yes --> F[Determine Actionability] + F --> H{Action Required?} + + H -- No --> G + H -- Yes --> I[File Follow-up Issue or PR in Affected Repo] + I --> J[Track Status in Security WG] + + G --> K[Close Scorecard Tracking Issue] + J --> K + +``` + + +## Automation Overview + +The [OpenSSF Scorecard Monitor](https://github.com/ossf/scorecard-monitor) GitHub Action is configured to run in the `security-wg` repository on a biweekly schedule ([ref](../.github/workflows/ossf-scorecard-reporting.yml)) (every Sunday at 00:00 UTC) and can also be triggered manually via the GitHub UI. + +This workflow does not perform Scorecard scans directly. Instead, it collects and aggregates results from participating repositories within the Express.js GitHub organizations that proactively report their own Scorecard data to the OSSF Scorecard API. + +The workflow performs the following: + +- Discovers repositories to include in the report using the config at `tools/ossf_scorecard/scope.json`. +- Collects previously generated Scorecard metadata from those repositories. +- Aggregates the results into: + - A Scorecard database: `tools/ossf_scorecard/database.json`. + - A human-readable Markdown report: `tools/ossf_scorecard/report.md`. +- Creates a GitHub issue with a summary of the findings. +- Opens a GitHub Pull Request with updated files. + +Example artifacts: +- PR: [OpenSSF Scorecard Report updated (PR #69)](https://github.com/expressjs/security-wg/pull/69). +- Issue: [OpenSSF Scorecard Report updated! (Issue #68)](https://github.com/expressjs/security-wg/issues/68). + +> [!NOTE] +> 🔧 Participating repositories must individually configure and run `ossf/scorecard` as a scheduled workflow to generate up-to-date results. The monitor workflow does not perform scans itself — it only collects and aggregates existing reports. + +> [!TIP] +> You can close the issue when merging the PR using [GitHub linking](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) capabilities + +## Responsibilities + +The Security WG is responsible for reviewing the OSSF Scorecard reports and assessing the relevance and severity of changes. + +**Responsibilities** +- Compare score changes with previous results +- Evaluate whether recommendations are relevant, actionable, and within policy +- Recommend and/or implement improvements if necessary +- Record the review outcome in the tracking issue + + +## Runbook + +### Step 0: Trigger & Report Generation + +The Scorecard job runs on a scheduled basis (every 2 weeks) or can be manually triggered. This generates: + +- Updated results in `tools/ossf_scorecard` +- A PR with the updated data +- A tracking issue for discussion + +> [!WARNING] +> The job runs against repositories listed in [`packages-in-scope.md`](https://github.com/expressjs/security-wg/blob/main/docs/packages-in-scope.md). If additional repos are monitored, results may include those as well. + + +### Step 1: Review Scorecard Deltas + +Reviewers should analyze the changes in Scorecard results between the current and previous reports, with particular attention to: + +- **Significant regressions** — such as a drop in high-priority checks like `Branch-Protection`, `Token-Permissions`, or `Maintained`. +- **New warnings or failures** — especially in checks that were previously passing. +- **Improvements** — even when a check has improved, reviewers should determine whether follow-up action is still required (e.g., enabling a security control that remains optional). + +> [!TIP] +> The Scorecard Monitor report includes links to [ossf/scorecard-visualizer](https://github.com/ossf/scorecard-visualizer), which you can use to visually compare results between two repository commit hashes. + + +### Step 2: Determine Relevance and Policy Alignment + +Not all Scorecard recommendations apply equally across Express repositories. For example: + +- **Action Pinning:** The organization follows its own policy as documented in [ADR 366](https://github.com/expressjs/discussions/blob/master/docs/adr/366-action-pinning.md) +- **Token Permissions:** Some recommendations may not align with our workflow model + +When encountering a new or changed recommendation: +- Refer to relevant ADRs or internal policies +- Use team judgment to assess whether a change is actionable and necessary + + +### Step 3: Take Action or Acknowledge + +If a change requires action: +- File a follow-up issue or PR in the affected repository +- Optionally, reference the Scorecard tracking issue for context + +If no action is needed: +- Comment in the issue that the change was reviewed and no further work is planned + +Once the PR is merged and review is complete: +- Close the tracking issue + + + +## Notes & Best Practices + +- Scorecard monitoring is not a compliance checklist — it is a decision-making tool. +- Document exceptions and decisions clearly in the tracking issues. +- If a recommendation recurs or spreads across multiple repositories, consider an ADR or organization-wide policy update. From 0cd0c7e28033ef9112d10dadb63302ac4282508c Mon Sep 17 00:00:00 2001 From: Ulises Gascon Date: Mon, 2 Jun 2025 14:31:24 +0200 Subject: [PATCH 2/3] ci: add once a month cron for OSSF Scrorecard reporting --- .github/workflows/ossf-scorecard-reporting.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ossf-scorecard-reporting.yml b/.github/workflows/ossf-scorecard-reporting.yml index dcb3fa7..284f848 100644 --- a/.github/workflows/ossf-scorecard-reporting.yml +++ b/.github/workflows/ossf-scorecard-reporting.yml @@ -1,7 +1,9 @@ name: OpenSSF Scorecard Monitor on: - # TODO: replace by CRON trigger once a deccision is made + schedule: + # Runs on the first Sunday of each month at 00:00 UTC + - cron: '0 0 1-7 * 0' # Manual trigger workflow_dispatch: From 80d352626cad9b5c085f71382878631a43882d0f Mon Sep 17 00:00:00 2001 From: Ulises Gascon Date: Mon, 2 Jun 2025 14:44:49 +0200 Subject: [PATCH 3/3] docs: align with current cron definition --- docs/scorecard_review.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/scorecard_review.md b/docs/scorecard_review.md index 6d95d61..e0d886a 100644 --- a/docs/scorecard_review.md +++ b/docs/scorecard_review.md @@ -44,7 +44,7 @@ flowchart TD ## Automation Overview -The [OpenSSF Scorecard Monitor](https://github.com/ossf/scorecard-monitor) GitHub Action is configured to run in the `security-wg` repository on a biweekly schedule ([ref](../.github/workflows/ossf-scorecard-reporting.yml)) (every Sunday at 00:00 UTC) and can also be triggered manually via the GitHub UI. +The [OpenSSF Scorecard Monitor](https://github.com/ossf/scorecard-monitor) GitHub Action is configured to run in the `security-wg` repository on a monthly schedule ([ref](../.github/workflows/ossf-scorecard-reporting.yml)) (on the first Sunday of each month at 00:00 UTC) and can also be triggered manually via the GitHub UI. This workflow does not perform Scorecard scans directly. Instead, it collects and aggregates results from participating repositories within the Express.js GitHub organizations that proactively report their own Scorecard data to the OSSF Scorecard API. @@ -83,7 +83,7 @@ The Security WG is responsible for reviewing the OSSF Scorecard reports and asse ### Step 0: Trigger & Report Generation -The Scorecard job runs on a scheduled basis (every 2 weeks) or can be manually triggered. This generates: +The Scorecard job runs on a scheduled basis (once a month) or can be manually triggered. This generates: - Updated results in `tools/ossf_scorecard` - A PR with the updated data