Skip to content

fix(automation): allow narrowly scoped Dependabot PRs - #406

Open
dDevAhmed wants to merge 94 commits into
mainfrom
maint/405-dependabot-pr-guard
Open

dDevAhmed wants to merge 94 commits into
mainfrom
maint/405-dependabot-pr-guard

Conversation

@dDevAhmed

@dDevAhmed dDevAhmed commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Linked task

Closes #405

Summary

Adds a narrowly scoped Dependabot path to the Contributor PR Guard without granting merge privileges.

  • npm updates must change exactly package.json and package-lock.json, preserve dependency names and scripts, and validate every resolved direct dependency version against its manifest range.
  • The lockfile validator checks required dependency edges across all retained packages, permits only graph-consistent dev flag changes at the same version, and rejects artifact metadata changes at the same version.
  • Every new or upgraded package tarball URL and integrity digest must exactly match trusted metadata fetched from the official npm registry for the declared package name and version.
  • GitHub Actions updates are parsed as YAML. Only immutable SHA values at jobs.<job_id>.uses and jobs.<job_id>.steps[*].uses can change; environment values and other YAML scalars are not masked.
  • Canonical trailing # vX.Y.Z comments on eligible action-reference lines may change with their SHA; other workflow content and comments remain unchanged.
  • The changed-file list, merge base, and before/after content are pinned to the same immutable PR comparison. Rename checks include both old and new paths.

Scope and safety

  • Only the exact dependabot[bot] login is eligible.
  • The guard policy is loaded from the trusted base revision; its YAML parser is installed from the trusted base lockfile with lifecycle scripts disabled.
  • No Drips assignment or Stellar Wave closing reference is required for this narrow bot path.
  • Out-of-scope paths, package scripts/config changes, added/removed dependency names, workflow logic changes, permission changes, and unpinned action references fail closed.
  • The workflow remains on pull_request with read-only permissions.
  • No write token, auto-merge, or branch-protection bypass is added.

Testing

Verified on head 64b48ad7d07b453abff03eb7c6904f04d0ebd823:

  • Quality: passed (typecheck, lint, formatting, tests, build, actionlint).
  • Linux Node 22 and Node 24: passed.
  • macOS Node 22: passed.
  • Windows Node 22: passed.
  • E2E Smoke: passed.
  • CodeQL: passed.
  • Dependency Review: passed.
  • Contributor PR Guard: passed.

Security

This guard only waives contributor-specific issue/Drips eligibility checks for the verified Dependabot account and tightly allowlisted file diffs. It does not approve or merge the PR and does not bypass CODEOWNERS, human review, or required status checks.

@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Explain Change →

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review

No actionable comments were generated in the recent review.

Walkthrough

The PR adds a classifier for eligible Dependabot npm and GitHub Actions updates. The Contributor PR Guard uses it for Dependabot PRs and retains contributor-specific checks for other PRs. The repository ruleset documentation describes the permitted update scopes and retained restrictions.

Changes: Dependabot PR Guard

Layer / File(s) Summary
Classify npm dependency updates
scripts/pr-guard-policy.cjs, tests/pr-guard-policy.test.ts
The classifier checks the Dependabot account, target branch, title, and changed-file scope. It validates dependency changes in package.json and checks related package-lock.json changes against the changed dependencies’ package closures. Tests cover allowed changes and invalid or out-of-scope updates.
Validate workflow pin updates
scripts/pr-guard-policy.cjs, tests/pr-guard-policy.test.ts
The classifier allows workflow changes when pinned action SHAs change and normalized workflow content, action identities, and reference counts remain unchanged. Tests cover permitted pin changes and rejected workflow modifications.
Route Dependabot PRs through the guard
.github/workflows/wave-pr-guard.yml, docs/contributing/repository-ruleset.md
The workflow supplies changed files and applicable base and head contents to the classifier. Dependabot PRs that pass classification skip linked-issue, assignment, protected-surface label, and PR-body section checks. Other PRs retain their checks. The documentation describes the allowed scopes and retained restrictions.

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Guard as Wave PR Guard workflow
  participant GitHub
  participant Classifier as classifyDependabotPR
  Guard->>GitHub: Fetch changed files and applicable base/head contents
  GitHub-->>Guard: Return changed files and source contents
  Guard->>Classifier: Pass PR metadata, files, and contents
  Classifier-->>Guard: Return allow or deny decision
  alt Classifier allows the update
    Guard->>Guard: Skip contributor-specific checks
  else Classifier denies the update
    Guard->>Guard: Fail the check
  end
