Skip to content

dependency-scanning.md

Latest commit

 

History

History
49 lines (33 loc) · 3.33 KB

dependency-scanning.md

File metadata and controls

49 lines (33 loc) · 3.33 KB
Raw

Dependency & Code Scanning

This repository runs automated dependency and code vulnerability scanning on Pull Requests.

Workflows added:

  • .github/workflows/audit.yml — runs npm audit --audit-level=high on PRs. Fails the job if any vulnerabilities at severity high or critical are found.
  • .github/workflows/codeql.yml — runs GitHub CodeQL analysis for JavaScript/TypeScript.

Suppression policy

  • Temporary suppression can be applied by adding the label audit/suppress to the PR. When present, the npm audit step is skipped but the label and rationale should be recorded in the PR description.

Blocking PRs on high/critical findings

  • Configure branch protection for the main branch and require the Code scanning status checks and the Dependency audit (npm) workflow to pass. This repository cannot change branch protection automatically — an administrator must enable the protections in the repository settings.

Guidance for maintainers

  • To run the audit locally: npm run audit.
  • For CI: npm run audit:ci.
  • To enforce stricter rules, update .github/workflows/audit.yml or add additional guard steps.

Notes

  • The CodeQL workflow creates code scanning alerts in the repository Security tab. Use the Security -> Code scanning alerts view to triage findings. Critical or high issues should be fixed or an explicit risk acceptance recorded.

Software Bill of Materials (SBOM)

Two CycloneDX SBOMs are generated per release build (tag push), as part of the container-scan job in .github/workflows/ci.yml:

  • sbom.app.cyclonedx.json — the application's npm production dependency tree, generated by @cyclonedx/cyclonedx-npm via npm run sbom. devDependencies are omitted by default (matching the npm audit --omit=dev convention above); pass --include-dev to include them.
  • sbom.container.cyclonedx.json — the full built container image, generated by trivy image --format cyclonedx. This includes OS packages (Alpine apk packages from the node:20-alpine base image) in addition to the application dependencies, since Trivy introspects the image filesystem rather than just package-lock.json.

Both SBOMs are:

  1. Uploaded as workflow artifacts (sbom artifact, always).
  2. Uploaded to the supply-chain security portal, if configured (see below).
  3. Attached to the GitHub Release for the tag.

Portal upload

npm run sbom:upload -- --file <sbom file> (scripts/upload-sbom.ts) posts the SBOM to a Dependency-Track-compatible POST /api/v1/bom endpoint. Configure it via repository secrets:

  • SBOM_PORTAL_URL — base URL of the portal, e.g. https://dtrack.example.com.
  • SBOM_PORTAL_API_KEY — API key with BOM upload permission.

If either secret is unset, the upload step logs a message and exits successfully (no-op) — useful for forks or before the portal is provisioned. If the secrets are set but the portal is unreachable, the script retries 3 times with linear backoff before failing; the workflow step is marked continue-on-error so a portal outage doesn't block the release itself, but the failure is still visible in the Actions run.

To run either script locally:

npm run sbom                                    # writes sbom.cyclonedx.json
SBOM_PORTAL_URL=... SBOM_PORTAL_API_KEY=... npm run sbom:upload -- --file sbom.cyclonedx.json