|
| 1 | +# Security verification |
| 2 | + |
| 3 | +How to confirm that dependency security issues are addressed. |
| 4 | + |
| 5 | +## 1. Run audits locally |
| 6 | + |
| 7 | +From the **`website/`** directory (where `package-lock.json` and `yarn.lock` live): |
| 8 | + |
| 9 | +```bash |
| 10 | +cd website |
| 11 | +npm audit |
| 12 | +# or |
| 13 | +yarn audit |
| 14 | +``` |
| 15 | + |
| 16 | +If you run `npm audit` from the repo root you’ll get `ENOLOCK` because there is no lockfile there. |
| 17 | + |
| 18 | +- **npm audit**: Uses `package-lock.json`; respects `overrides`. Run after `npm install`. |
| 19 | +- **yarn audit**: Uses `yarn.lock`; respects `resolutions`. Can sometimes return 500 from the registry; use npm audit as fallback. |
| 20 | + |
| 21 | +**Scripts in package.json:** |
| 22 | + |
| 23 | +- `yarn audit` or `npm run audit` — full report |
| 24 | +- `npm run audit:ci` — exits with code 1 only if there are **high** or **critical** issues (useful for CI) |
| 25 | + |
| 26 | +## 2. Check GitHub Dependabot |
| 27 | + |
| 28 | +1. Open the repo on GitHub → **Security** → **Dependabot alerts**. |
| 29 | +2. Alerts that are fixed by your lockfile/overrides should show as **resolved** after the fix is merged (or after Dependabot re-runs). |
| 30 | +3. You can **reopen** a PR or **merge** the security update branch so the default branch has the fixed lockfiles. |
| 31 | + |
| 32 | +## 3. What’s already fixed (overrides) |
| 33 | + |
| 34 | +These are pinned in `package.json` via `resolutions` (Yarn) and `overrides` (npm): |
| 35 | + |
| 36 | +| Package | Pinned version | Alerts addressed | |
| 37 | +|-------------|----------------|-------------------| |
| 38 | +| node-forge | 1.3.2 | ASN.1 recursion, OID truncation, etc. | |
| 39 | +| qs | 6.14.2 | arrayLimit bypass DoS | |
| 40 | +| minimatch | 3.1.2 | ReDoS (3.x line; 10.x has separate fix) | |
| 41 | +| lodash | 4.17.21 | Prototype pollution (_.unset / _.omit) | |
| 42 | +| ajv | ^8.17.0 | ReDoS with `$data` | |
| 43 | +| js-yaml | ^4.1.0 | Prototype pollution in merge | |
| 44 | + |
| 45 | +After changing `package.json` or lockfiles, run **`yarn install`** and/or **`npm install`** in `website/` so the lockfiles reflect these versions. |
| 46 | + |
| 47 | +## 4. Vulnerability checklist (fix one by one) |
| 48 | + |
| 49 | +A full list of all current vulnerabilities with checkboxes, advisory links, and fix steps is in **[VULNERABILITIES.md](./VULNERABILITIES.md)**. Use it to track and fix issues one by one. |
| 50 | + |
| 51 | +## 5. Remaining issues (npm audit) |
| 52 | + |
| 53 | +Many remaining findings come from **transitive dependencies of Docusaurus 3.7.0**, for example: |
| 54 | + |
| 55 | +- **@babel/helpers**, **@babel/runtime** — RegExp complexity (moderate) |
| 56 | +- **minimatch** (high) — ReDoS; advisory may require minimatch 10.x (major upgrade) |
| 57 | +- **lodash** — Prototype pollution; 4.17.21 is latest 4.x (advisory may want a different fix) |
| 58 | +- **mdast-util-to-hast** — Unsanitized class (moderate) |
| 59 | +- **webpack** — SSRF-related (fix available via `npm audit fix`) |
| 60 | +- **brace-expansion**, **diff**, **webpack-dev-server**, etc. |
| 61 | + |
| 62 | +**Ways to reduce remaining issues:** |
| 63 | + |
| 64 | +1. **Upgrade Docusaurus** to 3.9.x (or latest 3.x) so many transitive deps get updated at once. |
| 65 | + - Note: 3.9+ may require Node 20+. |
| 66 | +2. **Apply safe fixes:** |
| 67 | + `npm audit fix` (no `--force`) in `website/` to apply non-breaking fixes. |
| 68 | +3. **Overrides:** Add more `resolutions` / `overrides` only when you know the new version is compatible (e.g. from Docusaurus or advisory “fixed in” version). |
| 69 | +4. **Accept or dismiss:** For dev-only or low-impact advisories, you can document the decision and (if needed) use Dependabot “Dismiss” with a reason. |
| 70 | + |
| 71 | +## 6. CI (optional) |
| 72 | + |
| 73 | +To fail the build when new high/critical issues appear: |
| 74 | + |
| 75 | +```yaml |
| 76 | +# Example (GitHub Actions) |
| 77 | +- run: cd website && npm ci && npm run audit:ci |
| 78 | +``` |
| 79 | +
|
| 80 | +This uses `audit:ci`, which exits with code 1 only for high/critical severity. |
| 81 | + |
| 82 | +## 7. Single lockfile (recommended) |
| 83 | + |
| 84 | +The repo has both `yarn.lock` and `package-lock.json`. Using **one** package manager and **one** lockfile avoids drift and duplicate Dependabot alerts: |
| 85 | + |
| 86 | +- Prefer **Yarn** (as in `packageManager`): delete `package-lock.json`, use only `yarn install` and `yarn.lock`. |
| 87 | +- Or prefer **npm**: remove `packageManager`, delete `yarn.lock`, use only `npm install` and `package-lock.json`. |
| 88 | + |
| 89 | +Then configure Dependabot for that single ecosystem so alerts match what you actually install. |
0 commit comments