From ecdc548292310475fdc9bf20fe86bd106965bbc8 Mon Sep 17 00:00:00 2001 From: Mir Sameer Date: Fri, 19 Jun 2026 14:11:38 -0700 Subject: [PATCH] Add dependency review gate --- .github/workflows/dependency-review.yml | 26 +++++++++++++++++++++++++ README.md | 5 +++-- SECURITY.md | 11 +++++++++++ docs/BENCHMARK.md | 3 ++- docs/research-notes.md | 4 ++-- docs/validation-report.md | 7 ++++--- 6 files changed, 48 insertions(+), 8 deletions(-) create mode 100644 .github/workflows/dependency-review.yml diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml new file mode 100644 index 0000000..b87eef8 --- /dev/null +++ b/.github/workflows/dependency-review.yml @@ -0,0 +1,26 @@ +name: Dependency Review + +on: + pull_request: + +permissions: + contents: read + +jobs: + dependency-review: + name: Dependency Review + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 + with: + persist-credentials: false + - name: Dependency Review + uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0 + with: + fail-on-severity: moderate + fail-on-scopes: runtime, development + vulnerability-check: true + license-check: true + allow-licenses: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, 0BSD, CC0-1.0, Unlicense + comment-summary-in-pr: never + show-openssf-scorecard: true diff --git a/README.md b/README.md index 3a250ce..e383018 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ [![CI](https://github.com/sameer2191/repolens-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sameer2191/repolens-mcp/actions/workflows/ci.yml) [![CodeQL](https://github.com/sameer2191/repolens-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/sameer2191/repolens-mcp/actions/workflows/codeql.yml) +[![Dependency Review](https://github.com/sameer2191/repolens-mcp/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/sameer2191/repolens-mcp/actions/workflows/dependency-review.yml) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/sameer2191/repolens-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/sameer2191/repolens-mcp) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![Node.js](https://img.shields.io/badge/node-%3E%3D24-339933.svg)](package.json) @@ -38,14 +39,14 @@ RepoLens MCP is an original TypeScript implementation built around fast local ve - **Infrastructure graph nodes**: indexes Dockerfile stages/images, Kubernetes resources, container images, and Kustomize overlays with `DECLARES`, `CONFIGURES`, and `IMPORTS` edges. - **Architecture recommendations**: turns structural hotspots, git-history churn, import-resolved dependency cycles, dead-code candidates, and review signals into concrete next steps. - **Wide practical coverage**: TypeScript, JavaScript, Swift, Python, Go, Java, Rust, SQL, YAML, Markdown, JSON, and shell-oriented project files. -- **Validation evidence**: tests, CI, CodeQL, OpenSSF Scorecard, CycloneDX SBOM generation, GitHub build-provenance attestations, docs, local dashboard smoke checks, and a documented local big-repo validation run. +- **Validation evidence**: tests, CI, Dependency Review, CodeQL, OpenSSF Scorecard, CycloneDX SBOM generation, GitHub build-provenance attestations, docs, local dashboard smoke checks, and a documented local big-repo validation run. - **Architecture decisions built in**: persist ADR-style decisions next to the code graph. - **No frontend build required**: the dashboard is served by the CLI. ## Security And Quality - **Protected mainline**: `main` requires PR review, CODEOWNERS review, fresh branch checks, resolved conversations, linear history, `verify`, and CodeQL `Analyze`; force pushes and branch deletion are blocked. -- **GitHub security coverage**: CodeQL, OpenSSF Scorecard, Dependabot security updates, secret scanning with push protection, private vulnerability reporting, pinned workflow actions, least-privilege workflow tokens, and a release gate that blocks publishing when CodeQL has open alerts. +- **GitHub security coverage**: Dependency Review on pull requests, CodeQL, OpenSSF Scorecard, Dependabot security updates, secret scanning with push protection, private vulnerability reporting, pinned workflow actions, least-privilege workflow tokens, and a release gate that blocks publishing when CodeQL has open alerts. - **Property-based fuzzing**: `fast-check` fuzzes import resolver traversal boundaries, safe alias/source-root/workspace-package resolution, and MCP JSON-RPC tool-call validation in `tests/security-fixes.test.ts` and `tests/mcp-server.test.ts`. - **Release integrity**: npm provenance, GitHub build-provenance attestations, CycloneDX SBOM generation, lockfile dependency graphing, dry-run package validation, and a package contents gate that blocks local graph artifacts from being published. - **Agent-readable docs**: `llms.txt` and `docs/agent-guide.md` give coding agents a concise operating guide, data-boundary rules, and validation commands. diff --git a/SECURITY.md b/SECURITY.md index 08a433b..ee96d3f 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -36,6 +36,17 @@ npm run audit:prod Release publishing also runs dependency audit and CodeQL alert gates before package creation. Tag releases publish npm provenance from a separate privileged job and fail if `NPM_TOKEN` is missing. +## Pull Request Dependency Review + +Pull requests run GitHub Dependency Review with a pinned action SHA. The gate fails when a PR introduces moderate-or-higher vulnerabilities in runtime or development scopes, or dependencies outside the documented permissive license policy. + +Dependency changes should include the normal local checks plus context for why any newly introduced package is needed: + +```bash +npm run verify +npm run audit:prod +``` + ## GitHub Security Summary Maintainers can summarize the live GitHub Security tab state with: diff --git a/docs/BENCHMARK.md b/docs/BENCHMARK.md index 8058833..c11e7cb 100644 --- a/docs/BENCHMARK.md +++ b/docs/BENCHMARK.md @@ -14,7 +14,7 @@ npm run test:skip-gate Latest result: - TypeScript build passed. -- Node test suite passed: 57 tests, 56 passing, 0 failures, 1 sandbox-only dashboard socket skip. +- Node test suite passed: 65 tests, 64 passing, 0 failures, 1 sandbox-only dashboard socket skip. - Test skip gate passed with explicit policies for the dashboard sandbox socket skip and git-unavailable skips. - Coverage includes indexing, incremental refresh, git-aware watch refresh, MCP startup auto-index and auto-sync wiring, project catalog and fleet summaries, graph package import/export, code search, symbol/reference lookup, semantic and vector search, context packs, graph queries, dependency cycles, git-history hotspots, change impact, secret scanning, agent setup, Codex config safeguards, package bootstrap, installer metadata, and MCP JSON-RPC robustness. @@ -33,6 +33,7 @@ GITHUB_REPOSITORY=sameer2191/repolens-mcp GH_TOKEN="" npm run security:gi Current package hygiene: - Production dependency audit reports 0 vulnerabilities. +- Pull requests run a pinned GitHub Dependency Review gate for new moderate-or-higher vulnerabilities across runtime and development scopes. - Package contents are limited to runtime `dist/src`, public docs, README, license/security/contributing files, `llms.txt`, scripts, server manifest, and installers. - Compiled tests, TypeScript source, fixture data, local graph memory, SQLite databases, graph packages, private validation output, and workstation paths are blocked from npm packages. - Installer audit checks shipped shell and PowerShell installers, exercises dry-run Codex/agent setup under temporary home and target directories, and fails if dry runs write unexpected files. diff --git a/docs/research-notes.md b/docs/research-notes.md index 57206a8..053b197 100644 --- a/docs/research-notes.md +++ b/docs/research-notes.md @@ -31,9 +31,9 @@ RepoLens MCP is not a fork or a drop-in static C replacement. It is an original - Browser dashboard without a bundler so the project is easy to build and inspect. - Dashboard APIs expose architecture, fleet summaries, graph schema relationship/property hints, graph search, semantic search, local vector search, reference lookup, read-only graph queries, source snippets, import-resolved dependency cycles, dead-code candidates, graph previews, code search, and live Markdown/HTML architecture reports from the same local server. - Self-contained graph and architecture report exports for sharing HTML or Markdown artifacts without running a server, plus compressed checksummed `.rlgz` graph packages for reusing a SQLite graph without reindexing. A successful index can write a fresh package with `--write-package`, and a missing database can bootstrap from `.repolens/graph.rlgz` before the incremental pass. -- CI runs explicit test-skip governance, type-check, tests, production dependency audit, package dry-run, package contents gating, installer dry-run auditing, CycloneDX SBOM generation, self-indexing, and architecture output; separate workflows cover OpenSSF Scorecard and release build-provenance attestations. +- CI runs explicit test-skip governance, type-check, tests, production dependency audit, package dry-run, package contents gating, installer dry-run auditing, CycloneDX SBOM generation, self-indexing, and architecture output; separate workflows cover Dependency Review, OpenSSF Scorecard, and release build-provenance attestations. - `llms.txt`, `docs/agent-guide.md`, and `docs/BENCHMARK.md` provide concise agent-facing operating instructions, sanitized validation evidence, and local-data boundaries in the npm package. -- `install.ps1` mirrors the Unix installer for Windows users, and `scripts/github-security-summary.mjs` gives maintainers a repeatable GitHub Security tab summary that separates actionable alerts from Scorecard process signals. +- `install.ps1` mirrors the Unix installer for Windows users, Dependency Review blocks risky dependency additions in pull requests, and `scripts/github-security-summary.mjs` gives maintainers a repeatable GitHub Security tab summary that separates actionable alerts from Scorecard process signals. - The release workflow separates unprivileged verify/package work from privileged attestation, GitHub release, and npm publish work. ## Improvements To Highlight diff --git a/docs/validation-report.md b/docs/validation-report.md index 544c31a..38612ce 100644 --- a/docs/validation-report.md +++ b/docs/validation-report.md @@ -21,7 +21,7 @@ npm run test:skip-gate Result: - TypeScript build passed. -- Node test suite passed: 57 tests, 56 passing, 0 failures, 1 sandbox-only dashboard socket skip. +- Node test suite passed: 65 tests, 64 passing, 0 failures, 1 sandbox-only dashboard socket skip. - Test skip gate passed with explicit policies for the dashboard sandbox socket skip and git-unavailable skips. - Covered multi-agent MCP setup rendering/dry-run/write/uninstall behavior, version/update status with npm-compatible registry checks, persistent config list/get/set/reset behavior, Codex MCP config rendering/install/uninstall safeguards including forced replacement of old unmanaged sections, project catalog list/status/delete behavior, fleet summary aggregation with inferred service links, cross-repo fleet graph generation, concurrent catalog writes, decision persistence, repository indexing, benchmark full/no-op incremental evidence, incremental refresh, removed-file pruning, watch-mode refresh, git-aware watch skipping unchanged polls and refreshing dirty worktrees, MCP startup auto-indexing and git-aware auto-sync wiring from env and persisted config, MCP stdio JSON-RPC initialization, tool listing, and invalid tool-call rejection under bounded fuzzing, graph package bootstrap from `.repolens/graph.rlgz`, index-writer locking, graph package export/import, index-time graph package writing with `--write-package`, Swift extraction, Next.js App Router route extraction, GraphQL/protobuf/tRPC/OpenAPI protocol extraction, import-resolved file edge extraction with aliases/workspace packages/relative imports, typed `INHERITS`/`IMPLEMENTS`/`USES_TYPE` relationship extraction, conservative `DATA_FLOWS` extraction, positional argument-to-parameter mapping, ambiguous callee suppression, stale data-flow edge pruning on incremental refresh, trace modes for calls/data-flow/cross-service edges, multi-ecosystem manifest extraction, package-manager lockfile extraction, Dockerfile/Kubernetes/Kustomize graph extraction, channel/event graph extraction with `EMITS` and `LISTENS_ON`, runtime trace ingestion with `OBSERVED_*` edges, symbol search, indexed reference lookup, BM25 code search with camelCase/snake_case token expansion, redacted secret scanning, semantic search, local vector search, context-pack assembly, first-class `http_call` nodes with `CALLS_HTTP_ENDPOINT`, generated `HTTP_CALLS` route-call edges, graph community detection, source snippets, graph schema including relationship patterns and label property hints, structural graph search, read-only Cypher-like graph queries including `DISTINCT`, `count`, `ORDER BY`, `SKIP`, `IN`, and numeric comparisons, relative and workspace-package import cycle resolution, git-history hotspot extraction, history-aware architecture recommendations, architecture recommendations, dead-code candidates, architecture summary, property-based resolver fuzzing, and trace behavior on fixture repositories. @@ -54,9 +54,9 @@ Result: - Production dependency audit passed with `npm run audit:prod`: 0 vulnerabilities. - Package dry run passed for `repolens-mcp@1.0.0`. -- Packed artifact: `repolens-mcp-1.0.0.tgz`, 183,403 bytes packed, 938,818 bytes unpacked, 86 runtime/doc entries. +- Packed artifact: `repolens-mcp-1.0.0.tgz`, 194,979 bytes packed, 997,547 bytes unpacked, 89 runtime/doc entries. - Package contents are scoped to `dist/src`, `README.md`, `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, selected public docs, `llms.txt`, scripts, `package.json`, `server.json`, `install.sh`, and `install.ps1`; compiled tests, source TypeScript, local graph memory, SQLite databases, graph packages, fixtures, private validation output, and local workstation paths are excluded. -- Package contents gate passed: 86 files inspected. +- Package contents gate passed: 89 files inspected. - Installer audit passed for `install.sh` dry-run setup under a temporary home and target directory. `install.ps1` dry-run audit is enforced when `pwsh` is available and in CI. - CycloneDX SBOM generation passed with `npm sbom --sbom-format cyclonedx --json`. - Local installer syntax check passed for `install.sh`; the script verifies Node 24, runs `npm ci`, builds the project, runs `doctor`, can apply `install-codex` with `--dry-run`/`--force` controls, and can render or write project-local setup guidance through `install-agents`. @@ -67,6 +67,7 @@ Result: - `uninstall-codex --dry-run` detected the managed Codex block without writing, and `uninstall-agents` removed generated managed blocks from a temporary project target. - `benchmark` on the fixture repository ran a full index plus no-op incremental index, returned graph totals and throughput, and reported 0 medium/high secret findings. - `index --write-package` on the fixture repository wrote the default `.repolens/graph.rlgz` package and returned graph-package metadata in the index result. +- Dependency Review workflow added for pull requests. It uses pinned `actions/checkout` and pinned `actions/dependency-review-action@v5.0.0`, runs with read-only `contents` permission, and fails on moderate-or-higher vulnerabilities in runtime or development scopes. - Release workflow added for version tags and manual runs. It now separates unprivileged `verify-package` work from privileged `publish` work: package verification runs install, verification, dependency audit, demo indexing, `npm pack --json`, CycloneDX SBOM generation, SHA-256 checksum generation, and artifact upload with read-only contents plus `security-events: read`; tag publishing downloads the verified artifact in a separate job with `contents: write`, `id-token: write`, and `attestations: write`. - Release publishing calls `actions/attest-build-provenance@v2` for the tarball, SBOM, and checksum manifest, uploads GitHub release assets for tags, and publishes the tarball to npm with provenance. - Tag release publishing now fails when `NPM_TOKEN` is missing instead of silently skipping npm publication.