From fae9d4e7db6a858c407c75e607a071c533c5c4f6 Mon Sep 17 00:00:00 2001 From: Jay Date: Fri, 5 Jun 2026 08:13:24 +0200 Subject: [PATCH] docs: clarify package update PR policy (#10992) --- .github/PULL_REQUEST_TEMPLATE.md | 1 + .github/copilot-instructions.md | 1 + .github/dependabot.yml | 3 +++ AGENTS.md | 1 + COLLABORATOR_GUIDE.md | 3 +++ CONTRIBUTING.md | 6 ++++++ THREATMODEL.md | 4 ++-- 7 files changed, 17 insertions(+), 2 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index dcacbc2d..64449c8d 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,6 +1,7 @@ diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8c0c5206..561b9898 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -12,6 +12,7 @@ The rules below are a Copilot-facing subset of the load-bearing safety guarantee - Install with `npm ci`; the repo's `.npmrc` sets `ignore-scripts=true`. Do not remove that flag. If husky hooks are needed after a fresh install, run `npm rebuild husky && npx husky` once. - Do not add new runtime dependencies without discussion. `package-lock.json` is verified by `lockfile-lint` for npm HTTPS hosts and integrity hashes. +- Package, lockfile, and GitHub Actions update PRs are maintainer/bot-only; close these PRs from outside collaborators. Keep the 7-day Dependabot delay unless a critical vulnerability requires a maintainer-led manual update. ## Architecture in one screen diff --git a/.github/dependabot.yml b/.github/dependabot.yml index d4ee477e..e0becf33 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,4 +1,7 @@ version: 2 +# Package and GitHub Actions update PRs are maintainer/bot-only. +# Keep the 7-day cooldown unless a critical vulnerability requires a +# maintainer-led manual update. updates: - package-ecosystem: 'github-actions' directory: '/' diff --git a/AGENTS.md b/AGENTS.md index aa3bd738..87e09fef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,7 @@ This file is the canonical contributor guide for both human and AI agents workin - Use `npm ci`; repo `.npmrc` sets `ignore-scripts=true`, and CI also uses `npm ci --ignore-scripts`. - Do not remove `ignore-scripts=true`; if git hooks are needed after a fresh install, run `npm rebuild husky && npx husky` once. - Adding or updating dependencies is security-sensitive; `package-lock.json` is checked by `lockfile-lint` for npm HTTPS hosts and integrity hashes. +- Package, lockfile, and GitHub Actions update PRs are maintainer/bot-only; close these PRs from outside collaborators. Keep the 7-day Dependabot delay unless a critical vulnerability requires a maintainer-led manual update. - Build/test/lint tools still execute dependency code despite `ignore-scripts`; avoid unnecessary full builds when a focused check proves the change. - Do not add new runtime dependencies without discussion; the dependency surface is intentionally tiny. diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index bcb31b3a..bf8ed5ef 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -28,6 +28,8 @@ When opening a PR, make sure: - Cover the change with unit tests. Update browser, smoke, or module suites when packaging or runtime surface is affected. - Lint and tests pass before review. Do not merge red PRs. - Do not add runtime dependencies without discussion. `package-lock.json` changes must keep `lockfile-lint` happy (npm HTTPS hosts, integrity hashes). +- Package and GitHub Actions update PRs are maintainer/bot-only. Close PRs from outside collaborators that only update npm packages, lockfiles, or GitHub Actions versions. +- Keep the 7-day Dependabot delay for these updates. Bypass it only when a critical vulnerability requires a maintainer-led manual update. - Security-sensitive changes get extra scrutiny and focused regression tests. This includes URL construction, redirects, proxy/env handling, XSRF, socket paths, decompression limits, prototype walking, and adapters. Consult [THREATMODEL.md](./THREATMODEL.md). - Warn before removing functionality. - New public API surface is predictable, consistent with existing options, and documented. @@ -48,6 +50,7 @@ If someone reports a suspected vulnerability in a public issue, do not discuss s ## What collaborators should not do - Add runtime dependencies without discussion. The dependency surface is intentionally tiny. +- Merge package, lockfile, or GitHub Actions version update PRs from outside collaborators. - Disable `ignore-scripts` in `.npmrc` or otherwise weaken install-time safety. - Weaken `beforeRedirect`, proxy, `socketPath`, XSRF, or prototype-pollution safeguards without tests covering the regression cases. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ad96d5ac..425819b2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,6 +18,12 @@ Update tests for your changes. Pull requests must pass GitHub Actions. Update the [documentation](https://axios-http.com/docs/intro) when the API changes, so the API and docs stay in sync. +## Dependency and GitHub Actions updates + +Please do not open pull requests that only update npm packages, lockfiles, or GitHub Actions versions. We close these PRs from outside collaborators. Only maintainers and approved automated bots may create package and GitHub Actions update PRs. + +We keep the 7-day Dependabot delay for these updates unless a critical vulnerability requires a maintainer-led manual update. + ## Developing - `npm run test` runs the Jasmine and Mocha tests diff --git a/THREATMODEL.md b/THREATMODEL.md index 94ed3c1c..93807154 100644 --- a/THREATMODEL.md +++ b/THREATMODEL.md @@ -323,7 +323,7 @@ This model protects what gets published as `axios` on npm. A successful attack h | **Description** | Attacker opens a PR with a subtle backdoor: an obfuscated payload in a test fixture, a Unicode homoglyph in a comparison, or a malicious `rollup` plugin in the config. | | **Likelihood** | **High** (attempts are constant on high-profile repos) | | **Impact** | Critical, _if_ it lands | -| **Mitigations** | • Mandatory review before merge.
• `pull_request` workflows run with no secrets and a read-only token, so a malicious test cannot exfiltrate anything from CI.
• `pull_request_target` is not used because it would grant secrets to fork code.
• `zizmor` lints workflow files for known-dangerous patterns.
• Branch protection on `v1.x`.
• Path-scoped `.github/CODEOWNERS` flags sensitive paths explicitly: runtime source (`/lib/`, `/index.*`), build/release infrastructure (`rollup.config.js`, `package.json`, `package-lock.json`, `.npmrc`), CI automation (`.github/workflows/`, `.github/dependabot.yml`, `CODEOWNERS` itself), and security-critical docs (`THREATMODEL.md`, `SECURITY.md`). Changes to these paths surface the scoped ownership rule in the PR review UI distinct from the catch-all. The audit trail shows that the PR touched a sensitive path. | +| **Mitigations** | • Mandatory review before merge.
• `pull_request` workflows run with no secrets and a read-only token, so a malicious test cannot exfiltrate anything from CI.
• `pull_request_target` is not used because it would grant secrets to fork code.
• `zizmor` lints workflow files for known-dangerous patterns.
• Branch protection on `v1.x`.
• Package, lockfile, and GitHub Actions update PRs are maintainer/bot-only; outside-collaborator PRs for those updates are closed.
• Path-scoped `.github/CODEOWNERS` flags sensitive paths explicitly: runtime source (`/lib/`, `/index.*`), build/release infrastructure (`rollup.config.js`, `package.json`, `package-lock.json`, `.npmrc`), CI automation (`.github/workflows/`, `.github/dependabot.yml`, `CODEOWNERS` itself), and security-critical docs (`THREATMODEL.md`, `SECURITY.md`). Changes to these paths surface the scoped ownership rule in the PR review UI distinct from the catch-all. The audit trail shows that the PR touched a sensitive path. | | **Gaps** | • Review is human and fallible. Obfuscated changes to `dist/` (if checked in) or to large test fixtures are hard to spot.
• No automated diffing of `lib/` to `dist/` to catch build-output tampering.
Single-maintainer constraint: with `@jasonsaayman` as sole owner on every scoped path, CODEOWNERS cannot enforce a second reviewer. Two-person review on sensitive paths remains unavailable until a co-maintainer is added. Path-scoping is pre-staged for that event. | --- @@ -393,7 +393,7 @@ Mitigations adopted and recommended. Adopted items are enforced via the repo; ot | **Description** | `follow-redirects`, `form-data`, `proxy-from-env`, or `https-proxy-agent` ships a malicious version. Unlike T-S2, this code ends up in the published axios bundle / runtime rather than being limited to maintainer machines. Every axios consumer runs it. | | **Likelihood** | Low (only 4 deps; all are mature, narrowly-scoped, and watched) | | **Impact** | Critical | -| **Mitigations** | • Three runtime deps total, minimal by design.
• `^` ranges in `package.json` mean consumers may get newer patch versions than the lockfile pins. This is intentional, because consumers get security fixes, but it also means a malicious patch release of `follow-redirects` propagates without an axios release.
• `follow-redirects` is security-conscious and well-maintained; we track its advisories closely (multiple past axios releases were just `follow-redirects` bumps).
• Dependabot is configured (`.github/dependabot.yml`) for both npm and GitHub Actions, running weekly with grouped updates for production and development dependencies. | +| **Mitigations** | • Three runtime deps total, minimal by design.
• `^` ranges in `package.json` mean consumers may get newer patch versions than the lockfile pins. This is intentional, because consumers get security fixes, but it also means a malicious patch release of `follow-redirects` propagates without an axios release.
• `follow-redirects` is security-conscious and well-maintained; we track its advisories closely (multiple past axios releases were just `follow-redirects` bumps).
• Dependabot is configured (`.github/dependabot.yml`) for both npm and GitHub Actions, running weekly with grouped updates for production and development dependencies. The 7-day cooldown stays in place unless a critical vulnerability requires a maintainer-led manual update. | | **Gaps** | • No vendoring/inlining considered. The deps are small enough that vendoring is plausible, but it would forfeit upstream security fixes. Current judgment: not worth it. | ---