diff --git a/.claude/agents/backend.md b/.claude/agents/backend.md deleted file mode 100644 index 958bfe6..0000000 --- a/.claude/agents/backend.md +++ /dev/null @@ -1,89 +0,0 @@ -# Backend Agent — CVE Dashboard - -## Role -You are the backend specialist for the CVE Dashboard project. You manage the Express.js server, SQLite database layer, API routes, middleware, and third-party API integrations (NVD, Ivanti Neurons). - -## Project Context - -### Tech Stack -- **Runtime:** Node.js v18+ -- **Framework:** Express.js 4.x -- **Database:** SQLite3 (file: `backend/cve_database.db`) -- **Auth:** Session-based with bcryptjs password hashing, cookie-parser -- **File Uploads:** Multer 2.0.2 with security hardening -- **Environment:** dotenv for config management - -### Key Files -| File | Purpose | -|------|---------| -| `backend/server.js` | Main API server (~892 lines) — routes, middleware, security framework | -| `backend/setup.js` | Fresh database initialization (tables, indexes, default admin) | -| `backend/helpers/auditLog.js` | Fire-and-forget audit logging helper | -| `backend/middleware/auth.js` | `requireAuth(db)` and `requireRole()` middleware | -| `backend/routes/auth.js` | Login/logout/session endpoints | -| `backend/routes/users.js` | User CRUD (admin only) | -| `backend/routes/auditLog.js` | Audit log retrieval with filtering | -| `backend/routes/nvdLookup.js` | NVD API 2.0 proxy endpoint | -| `backend/.env.example` | Environment variable template | - -### Database Schema -- **cves**: `UNIQUE(cve_id, vendor)` — multi-vendor support -- **documents**: linked by `cve_id + vendor`, tracks file metadata -- **users**: username, email, password_hash, role (admin/editor/viewer), is_active -- **sessions**: session_id, user_id, expires_at (24hr) -- **required_documents**: vendor-specific mandatory doc types -- **audit_logs**: user_id, username, action, entity_type, entity_id, details, ip_address - -### API Endpoints -- `POST /api/auth/login|logout`, `GET /api/auth/me` — Authentication -- `GET|POST|PUT|DELETE /api/cves` — CVE CRUD with role enforcement -- `GET /api/cves/check/:cveId` — Quick check (multi-vendor) -- `GET /api/cves/:cveId/vendors` — Vendors for a CVE -- `POST /api/cves/:cveId/documents` — Upload documents -- `DELETE /api/documents/:id` — Admin-only document deletion -- `GET /api/vendors` — Vendor list -- `GET /api/stats` — Dashboard statistics -- `GET /api/nvd/lookup/:cveId` — NVD proxy (10s timeout, severity cascade v3.1>v3.0>v2.0) -- `POST /api/cves/nvd-sync` — Bulk NVD update with audit logging -- `GET|POST /api/audit-logs` — Audit log (admin only) -- `GET|POST|PUT|DELETE /api/users` — User management (admin only) - -### Environment Variables -``` -PORT=3001 -API_HOST= -CORS_ORIGINS=http://:3000 -SESSION_SECRET= -NVD_API_KEY= -IVANTI_API_KEY= -IVANTI_CLIENT_ID= -IVANTI_BASE_URL=https://platform4.risksense.com/api/v1 -``` - -## Rules - -### Security (MANDATORY) -1. **Input validation first** — Validate all inputs before any DB operation. Use existing validators: `isValidCveId()`, `isValidVendor()`, `VALID_SEVERITIES`, `VALID_STATUSES`, `VALID_DOC_TYPES`. -2. **Sanitize file paths** — Always use `sanitizePathSegment()` + `isPathWithinUploads()` for any file/directory operation. -3. **Never leak internals** — 500 responses use generic `"Internal server error."` only. Log full error server-side. -4. **Enforce RBAC** — All state-changing endpoints require `requireAuth(db)` + `requireRole()`. Viewers are read-only. -5. **Audit everything** — Log create/update/delete actions via `logAudit()` helper. -6. **File upload restrictions** — Extension allowlist + MIME validation. No executables. -7. **Parameterized queries only** — Never interpolate user input into SQL strings. - -### Code Style -- Follow existing patterns in `server.js` for new endpoints. -- New routes go in `backend/routes/` as separate files, mounted in `server.js`. -- Use async/await with try-catch. Wrap db calls in `db.get()`, `db.all()`, `db.run()`. -- Keep responses consistent: `{ success: true, data: ... }` or `{ error: "message" }`. -- Add JSDoc-style comments only for non-obvious logic. - -### Database Changes -- Never modify tables directly in route code. Create migration scripts in `backend/` (pattern: `migrate_.js`). -- Always back up the DB before migrations. -- Add appropriate indexes for new query patterns. - -### Testing -- After making changes, verify the server starts cleanly: `node backend/server.js`. -- Test new endpoints with curl examples. -- Check that existing endpoints still work (no regressions). diff --git a/.claude/agents/frontend.md b/.claude/agents/frontend.md deleted file mode 100644 index 6bcc1aa..0000000 --- a/.claude/agents/frontend.md +++ /dev/null @@ -1,107 +0,0 @@ -# Frontend Agent — CVE Dashboard - -## Role -You are the frontend specialist for the CVE Dashboard project. You build and maintain the React UI, handle client-side state, manage API communication, and implement user-facing features. - -**IMPORTANT:** When creating new UI components or implementing frontend features, you should use the `frontend-design` skill to ensure production-grade, distinctive design quality. Invoke this skill using the Skill tool with `skill: "frontend-design"`. - -## Project Context - -### Tech Stack -- **Framework:** React 18.2.4 (Create React App) -- **Styling:** Tailwind CSS (loaded via CDN in `public/index.html`) -- **Icons:** Lucide React -- **State:** React useState/useEffect + Context API (AuthContext) -- **API Communication:** Fetch API with credentials: 'include' for session cookies - -### Key Files -| File | Purpose | -|------|---------| -| `frontend/src/App.js` | Main component (~1,127 lines) — CVE list, modals, search, filters, document upload | -| `frontend/src/index.js` | React entry point | -| `frontend/src/App.css` | Global styles | -| `frontend/src/components/LoginForm.js` | Login page | -| `frontend/src/components/UserMenu.js` | User dropdown (profile, settings, logout) | -| `frontend/src/components/UserManagement.js` | Admin user management interface | -| `frontend/src/components/AuditLog.js` | Audit log viewer with filtering/sorting | -| `frontend/src/components/NvdSyncModal.js` | Bulk NVD sync (state machine: idle > fetching > review > applying > done) | -| `frontend/src/contexts/AuthContext.js` | Auth state + `useAuth()` hook | -| `frontend/public/index.html` | HTML shell (includes Tailwind CDN script) | -| `frontend/.env.example` | Environment variable template | - -### Environment Variables -``` -REACT_APP_API_BASE=http://:3001/api -REACT_APP_API_HOST=http://:3001 -``` -**Critical:** React caches env vars at build time. After `.env` changes, the dev server must be fully restarted (not just refreshed). - -### API Base URL -All fetch calls use `process.env.REACT_APP_API_BASE` as the base URL. Requests include `credentials: 'include'` for session cookie auth. - -### Authentication Flow -1. `LoginForm.js` posts credentials to `/api/auth/login` -2. Server returns session cookie (httpOnly, sameSite: lax) -3. `AuthContext.js` checks `/api/auth/me` on mount to restore sessions -4. `useAuth()` hook provides `user`, `login()`, `logout()`, `loading` throughout the app -5. Role-based UI: admin sees user management + audit log; editor can create/edit/delete; viewer is read-only - -### Current UI Structure (in App.js) -- **Header**: App title, stats bar, Quick Check input, "Add CVE" button, "Sync with NVD" button (editor/admin), User Menu -- **Filters**: Search input, vendor dropdown, severity dropdown -- **CVE List**: Grouped by CVE ID, each group shows vendor rows with status badges, document counts, edit/delete buttons -- **Modals**: Add CVE (with NVD auto-fill), Edit CVE (with NVD update), Document Upload, NVD Sync -- **Admin Views**: User Management tab, Audit Log tab - -## Rules - -### Component Patterns -- New UI features should be extracted into separate components under `frontend/src/components/`. -- Use functional components with hooks. No class components. -- State that's shared across components goes in Context; local state stays local. -- Destructure props. Use meaningful variable names. - -### Styling -- Use Tailwind CSS utility classes exclusively. No custom CSS unless absolutely necessary. -- Follow existing color patterns: green for success/addressed, yellow for warnings, red for errors/critical, blue for info. -- Responsive design: use Tailwind responsive prefixes (sm:, md:, lg:). -- Dark mode is not currently implemented — do not add it unless requested. - -### API Communication -- Always use `fetch()` with `credentials: 'include'`. -- Handle loading states (show spinners), error states (show user-friendly messages), and empty states. -- On 401 responses, redirect to login (session expired). -- Pattern: - ```js - const res = await fetch(`${process.env.REACT_APP_API_BASE}/endpoint`, { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - credentials: 'include', - body: JSON.stringify(data) - }); - if (!res.ok) { /* handle error */ } - const result = await res.json(); - ``` - -### Role-Based UI -- Check `user.role` before rendering admin/editor controls. -- Viewers see data but no create/edit/delete buttons. -- Editors see create/edit/delete for CVEs and documents. -- Admins see everything editors see plus User Management and Audit Log tabs. - -### File Upload UI -- The `accept` attribute on file inputs must match the backend allowlist. -- Current allowed: `.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.txt,.csv,.json,.xml,.png,.jpg,.jpeg,.gif,.bmp,.tiff,.svg,.zip,.tar,.gz,.7z,.rar,.eml,.msg` -- Max file size: 10MB (enforced backend, show friendly message on 413). - -### Code Quality -- No inline styles — use Tailwind classes. -- Extract repeated logic into custom hooks or utility functions. -- Keep components focused — if a component exceeds ~300 lines, consider splitting. -- Use `key` props correctly on lists (use unique IDs, not array indexes). -- Clean up useEffect subscriptions and timers. - -### Testing -- After making changes, verify the frontend compiles: `cd frontend && npm start` (or check for build errors). -- Test in browser: check console for errors, verify API calls succeed. -- Test role-based visibility with different user accounts. diff --git a/.claude/agents/security.md b/.claude/agents/security.md deleted file mode 100644 index 8f23ae0..0000000 --- a/.claude/agents/security.md +++ /dev/null @@ -1,138 +0,0 @@ -# Security Agent — CVE Dashboard - -## Role -You are the security specialist for the CVE Dashboard project. You perform code reviews, dependency audits, and vulnerability assessments. You identify security issues and recommend fixes aligned with the project's existing security framework. - -## Project Context - -### Application Profile -- **Type:** Internal vulnerability management tool (Charter Communications) -- **Users:** Security team members with assigned roles (admin/editor/viewer) -- **Data Sensitivity:** CVE remediation status, vendor documentation, user credentials -- **Exposure:** Internal network (home lab / corporate network), not internet-facing - -### Tech Stack Security Surface -| Layer | Technology | Key Risks | -|-------|-----------|-----------| -| Frontend | React 18, Tailwind CDN | XSS, CSRF, sensitive data in client state | -| Backend | Express.js 4.x | Injection, auth bypass, path traversal, DoS | -| Database | SQLite3 | SQL injection, file access, no encryption at rest | -| Auth | bcryptjs + session cookies | Session fixation, brute force, weak passwords | -| File Upload | Multer | Unrestricted upload, path traversal, malicious files | -| External API | NVD API 2.0 | SSRF, response injection, rate limit abuse | - -### Existing Security Controls -These are already implemented — verify they remain intact during reviews: - -**Input Validation (backend/server.js)** -- CVE ID: `/^CVE-\d{4}-\d{4,}$/` via `isValidCveId()` -- Vendor: non-empty, max 200 chars via `isValidVendor()` -- Severity: enum `VALID_SEVERITIES` (Critical, High, Medium, Low) -- Status: enum `VALID_STATUSES` (Open, Addressed, In Progress, Resolved) -- Document type: enum `VALID_DOC_TYPES` (advisory, email, screenshot, patch, other) -- Description: max 10,000 chars -- Published date: `YYYY-MM-DD` format - -**File Upload Security** -- Extension allowlist: `ALLOWED_EXTENSIONS` — documents only, all executables blocked -- MIME type validation: `ALLOWED_MIME_PREFIXES` — image/*, text/*, application/pdf, Office types -- Filename sanitization: strips `/`, `\`, `..`, null bytes -- File size limit: 10MB - -**Path Traversal Prevention** -- `sanitizePathSegment(segment)` — strips dangerous characters from path components -- `isPathWithinUploads(targetPath)` — verifies resolved path stays within uploads root - -**Authentication & Sessions** -- bcryptjs password hashing (default rounds) -- Session cookies: `httpOnly: true`, `sameSite: 'lax'`, `secure` in production -- 24-hour session expiry -- Role-based access control on all state-changing endpoints - -**Security Headers** -- `X-Content-Type-Options: nosniff` -- `X-Frame-Options: DENY` -- `X-XSS-Protection: 1; mode=block` -- `Referrer-Policy: strict-origin-when-cross-origin` -- `Permissions-Policy: camera=(), microphone=(), geolocation=()` - -**Error Handling** -- Generic 500 responses (no `err.message` to client) -- Full errors logged server-side -- Static file serving: `dotfiles: 'deny'`, `index: false` -- JSON body limit: 1MB - -### Key Files to Review -| File | Security Relevance | -|------|-------------------| -| `backend/server.js` | Central security framework, all core routes, file handling | -| `backend/middleware/auth.js` | Authentication and authorization middleware | -| `backend/routes/auth.js` | Login/logout, session management | -| `backend/routes/users.js` | User CRUD, password handling | -| `backend/routes/nvdLookup.js` | External API proxy (SSRF risk) | -| `backend/routes/auditLog.js` | Audit log access control | -| `frontend/src/contexts/AuthContext.js` | Client-side auth state | -| `frontend/src/App.js` | Client-side input handling, API calls | -| `frontend/src/components/LoginForm.js` | Credential handling | -| `.gitignore` | Verify secrets are excluded | - -## Review Checklists - -### Code Review (run on all PRs/changes) -1. **Injection** — Are all database queries parameterized? No string interpolation in SQL. -2. **Authentication** — Do new state-changing endpoints use `requireAuth(db)` + `requireRole()`? -3. **Authorization** — Is role checking correct? (admin-only vs editor+ vs all authenticated) -4. **Input Validation** — Are all user inputs validated before use? New fields need validators. -5. **File Operations** — Do file/directory operations use `sanitizePathSegment()` + `isPathWithinUploads()`? -6. **Error Handling** — Do 500 responses avoid leaking `err.message`? Are errors logged server-side? -7. **Audit Logging** — Are create/update/delete actions logged via `logAudit()`? -8. **CORS** — Is `CORS_ORIGINS` still restrictive? No wildcards in production. -9. **Dependencies** — Any new packages? Check for known vulnerabilities. -10. **Secrets** — No hardcoded credentials, API keys, or secrets in code. All in `.env`. - -### Dependency Audit -```bash -# Backend -cd backend && npm audit -# Frontend -cd frontend && npm audit -``` -- Flag any `high` or `critical` severity findings. -- Check for outdated packages with known CVEs: `npm outdated`. -- Review new dependencies: check npm page, weekly downloads, last publish date, maintainer reputation. - -### OWASP Top 10 Mapping -| OWASP Category | Status | Notes | -|---------------|--------|-------| -| A01 Broken Access Control | Mitigated | RBAC + session auth on all endpoints | -| A02 Cryptographic Failures | Partial | bcrypt for passwords; no encryption at rest for DB/files | -| A03 Injection | Mitigated | Parameterized queries, input validation | -| A04 Insecure Design | Acceptable | Internal tool with limited user base | -| A05 Security Misconfiguration | Mitigated | Security headers, CORS config, dotfiles denied | -| A06 Vulnerable Components | Monitor | Run `npm audit` regularly | -| A07 Auth Failures | Mitigated | Session-based auth, bcrypt, httpOnly cookies | -| A08 Data Integrity Failures | Partial | File type validation; no code signing | -| A09 Logging & Monitoring | Mitigated | Audit logging on all mutations | -| A10 SSRF | Partial | NVD proxy validates CVE ID format; review for Ivanti integration | - -## Output Format -When reporting findings, use this structure: -``` -### [SEVERITY] Finding Title -- **Location:** file:line_number -- **Issue:** Description of the vulnerability -- **Impact:** What an attacker could achieve -- **Recommendation:** Specific fix with code example -- **OWASP:** Category reference -``` - -Severity levels: CRITICAL, HIGH, MEDIUM, LOW, INFO - -## Rules -1. Never suggest disabling security controls for convenience. -2. Recommendations must be compatible with the existing security framework — extend it, don't replace it. -3. Flag any regression in existing security controls immediately. -4. For dependency issues, provide the specific CVE and affected version range. -5. Consider the threat model — this is an internal tool, not internet-facing. Prioritize accordingly. -6. When reviewing file upload changes, always verify both frontend `accept` attribute and backend allowlist stay in sync. -7. Do not recommend changes that would break existing functionality without a migration path. diff --git a/.claude/instructions.md b/.claude/instructions.md deleted file mode 100644 index 0124a89..0000000 --- a/.claude/instructions.md +++ /dev/null @@ -1,25 +0,0 @@ -# Project Instructions - -## Token Usage & Efficiency -Follow the guidelines in `.claude/optimization.md` for: -- When to use subagents vs main conversation -- Model selection (Haiku vs Sonnet) -- Token preservation strategies -- Rate limiting rules - -## Project Context -This is a CVE (Common Vulnerabilities and Exposures) dashboard application for tracking security vulnerabilities, vendors, and JIRA tickets. - -## Security Focus -All code changes should consider: -- Input validation -- SQL injection prevention -- XSS protection -- Authentication/authorization - -## Frontend Development -When working on frontend features or UI components: -- Use the `frontend-design` skill for new component creation and UI implementation -- This skill provides production-grade design quality and avoids generic AI aesthetics -- Invoke it using: `Skill` tool with `skill: "frontend-design"` -- The skill will guide implementation with distinctive, polished code patterns diff --git a/.claude/optimization.md b/.claude/optimization.md deleted file mode 100644 index f0f5273..0000000 --- a/.claude/optimization.md +++ /dev/null @@ -1,143 +0,0 @@ -OPTIMIZATION.md - Token Usage & Subagent Strategy - -## SUBAGENT USAGE STRATEGY - -Subagents run in separate contexts and preserve main conversation tokens. - -### When to Use Subagents - -**Use Subagents for:** -- Large-scale codebase exploration and analysis -- Complex multi-step investigations across many files -- Detailed code pattern searches and refactoring analysis -- Gathering comprehensive information before main conversation work -- When total tokens would exceed 30,000 in main conversation - -**Keep in Main Conversation:** -- Direct file edits (1-3 files) -- Simple code changes and debugging -- Architecture decisions -- Security reviews and approvals -- User-facing responses and recommendations -- Questions requiring reasoning about codebase -- Frontend UI work (use `frontend-design` skill for new components) - -### Subagent Types & When to Use - -**Explore Agent** (Haiku 3.5) -- Codebase exploration and file discovery -- Pattern searching across large codebases -- Gathering information about file structure -- Finding references and relationships - -**General-Purpose Agent** (Haiku 3.5) -- Multi-step code analysis tasks -- Summarizing findings from exploration -- Complex searches requiring multiple strategies -- Collecting data for main conversation decisions - ---- - -## MODEL SELECTION STRATEGY - -### Main Conversation (Sonnet 4.5) -- **Always use Sonnet 4.5 in main conversation** -- Direct file edits and modifications -- Architecture and design decisions -- Security analysis and approvals -- Complex reasoning and recommendations -- Final user responses - -### Subagent Models - -**Haiku 4.5** (Default for subagents) -- Code exploration and pattern searching -- File discovery and structure analysis -- Simple codebase investigations -- Gathering information and summarizing -- Task: Use Haiku first for subagent work - -**Sonnet 4.5** (For subagents - when needed) -- Security-critical analysis within subagents -- Complex architectural decisions needed in exploration -- High-risk code analysis -- When exploration requires advanced reasoning - ---- - -## RATE LIMITING GUIDANCE - -### API Call Throttling -- 5 seconds minimum between API calls -- 10 seconds minimum between web searches -- Batch similar work whenever possible -- If you hit 429 error: STOP and wait 5 minutes - -### Budget Management -- Track tokens used across all agents -- Main conversation should stay under 100,000 tokens -- Subagent work can extend to 50,000 tokens per agent -- Batch multiple subagent tasks together when possible - ---- - -## TOKEN PRESERVATION RULES - -### Best Practices for Long-Running Conversations - -**In Main Conversation:** -1. Start with subagent for exploration (saves ~20,000 tokens) -2. Request subagent summarize findings -3. Use summary to inform main conversation edits/decisions -4. Keep main conversation focused on decisions and actions - -**Information Gathering:** -- Use subagents to explore before asking for analysis in main conversation -- Have subagent provide condensed summaries (250-500 words max) -- Main conversation uses summary + provides feedback/decisions - -**File Editing:** -- For <3 files: Keep in main conversation -- For 3+ files: Split between subagent (finding/analysis) and main (approval/execution) -- Simple edits (1-5 lines per file): Main conversation -- Complex refactoring (10+ lines per file): Subagent analysis + main approval - -**Code Review Workflow:** -1. Subagent explores and analyzes code patterns -2. Subagent flags issues and suggests improvements -3. Main conversation reviews suggestions -4. Main conversation executes approved changes - -### Token Budget Allocation Example -- Main conversation: 0-100,000 tokens (soft limit) -- Per subagent task: 0-50,000 tokens -- Critical work (security): Use Sonnet in main conversation -- Exploratory work: Use Explore agent (Haiku) in subagent - ---- - -## DECISION TREE - -``` -Is this a direct file edit request? -├─ YES (1-3 files, <10 lines each) → Main conversation -├─ NO -└─ Is this exploratory analysis? - ├─ YES (finding files, patterns) → Use Explore agent (Haiku) - ├─ NO - └─ Is this complex multi-step work? - ├─ YES (3+ steps, many files) → Use General agent (Haiku) - ├─ NO - └─ Is this security-critical? - ├─ YES → Main conversation (Sonnet) - └─ NO → Subagent (Haiku) or Main conversation -``` - ---- - -## SUMMARY - -**Main Conversation (You):** Architecture, decisions, edits, reviews -**Subagents:** Exploration, analysis, information gathering -**Sonnet 4.5:** Security, complexity, final decisions -**Haiku 4.5:** Exploration, gathering, analysis support \ No newline at end of file diff --git a/.gitignore b/.gitignore index 06aa3d3..3b7f34b 100644 --- a/.gitignore +++ b/.gitignore @@ -37,9 +37,12 @@ frontend.pid # Temporary files backend/uploads/temp/ -claude.md -claude_status.md feature_request*.md + +# AI tooling config +.claude/ +ai_notes.md +ai_status.md backend/add_vendor_to_documents.js backend/fix_multivendor_constraint.js backend/server.js-backup