From d587424a8d78945f52cab5349ead10674fecf18f Mon Sep 17 00:00:00 2001 From: acossa Date: Mon, 11 May 2026 09:54:29 +0200 Subject: [PATCH 1/3] ci(scorecard): scope publish permissions to job --- .github/workflows/scorecard.yml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index a41a469..c1d679f 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -11,13 +11,15 @@ on: permissions: contents: read - id-token: write - security-events: write jobs: scorecard: name: Scorecard analysis runs-on: ubuntu-latest + permissions: + contents: read + id-token: write + security-events: write steps: - name: Run Scorecard uses: ossf/scorecard-action@f49aabe0b5af0936a0987cfb85d86b75731b0186 From b27d52859457268672f043b404715df679f30e9f Mon Sep 17 00:00:00 2001 From: acossa Date: Mon, 11 May 2026 09:54:32 +0200 Subject: [PATCH 2/3] ci(codeql): add static analysis workflow --- .github/workflows/codeql.yml | 43 ++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 .github/workflows/codeql.yml diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..de9ee43 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,43 @@ +# CodeQL static analysis workflow. +# Author: Admilson B. F. Cossa +# SPDX-License-Identifier: Apache-2.0 + +name: CodeQL + +on: + workflow_dispatch: + pull_request: + branches: + - main + push: + branches: + - main + schedule: + - cron: "37 4 * * 1" + +permissions: + contents: read + +jobs: + analyze: + name: CodeQL analysis + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write + strategy: + fail-fast: false + matrix: + language: + - javascript-typescript + steps: + - name: Checkout + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd + + - name: Initialize CodeQL + uses: github/codeql-action/init@68bde559dea0fdcac2102bfdf6230c5f70eb485e + with: + languages: ${{ matrix.language }} + + - name: Analyze + uses: github/codeql-action/analyze@68bde559dea0fdcac2102bfdf6230c5f70eb485e From f517a79df80e1465b44d540f218d7ad00f301eb3 Mon Sep 17 00:00:00 2001 From: acossa Date: Mon, 11 May 2026 09:54:36 +0200 Subject: [PATCH 3/3] docs(security): document OpenSSF badge process --- OPENSSF-BEST-PRACTICES.md | 78 +++++++++++++++++++++++++++++++++++++++ SECURITY.md | 25 ++++++++++--- 2 files changed, 97 insertions(+), 6 deletions(-) create mode 100644 OPENSSF-BEST-PRACTICES.md diff --git a/OPENSSF-BEST-PRACTICES.md b/OPENSSF-BEST-PRACTICES.md new file mode 100644 index 0000000..73269e3 --- /dev/null +++ b/OPENSSF-BEST-PRACTICES.md @@ -0,0 +1,78 @@ + + +# OpenSSF Best Practices Process + +WorkIt uses the OpenSSF Best Practices badge as a public supply-chain hygiene +checklist. The badge must not be shown as passing until the project entry exists +and the checklist is complete. + +## Goal + +Use the OpenSSF Best Practices process to verify and document: + +- public source availability +- Apache-2.0 licensing +- security policy and private vulnerability reporting +- reproducible verification commands +- CI on pull requests and `main` +- dependency update automation +- vulnerability auditing +- static analysis +- signed releases and npm provenance +- package contents discipline + +## Required Public Evidence + +Before claiming badge status, verify these repository facts: + +```sh +npm run verify +npm run test:coverage +npm run test:evidence +npm run bench:articles +npm pack --dry-run --json +``` + +The public evidence files are: + +```txt +README.md +SECURITY.md +CONTRIBUTING.md +CODE_OF_CONDUCT.md +LICENSE +evidence/claims.json +evidence/README.md +benchmarks/results/articles.latest.json +.github/workflows/ci.yml +.github/workflows/codeql.yml +.github/workflows/scorecard.yml +.github/workflows/release-provenance.yml +.github/dependabot.yml +``` + +## External Badge Steps + +1. Create the WorkIt project entry at the OpenSSF Best Practices site. +2. Fill in the public repository URL: `https://github.com/WorkRuntime/workit`. +3. Link the security policy: `SECURITY.md`. +4. Link the license: `LICENSE`. +5. Link the CI workflow and verification commands. +6. Link the CodeQL workflow after the first successful run. +7. Link the release provenance workflow and the latest GitHub release. +8. Record any checklist items that are intentionally deferred. +9. Add the badge to `README.md` only after the badge URL exists. + +## Deferred Items + +These checks require project maturity or a deliberate future feature: + +- broader contributor diversity +- long-term maintenance age +- recognized fuzzing integration +- external security review + +Do not fake these items. Track them as roadmap work until real evidence exists. diff --git a/SECURITY.md b/SECURITY.md index 264fe96..7c796bf 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -63,17 +63,22 @@ npm pack --dry-run --json ``` The provenance workflow is defined in `.github/workflows/release-provenance.yml`. -Registry dry-runs and real publication are intentionally blocked while -`package.json` has `private: true`. Final release requires a separate scoped -commit that proves `@workit` npm scope ownership, flips `private` to `false`, -and runs: +Registry dry-runs and real publication must be triggered only from a signed +release tag after the scoped release commit is clean and verified. The publish +step runs: ```sh npm publish --provenance --access public --dry-run ``` -The package must not publish source maps, local docs, tests, secrets, temporary -files, debug output, or private agent instructions. +for dry runs, and: + +```sh +npm publish --provenance --access public +``` + +for an approved release. The package must not publish source maps, local docs, +tests, secrets, temporary files, debug output, or private agent instructions. Release tags must be signed. The release operator must create the version tag only after the scoped release commit is clean and verified: @@ -85,6 +90,14 @@ git tag -v vX.Y.Z Unsigned release tags are not valid release evidence. +## OpenSSF Best Practices + +The OpenSSF Best Practices badge is tracked as a public supply-chain hygiene +process, not as a marketing badge. The project must not claim a passing badge +until the external OpenSSF checklist is completed and the project entry exists. + +The process is documented in `OPENSSF-BEST-PRACTICES.md`. + ## Responsible Disclosure Scope Reports are in scope when they affect: