Skip to main content
Was this helpful?

Dependency and Security Management

PrimeCal manages dependency risk per lockfile scope:

  • repo root
  • backend-nestjs
  • frontend
  • docs-portal

The source of truth for automated dependency updates is .github/dependabot.yml. Security work is validated through npm audit --audit-level=high, targeted tests, and product-area regression checks.

Dependabot policy​

Dependabot covers:

  • npm updates for /
  • npm updates for /backend-nestjs
  • npm updates for /frontend
  • npm updates for /docs-portal
  • GitHub Actions updates for /.github/workflows

Cadence:

  • npm scopes: weekly
  • GitHub Actions: monthly

Updates are grouped by scope to reduce review noise while still keeping security fixes prompt.

CI security gates​

PrimeCal currently enforces these dependency and security checks:

  • backend security tests
  • MCP security tests
  • raw SQL audit script
  • npm audit --audit-level=high for each dependency scope
  • docs and workflow documentation updates when release policy changes

CodeQL is not a required gate in this pass. Treat it as a follow-up only if the repository owner enables the necessary GitHub private-repo security support.

How to handle an alert​

  1. Group alerts by manifest and package pair instead of reacting to one alert at a time.
  2. Prefer direct dependency upgrades first.
  3. Use the existing Dependabot PR when it matches the needed fix and the release notes are acceptable.
  4. Run the smallest relevant verification immediately after the upgrade.
  5. Run the full local acceptance stack before merge for cross-cutting upgrades.

Examples:

  • backend runtime packages: run backend unit, security, integration, e2e, and MCP lanes
  • frontend build/runtime packages: run frontend lint, tests, build, and any impacted browser coverage
  • docs-portal packages: run docs:check, Docusaurus build, and verify sidebar routing
  • root tooling packages: run the affected repo-level orchestration tests and scripts

Current note:

  • the legacy Newman-based API smoke runner was replaced with scripts/test/test-api.js so root security posture is no longer tied to the vulnerable Postman runtime chain

Temporary backend exception​

The backend still has one documented upstream exception in the GitHub alert view:

  • package cluster: typeorm optional SQLite peer chain (sqlite3, node-gyp, make-fetch-happen, cacache, tar)
  • why upgrade is blocked: the current stable typeorm@0.3.x line still advertises the vulnerable sqlite3 peer in npm metadata, while the typeorm@1.0.0 audit suggestion is a breaking major with no validated migration path for PrimeCal yet
  • current mitigation: PrimeCal now uses better-sqlite3 for the SQLite dev/test path, backend CI installs dependencies with npm --prefix backend-nestjs ci --omit=peer, and backend audit checks run with --omit=peer so the executed dependency graph matches the supported runtime graph
  • owner follow-up: re-check the stable TypeORM release line and npm peer-resolution behavior after billing is restored and hosted CI can be rerun end-to-end; remove this exception as soon as a non-vulnerable stable TypeORM/SQLite path is available

Temporary ignore policy​

Temporary ignores are the exception, not the default. Every ignore must document:

  • exact alert and package
  • why the upgrade is blocked
  • current mitigation
  • owner
  • follow-up action and review date

If a High or Critical alert cannot be fixed immediately, record the mitigation here and in the pull request description. Do not leave undocumented exceptions.

Local security commands​

npm run ci:audit:root
npm run ci:audit:backend
npm run ci:audit:frontend
npm run ci:audit:docs-portal
npm --prefix backend-nestjs run test:security
npm --prefix backend-nestjs run test:mcp:security

Run all four audit commands whenever manifests or lockfiles change.

Hosted verification status​

As of July 10, 2026, GitHub Actions execution is externally blocked by repository billing and spending-limit issues. That is not treated as a code pass. Until billing is restored:

  • local audits and test runs are the acceptance path
  • workflow files must still be kept ready for hosted execution
  • post-billing verification is mandatory before calling the rollout fully complete

Required post-billing follow-up:

  1. Re-run the CI workflow on the feature branch and PR.
  2. Re-check Dependabot PR branches.
  3. Re-open the Dependabot alerts view and confirm no High or Critical items remain unresolved without written mitigation.
  4. Capture workflow screenshots for the docs portal if they are still missing.