Loading

Possibly related issues

  • Issue 290: The PR changes Contributor PR Guard behavior. The supplied context does not establish whether it addresses the issue’s fork-read-only and workflow-permission criteria.
  • Issue 361: The PR adds a Dependabot path and documents retained checks and review requirements. The supplied context does not confirm that all quality, platform, security, and E2E checks in the issue are enforced.
Merge Risk: Moderate · up to 62ec4

This change lets Dependabot npm and GitHub Actions updates bypass the contributor-specific issue and assignment checks. The checks that remain do not fully validate that a lockfile artifact matches its declared version, or that only real action references were edited. They also reject some legitimate Dependabot updates. Normal CI and review requirements still apply, so the risk is bounded. Address the open validation gaps, or explicitly accept them, before merging.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title 'fix(automation): allow narrowly scoped Dependabot PRs' matches the main change. The PR adds a narrow exception in the contributor PR guard that lets exact dependabot[bot] PRs pass contribut…
Linked Issues check Passed Issue #405 is the only active direct target. Its coding requirements are implemented at reviewed head 62ec466.

Incremental review since previous reviewed head efdf59a: the commit history shows one co…
Out of Scope Changes check Passed All changed areas connect to #405 or its stated security intent.
- .github/workflows/wave-pr-guard.yml: adds the bot branch and the non-bot branch, and reads base and head workflow contents. This im…
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Full details: Title check

Explanation

The title 'fix(automation): allow narrowly scoped Dependabot PRs' matches the main change. The PR adds a narrow exception in the contributor PR guard that lets exact dependabot[bot] PRs pass contributor-specific checks for limited npm dependency and GitHub Actions SHA updates. The title is specific, concise, and uses a conventional-commit prefix. It does not mention the lockfile or workflow scope, but that detail is not required.

Full details: Linked Issues check

Explanation

Issue #405 is the only active direct target. Its coding requirements are implemented at reviewed head 62ec466.

Incremental review since previous reviewed head efdf59a: the commit history shows one commit after efdf59a, style: format PR guard policy tests (62ec466). The diffs of scripts/pr-guard-policy.cjs and .github/workflows/wave-pr-guard.yml between efdf59a and 62ec466 returned no content. This is consistent with no change to those files. The prior code-level conclusions are retained for these files.

