Operations and troubleshooting¶
This chapter covers day-two operations, failure modes, and security notes for teams hosting CVE Intelligence Panel internally.
Performance¶
Full scans over many tools without NVD_API_KEY may take several minutes. Run during maintenance windows. Watch mode should remain lightweight if NVD is excluded.
Common issues¶
| Symptom | Likely cause | Action |
|---|---|---|
Too many scan requests / RATE_LIMITED |
App middleware (scan or watch bucket) | Wait retryAfterSec; close extra tabs; raise RATE_LIMIT_* in .env; restart server |
| Empty NVD results | NVD upstream rate limit | Add NVD_API_KEY, reduce stack size, retry |
| Stale source times | Fetch failed | Check network; read server logs |
| Translation stuck | Provider down | Disable auto-translate temporarily; use English UI |
| False-positive match | Heuristic tool name | Refine stack naming; manual triage |
| No new watch items | knownIds already contains CVE |
Expected; verify with full scan |
Security¶
- Do not expose the API publicly without authentication.
- Keep
GITHUB_TOKENandNVD_API_KEYin server env only. - RSS and external JSON are untrusted input — server parses defensively.
Upgrades¶
After git pull, run npm install, make build, restart process. Clear browser cache if i18n keys change between versions. v1.1.0 adds the setup wizard and stack-keyed scan cache — existing stacks are auto-migrated; new installs walk through the wizard once.
Automated testing¶
| Suite | Command | Scope |
|---|---|---|
| Unit + API | make test |
tests/server/, tests/client/, tests/integration/ |
| Coverage (CI) | npm run test:ci |
Same + lcov for Codecov/Sonar |
| E2E (Playwright) | npm run test:e2e:install once, then npm run test:e2e |
tests/e2e/ — CSV export, Live Watch tab, tenant notification prefs (mock API) |
Integration tests under tests/integration/ cover NVD pagination (nvd-pagination.test.ts), OSV bulk air-gap (osv-bulk-scan.test.ts), GitLab mirror prefetch (gitlab-mirror-prefetch.test.ts), and multi-tenant API round-trips (multi-tenant-api.test.ts). See CONTRIBUTING.md for PR checks.
Test coverage (CI baseline)¶
The Node test runner (npm test) currently runs 257 specs across server unit tests, client helpers, and integration mirrors. CI coverage (npm run test:ci) reports roughly 94% lines, 82% branches, and 94% functions (V8 lcov → Codecov/SonarCloud).
| Area | Example files |
|---|---|
| Notifications | tests/server/notifications.test.ts, notificationEmail.test.ts, notificationTelegram.test.ts |
| Middleware | tenantContext.test.ts, scanTimeout.test.ts, securityHeaders.test.ts |
| Data layer | pool.test.ts, tenants.test.ts, tenantsDb.integration.test.ts |
| Client helpers | exportVulns.test.ts, iconAssets.test.ts, scanCache.test.ts |
| Integration | tests/integration/nvd-pagination.test.ts, osv-bulk-scan.test.ts, multi-tenant-api.test.ts, gitlab-mirror-prefetch.test.ts |
E2E: tests/e2e/export.spec.ts, watch.spec.ts, tenant-prefs.spec.ts — install Chromium once with npm run test:e2e:install.
Documentation maintenance¶
Product changes must update all six extended-docs/docs/content/{locale}/ trees, src/i18n/messages/*.ts, and legacy docs/ when applicable. Follow agent rule code-to-docs-sync (agent/rules/code-to-docs-sync.mdc) — path→doc mapping, glossary, and scripts/check-extended-docs-locale-sync.sh.
For audit logs, RBAC, tenants, metrics, airgap, and Kubernetes discovery, see Self-hosted operations.