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/ against Vite dev server (CSV export flow) |
Integration tests under tests/integration/ currently cover NVD pagination against a local HTTP mirror with AIRGAPPED=true (nvd-pagination.test.ts). Additional integration specs are tracked in #78. 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 |
E2E (tests/e2e/export.spec.ts) requires Playwright Chromium — install 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.