From 71571b2a5fc99a0966c70c87b0bb9ab77aebcde7 Mon Sep 17 00:00:00 2001 From: Alex Smith Date: Tue, 28 Jul 2026 20:58:33 -0400 Subject: [PATCH 1/2] docs: advertise supply-chain hardening in READMEs and correct SECURITY.md Adds Socket.dev, OpenSSF Scorecard, npm provenance, and security-policy badges plus a 'Hardened by default' section to all four READMEs. The two npm-published package READMEs are the highest-leverage place to say this and previously said nothing. Package READMEs use absolute URLs so links survive rendering on npmjs.com. SECURITY.md corrections: - Socket.dev and CodeQL were invisible in-repo (both dashboard-configured) - cooldown exceptions described as prettier-only; there are more - bestax-migrate missing from the supported-versions table - provenance said 'both packages'; there are three Closes #403 --- README.md | 23 +++++++++++++++++++++++ SECURITY.md | 37 +++++++++++++++++++++++++++++-------- bestax-migrate/README.md | 22 ++++++++++++++++++++++ bulma-ui/README.md | 20 ++++++++++++++++++++ create-bestax/README.md | 18 ++++++++++++++++++ 5 files changed, 112 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 56921c2fc..cfab40fa5 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,10 @@ [![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen.svg)](https://github.com/allxsmith/bestax/blob/main/bulma-ui/jest.config.js) [![Bulma](https://img.shields.io/badge/Bulma-v1.0+-00d1b2.svg)](https://bulma.io) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Socket Badge](https://socket.dev/api/badge/npm/package/@allxsmith/bestax-bulma)](https://socket.dev/npm/package/@allxsmith/bestax-bulma/overview) +[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax) +[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/@allxsmith/bestax-bulma#provenance) +[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) TypeScript-first React component library for the **Bulma v1** CSS framework โ€” 80+ fully typed components โ€” plus a project scaffolder and AI agent tooling. @@ -173,6 +177,25 @@ Building with an AI agent (Claude Code, Cursor, Copilot)? bestax-bulma ships LLM --- +## ๐Ÿ”’ Hardened by default + +Supply-chain security here is a standing constraint on how the project is built, not a checklist we filled in once: + +- **Signed provenance on every release** โ€” each tarball carries a sigstore attestation linking it to the exact commit and CI run that produced it. Check it yourself with `npm audit signatures`, or on the package page's Provenance section. +- **npm OIDC trusted publishing** โ€” releases authenticate with short-lived, per-run tokens. There is no long-lived `NPM_TOKEN` in this repo to steal. +- **Signed release commits** โ€” release commits and tags are GPG-signed, and `main` rejects unsigned commits outright. +- **Socket.dev scans every PR** โ€” dependency changes are checked for malware, install scripts, obfuscated code, and privilege escalation before they can reach `main`. +- **Every GitHub Action pinned to a full commit SHA** โ€” no movable tags, so a compromised action release can't roll silently into the pipeline. +- **Install scripts blocked by default** โ€” dependency `install`/`postinstall` scripts don't run unless explicitly allow-listed one at a time, each with a written rationale ([`pnpm-workspace.yaml`](pnpm-workspace.yaml)). +- **3-day dependency cooldown** โ€” freshly published versions won't install. This is the main defense against account-takeover worms, which are usually yanked within hours. +- **Frozen lockfile + audit gate** โ€” CI installs exactly what the reviewed lockfile resolves and fails on high-severity advisories. +- **CodeQL, Dependency Review, and Dependabot** โ€” static analysis over both the source and the workflow files, PR-level advisory blocking, and weekly grouped dependency updates. +- **Layered AI review before merge** โ€” every PR gets a [CodeRabbit](https://coderabbit.ai) review plus an independent adversarial Claude review that deliberately runs a different model from the one writing AI-authored changes. On top of that, `main` requires green CI, one approving review, and a human merge. AI agents are structurally barred from editing the workflows, release config, or supply-chain settings that gate them. + +Full detail: [`SECURITY.md`](SECURITY.md) ยท [Security guide](https://bestax.io/docs/guides/security) + +--- + ## ๐Ÿ’ฌ Community - [Discord](https://discord.gg/zehJrQGtKu) diff --git a/SECURITY.md b/SECURITY.md index 6516ca849..c1f37e178 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -3,15 +3,16 @@ ## Supported Versions Security fixes land on the **latest release line only** โ€” currently -`@allxsmith/bestax-bulma` 5.x and `create-bestax` 3.x. Both packages release -automatically from `main` (semantic-release), so the latest published version -is always the patched one. Older majors may still work but receive no security -updates; please upgrade. +`@allxsmith/bestax-bulma` 5.x, `create-bestax` 3.x, and `bestax-migrate` 1.x. +All three packages release automatically from `main` (semantic-release), so the +latest published version is always the patched one. Older majors may still work +but receive no security updates; please upgrade. | Package | Supported | Unsupported | | ------------------------- | ------------ | ----------- | | `@allxsmith/bestax-bulma` | 5.x (latest) | < 5.0 | | `create-bestax` | 3.x (latest) | < 3.0 | +| `bestax-migrate` | 1.x (latest) | โ€” | ## Supply-Chain Security @@ -22,8 +23,12 @@ Measures active in this repository and its release pipeline: (`allowBuilds` in `pnpm-workspace.yaml`). - **Dependency cooldown** โ€” by default, versions published less than 3 days ago won't install (`minimumReleaseAge`), defending against just-published - malicious releases. One dev-only exception: `prettier` is excluded (and - pinned) so formatting stays deterministic; it is never shipped to users. + malicious releases. Exceptions are listed in `minimumReleaseAgeExclude` and + are the deliberate minority: `prettier` is excluded (and pinned) so + formatting stays deterministic and is never shipped to users, and an + individual package may be excluded temporarily to pull an urgent security + patch in ahead of the cooldown โ€” each such entry carries an inline rationale + and a removal date. - **Isolated `node_modules`** โ€” pnpm's isolated linker prevents phantom (undeclared) dependencies from being imported. - **Frozen lockfile in CI** โ€” builds and releases install with @@ -31,7 +36,7 @@ Measures active in this repository and its release pipeline: reviewed lockfile resolves. (The React 18/19 compatibility matrix is the one deliberate exception: it re-resolves to pin the requested React major for testing, and never publishes.) -- **npm provenance** โ€” both published packages set +- **npm provenance** โ€” all three published packages set `publishConfig.provenance`, so every release carries a signed attestation linking the tarball to the exact commit and CI run that built it. - **OIDC trusted publishing** โ€” releases authenticate to npm with @@ -39,11 +44,27 @@ Measures active in this repository and its release pipeline: to steal. - **SHA-pinned GitHub Actions** โ€” every third-party action is pinned to a full commit SHA, not a movable tag. +- **Socket.dev** โ€” the Socket GitHub App reviews every pull request for + malware, install scripts, obfuscated code, and privilege escalation in + dependency changes, and posts two required checks. Its policy is managed in + the Socket dashboard rather than in this repository, so it has no config + file here. - **CodeQL** โ€” GitHub code scanning runs on JavaScript/TypeScript and the - workflow files themselves. + workflow files themselves. It uses GitHub's _default setup_, so there is no + `codeql.yml` in `.github/workflows/`. +- **OpenSSF Scorecard** โ€” `.github/workflows/scorecard.yml` scores this + repository's supply-chain posture weekly and publishes the result publicly. - **Dependency review** โ€” a workflow blocks PRs that introduce dependencies with known advisories. - **Dependabot** โ€” weekly, grouped dependency update PRs. +- **Protected `main`** โ€” unsigned commits, force pushes, and branch deletion + are rejected. Merges require green CI (`Build and Test`, the React 18/19 + compatibility matrix, and `Dependency Review`) plus an approving review. +- **Layered automated review** โ€” every PR is reviewed by CodeRabbit and by an + independent adversarial Claude review that deliberately runs a different + model from the one used to write AI-authored changes. AI agents working in + this repository are barred from modifying the workflows, release + configuration, or supply-chain settings that gate them. Consumers can verify provenance themselves: the npm package pages show the attestation ("Provenance" section), and โ€” in projects installed with the npm diff --git a/bestax-migrate/README.md b/bestax-migrate/README.md index 3f7512d0e..2a952c291 100644 --- a/bestax-migrate/README.md +++ b/bestax-migrate/README.md @@ -1,5 +1,13 @@ # bestax-migrate +[![npm version](https://img.shields.io/npm/v/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate) +[![npm downloads](https://img.shields.io/npm/dm/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Socket Badge](https://socket.dev/api/badge/npm/package/bestax-migrate)](https://socket.dev/npm/package/bestax-migrate/overview) +[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax) +[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/bestax-migrate#provenance) +[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) + Codemods that migrate existing React apps to [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) โ€” the actively maintained React component library for **Bulma v1**. Currently supported source libraries: @@ -54,6 +62,20 @@ npx skills add https://github.com/allxsmith/bestax --skill bestax-migrate Full walkthrough: [react-bulma-components migration guide](https://bestax.io/docs/guides/getting-started/migration/react-bulma-components). +## Hardened by default + +A codemod rewrites your source in place, so how it is built and published matters: + +- **Signed provenance** โ€” every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/bestax-migrate#provenance), or run `npm audit signatures`. +- **npm OIDC trusted publishing** โ€” short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed. +- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`. +- **The libraries this tool migrates away from are never installed here** โ€” source fixtures are read as text only, so no unmaintained third-party package enters the dependency tree. +- **Dependencies are a deliberate act** โ€” install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves. +- **Every GitHub Action is pinned to a full commit SHA**, and CodeQL, Dependency Review, and Dependabot run continuously alongside a high-severity `pnpm audit` gate. +- **Layered AI review before merge** โ€” [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge. + +Full detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) ยท [Security guide](https://bestax.io/docs/guides/security) + ## License MIT ยฉ Alex Smith diff --git a/bulma-ui/README.md b/bulma-ui/README.md index 57a0275ec..48cee96ba 100644 --- a/bulma-ui/README.md +++ b/bulma-ui/README.md @@ -7,6 +7,10 @@ [![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen.svg)](https://github.com/allxsmith/bestax/blob/main/bulma-ui/jest.config.js) [![Bulma](https://img.shields.io/badge/Bulma-v1.0+-00d1b2.svg)](https://bulma.io) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Socket Badge](https://socket.dev/api/badge/npm/package/@allxsmith/bestax-bulma)](https://socket.dev/npm/package/@allxsmith/bestax-bulma/overview) +[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax) +[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/@allxsmith/bestax-bulma#provenance) +[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) TypeScript-first React component library for the **Bulma v1** CSS framework โ€” 80+ fully typed, tree-shakeable components, including extras like Carousel, Dialog, Sidebar, Steps, and date/time pickers. @@ -124,6 +128,22 @@ View the package on npmjs: --- +## ๐Ÿ”’ Hardened by default + +This package is one runtime dependency deep (Bulma) and is published under a deliberately strict pipeline: + +- **Signed provenance** โ€” every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Verify it in the **Provenance** section of the [npm page](https://www.npmjs.com/package/@allxsmith/bestax-bulma#provenance), or run `npm audit signatures` in your project. +- **npm OIDC trusted publishing** โ€” short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed. +- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`. +- **Dependencies are a deliberate act** โ€” install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves. +- **Every GitHub Action is pinned to a full commit SHA**, so a compromised action release can't roll silently into a build of this package. +- **CodeQL, Dependency Review, and Dependabot** run continuously, alongside a high-severity `pnpm audit` gate. +- **Layered AI review before merge** โ€” [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge. + +Full detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) ยท [Security guide](https://bestax.io/docs/guides/security) + +--- + ## ๐Ÿ“š Documentation **For full documentation, guides, and best practices, please use our official docs site:** diff --git a/create-bestax/README.md b/create-bestax/README.md index e1b268bc9..91003984d 100644 --- a/create-bestax/README.md +++ b/create-bestax/README.md @@ -3,6 +3,10 @@ [![npm version](https://img.shields.io/npm/v/create-bestax.svg)](https://www.npmjs.com/package/create-bestax) [![npm downloads](https://img.shields.io/npm/dm/create-bestax.svg)](https://www.npmjs.com/package/create-bestax) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Socket Badge](https://socket.dev/api/badge/npm/package/create-bestax)](https://socket.dev/npm/package/create-bestax/overview) +[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax) +[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/create-bestax#provenance) +[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) The scaffolder for [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) โ€” spin up a Vite app pre-wired for the **Bulma v1** React component library in one command. Picks your framework (JS or TypeScript), CSS flavor, and icon library, and can drop in the bestax **AI skills** so an agent like Claude Code knows the library from the first prompt. @@ -127,6 +131,20 @@ npm run typecheck # Type check CLI source code **Note on Templates:** Template files in `templates/` are excluded from linting. They should be manually validated by scaffolding a test project and running lint/build there before releasing. +## Hardened by default + +A scaffolder runs with write access to your filesystem and picks your starting dependencies, so how it is built and published matters: + +- **Signed provenance** โ€” every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/create-bestax#provenance), or run `npm audit signatures`. +- **npm OIDC trusted publishing** โ€” short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed. +- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`. +- **Dependencies are a deliberate act** โ€” install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves. +- **Every GitHub Action is pinned to a full commit SHA**, so a compromised action release can't roll silently into a build of this CLI. +- **CodeQL, Dependency Review, and Dependabot** run continuously, alongside a high-severity `pnpm audit` gate. +- **Layered AI review before merge** โ€” [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge. + +Full detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) ยท [Security guide](https://bestax.io/docs/guides/security) + ## Publishing This package uses semantic-release with scope-based rules. Only commits with `feat(create-bestax)` or `fix(create-bestax)` will trigger releases. From 180bd6b8030d0b6bdf009fef9c3410490510370b Mon Sep 17 00:00:00 2001 From: Alex Smith Date: Wed, 29 Jul 2026 06:24:58 -0400 Subject: [PATCH 2/2] docs: don't call Socket's checks 'required' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Socket posts two checks on every PR, but they are not in main's required_status_checks โ€” only Build and Test, the React 18/19 matrix, and Dependency Review are. Caught by deep review on #407. --- SECURITY.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index c1f37e178..db09e2dc9 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -46,9 +46,9 @@ Measures active in this repository and its release pipeline: full commit SHA, not a movable tag. - **Socket.dev** โ€” the Socket GitHub App reviews every pull request for malware, install scripts, obfuscated code, and privilege escalation in - dependency changes, and posts two required checks. Its policy is managed in - the Socket dashboard rather than in this repository, so it has no config - file here. + dependency changes, and posts two checks on every pull request. Its policy + is managed in the Socket dashboard rather than in this repository, so it has + no config file here. - **CodeQL** โ€” GitHub code scanning runs on JavaScript/TypeScript and the workflow files themselves. It uses GitHub's _default setup_, so there is no `codeql.yml` in `.github/workflows/`.