Requirement mapping, from the prior review at efdf59a:

  1. Exact login [#405 scope 1]: classifyDependabotPR accepts only dependabot[bot]. The workflow routes only that login to the bot path.
  2. npm path [#405 scope 2; acceptance 1]: changed files must equal exactly package.json and package-lock.json. The manifest validator permits only changed dependency version-range strings. The lockfile validator requires v3 data, root and dependency consistency with the manifest, dependency-closure-limited graph changes, and registry URL and integrity metadata for new or updated entries.
  3. Workflow path [#405 scope 2; acceptance 2]: files must be modified .github/workflows/** YAML. Base and head contents are compared after SHA normalization. Only pinned SHA changes are allowed. Reference counts and action names must match, and at least one SHA must change.
  4. Fail-closed [#405 scope 3; acceptance 3]: other paths, non-modified files, mixed npm and workflow sets, unavailable content, and added or removed references are denied. The workflow fails on any rejected decision.
  5. Overlap and protected surfaces [#405 scope 4, 7]: the open-PR overlap loop runs for all PRs. Protected-surface label and Testing/Security body checks apply only to non-bot PRs. CODEOWNERS and rulesets are external controls and are not bypassed.
  6. No Drips or Wave requirement on the bot path [#405 scope 5]: the bot branch skips linked-issue, label, dependency, and assignee checks. The non-bot branch keeps them [acceptance 4].
  7. Permissions [#405 scope 8; acceptance 5]: triggers stay on pull_request. contents, issues, and pull-requests are read. Checkout uses persist-credentials: false. No write permission or auto-merge is added.
  8. Tests [#405 scope 9]: tests/pr-guard-policy.test.ts contains allowed and denied npm, action, and ordering cases. The latest commit only formats this file. I did not read the test file directly.

Not verified here: acceptance item 6 (actionlint and full required CI on the exact head) and independent code-owner approval. These depend on results outside this review.

Full details: Out of Scope Changes check

Explanation

All changed areas connect to #405 or its stated security intent.

  • .github/workflows/wave-pr-guard.yml: adds the bot branch and the non-bot branch, and reads base and head workflow contents. This implements #405 scope 2 and 5.
  • scripts/pr-guard-policy.cjs: contains only the allowlist, manifest, lockfile, and workflow validation for classifyDependabotPR. The file read at efdf59a contained no unrelated behavior. No change to this file appears after efdf59a.
  • tests/pr-guard-policy.test.ts: supporting tests for the new policy. The latest change to this file is formatting only.
  • docs/contributing/repository-ruleset.md: documents the narrow exception and the retained controls. #405 names this guide as authoritative for protected-path review.

No unrelated source, application, release, or permission change appears in the whole-PR summary or in the files reviewed. Limitation: the test file and the documentation file were not read directly.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: fc51e1eb-1963-40f6-9e95-8aec72fa7fd1
Commits

Reviewing files that changed from the base of the PR and between efdf59a and 62ec466.

Files selected for processing: 1

  • tests/pr-guard-policy.test.ts
Files skipped from review as they are similar to previous changes: 1

  • tests/pr-guard-policy.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Comment thread scripts/pr-guard-policy.cjs Fixed
Comment thread scripts/pr-guard-policy.cjs Fixed
@dDevAhmed dDevAhmed closed this Nov 16, 2026
@dDevAhmed dDevAhmed reopened this Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

Security gate — CodeQL finding on current head

The latest exact-head checks for 531dc3b4aa84c0fe1dee0e9098a607115a8e1513 show the normal CI matrix green, but GitHub Advanced Security's CodeQL check is failing with 1 new high-severity alert in code changed by this PR. The separate GitHub Actions CodeQL workflow passed; that does not clear the Advanced Security finding.

Please inspect the alert details in the PR's Code scanning results, identify the affected file and data flow, and fix or provide a narrowly justified false-positive disposition with evidence. Do not suppress or dismiss the alert merely to make the check green. Push the remediation and rerun the full security/CI matrix. Keep this PR draft until the high-severity finding is resolved and the required owner review is obtained.

Copy link
Copy Markdown
Contributor Author

CodeQL remediation pushed

I traced the high-severity CodeQL alert to the semver-range validation regex in scripts/pr-guard-policy.cjs. The repeated alternation plus nested repetition allowed pathological backtracking on long ||-separated dependency strings.

The guard now parses a bounded number of independently validated clauses, rejects strings longer than 128 characters, and limits disjunctions to eight clauses. Added a regression test using a repeated adversarial input. This preserves the accepted simple semver-range forms while removing the vulnerable repeated-group regex.

Please rerun the exact-head CodeQL/CI checks. The PR remains draft pending successful security checks and independent code-owner review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MAINT-SW-002 — Add a least-privilege Dependabot PR Guard path

2 participants