From 62592e98213cff9766c2d8e77e2ae4045146d34a Mon Sep 17 00:00:00 2001 From: jramos Date: Fri, 3 Apr 2026 09:27:12 -0600 Subject: [PATCH] add kiro steering files --- .kiro/steering/product.md | 27 ++++++++++++ .kiro/steering/structure.md | 83 +++++++++++++++++++++++++++++++++++++ .kiro/steering/tech.md | 78 ++++++++++++++++++++++++++++++++++ 3 files changed, 188 insertions(+) create mode 100644 .kiro/steering/product.md create mode 100644 .kiro/steering/structure.md create mode 100644 .kiro/steering/tech.md diff --git a/.kiro/steering/product.md b/.kiro/steering/product.md new file mode 100644 index 0000000..a829ad4 --- /dev/null +++ b/.kiro/steering/product.md @@ -0,0 +1,27 @@ +# Product Overview + +The STEAM Security Dashboard is a self-hosted vulnerability management tool for the NTS-AEO-STEAM and NTS-AEO-ACCESS-ENG business units. It centralizes CVE tracking, Ivanti host finding triage, AEO compliance posture monitoring, FP/Archer exception workflows, and internal documentation in a single interface. + +## Core Capabilities + +- Searchable CVE list with per-vendor tracking and document storage +- NVD API integration for auto-populating CVE metadata +- Ivanti/RiskSense integration for syncing open host findings with FP workflow tracking +- Reporting page with charts, advanced filtering, inline editing, and CSV/XLSX export +- Ivanti Queue for batch-processing FP, Archer, and CARD workflows +- AEO Compliance page with weekly xlsx upload, diff preview, per-team metric health cards, and device-level violation tracking +- Archer risk acceptance ticket tracking (EXC numbers) linked to CVE/vendor pairs +- Knowledge base for internal documentation and policies +- Role-based access control (viewer, editor, admin) with full audit trail + +## User Roles + +| Role | Permissions | +|------|------------| +| viewer | Read-only access to all data | +| editor | All viewer permissions plus create/update operations | +| admin | All editor permissions plus delete, user management, and audit log access | + +## Teams Tracked + +Only **STEAM** and **ACCESS-ENG** teams are tracked in the compliance module. diff --git a/.kiro/steering/structure.md b/.kiro/steering/structure.md new file mode 100644 index 0000000..6979e62 --- /dev/null +++ b/.kiro/steering/structure.md @@ -0,0 +1,83 @@ +# Project Structure & Conventions + +## Directory Layout + +``` +cve-dashboard/ +├── backend/ # Express API server +│ ├── server.js # Main entry point — app setup, middleware, CVE/document routes inline +│ ├── setup.js # One-time DB init + default admin creation +│ ├── cve_database.db # SQLite database (gitignored) +│ ├── uploads/ # File storage (gitignored) +│ ├── routes/ # Express route modules (factory pattern) +│ │ ├── auth.js +│ │ ├── users.js +│ │ ├── auditLog.js +│ │ ├── nvdLookup.js +│ │ ├── knowledgeBase.js +│ │ ├── archerTickets.js +│ │ ├── ivantiWorkflows.js +│ │ ├── ivantiFindings.js +│ │ ├── ivantiTodoQueue.js +│ │ └── compliance.js +│ ├── middleware/ +│ │ └── auth.js # requireAuth(db), requireRole(...roles) +│ ├── helpers/ +│ │ └── auditLog.js # logAudit() — fire-and-forget DB insert +│ ├── migrations/ # Sequential migration scripts (run manually with node) +│ └── scripts/ # Python utilities (compliance parsing, CSV import) +│ +├── frontend/ # React 19 SPA (Create React App) +│ └── src/ +│ ├── App.js # Main dashboard — CVE list, filters, modals, inline styles +│ ├── App.css # Global styles and CSS variables +│ ├── contexts/ +│ │ └── AuthContext.js # Auth state provider (login, logout, role helpers) +│ └── components/ +│ ├── LoginForm.js +│ ├── NavDrawer.js +│ ├── UserMenu.js +│ ├── CalendarWidget.js +│ ├── UserManagement.js +│ ├── AuditLog.js +│ ├── NvdSyncModal.js +│ ├── KnowledgeBaseModal.js +│ ├── KnowledgeBaseViewer.js +│ └── pages/ # Full-page views +│ ├── ReportingPage.js +│ ├── CompliancePage.js +│ ├── ComplianceUploadModal.js +│ ├── ComplianceDetailPanel.js +│ ├── ComplianceChartsPanel.js +│ ├── IvantiCountsChart.js +│ ├── KnowledgeBasePage.js +│ └── ExportsPage.js +│ +├── docs/ # Internal documentation (markdown) +├── start-servers.sh # Start both servers in background +├── stop-servers.sh # Stop both servers +└── DESIGN_SYSTEM.md # UI design system reference (colors, typography, components) +``` + +## Backend Conventions + +- Route modules export a factory function: `function createXxxRouter(db, ...middleware)` that returns an Express Router. +- The `db` (sqlite3 Database instance) is passed via dependency injection from `server.js`. +- Auth middleware: `requireAuth(db)` validates session cookie, attaches `req.user`. `requireRole('editor', 'admin')` checks role. +- All state-changing actions call `logAudit(db, { userId, username, action, entityType, entityId, details, ipAddress })`. +- Input validation is done inline in route handlers with early-return error responses. +- SQLite queries use the callback-based `db.run()`, `db.get()`, `db.all()` API. +- API routes are prefixed with `/api`. All endpoints except login/logout require a valid session cookie. +- CVE and document routes are defined inline in `server.js`; feature routes are in separate modules under `routes/`. + +## Frontend Conventions + +- Single-page app with page-level navigation managed in `App.js` (no React Router). +- Auth state managed via React Context (`AuthContext`). Use `useAuth()` hook for login/logout/role checks. +- API calls use `fetch()` with `credentials: 'include'` for cookie-based auth. +- API base URL from `process.env.REACT_APP_API_BASE`. +- Styling uses a mix of inline style objects (defined as constants in component files) and `App.css` global styles. +- Dark theme with a "tactical intelligence" aesthetic — see `DESIGN_SYSTEM.md` for color palette, typography, and component specs. +- Icons from `lucide-react`. Charts from `recharts`. +- Page components live in `components/pages/`. Shared components live in `components/`. +- No TypeScript — the project uses plain JavaScript throughout. diff --git a/.kiro/steering/tech.md b/.kiro/steering/tech.md new file mode 100644 index 0000000..fee079a --- /dev/null +++ b/.kiro/steering/tech.md @@ -0,0 +1,78 @@ +# Tech Stack & Build System + +## Stack + +| Layer | Technology | +|-------|-----------| +| Backend | Node.js 18+, Express 5 | +| Database | SQLite3 (file: `backend/cve_database.db`) | +| Auth | bcryptjs, cookie-based sessions (httpOnly, 24h expiry) | +| File uploads | Multer 2 (10MB limit) | +| Frontend | React 19 (Create React App / react-scripts 5) | +| UI Icons | lucide-react | +| Charts | recharts | +| Spreadsheet parsing | xlsx (frontend), pandas + openpyxl (backend Python scripts) | +| Markdown rendering | react-markdown | +| Diagrams | mermaid | + +## Common Commands + +### Backend +```bash +cd backend +node setup.js # Initialize DB, tables, indexes, default admin user +node server.js # Start backend on port 3001 +``` + +### Frontend +```bash +cd frontend +npm install # Install dependencies +npm start # Dev server on port 3000 +npm run build # Production build +npm test # Run tests (react-scripts test) +``` + +### Both servers (from project root) +```bash +./start-servers.sh # Start backend + frontend in background +./stop-servers.sh # Stop all servers +``` + +### Database Migrations (run from `backend/` in order) +```bash +node migrations/add_knowledge_base_table.js +node migrations/add_archer_tickets_table.js +node migrations/add_ivanti_sync_table.js +node migrations/add_ivanti_findings_tables.js +node migrations/add_ivanti_todo_queue_table.js +node migrations/add_card_workflow_type.js +node migrations/add_todo_queue_ip_address.js +node migrations/add_compliance_tables.js +``` + +### Python Scripts (from `backend/scripts/`) +```bash +# Compliance xlsx parsing (called automatically by upload flow) +python3 parse_compliance_xlsx.py + +# Bulk notes import +python3 import_notes_from_csv.py input.csv --dry-run +python3 import_notes_from_csv.py input.csv +``` + +Python dependencies: `pandas>=2.0.0`, `openpyxl>=3.0.0` (install via apt or venv). + +## Environment Configuration + +- `backend/.env` — PORT, CORS_ORIGINS, SESSION_SECRET, NVD_API_KEY, Ivanti API credentials +- `frontend/.env` — REACT_APP_API_BASE, REACT_APP_API_HOST +- Both `.env` files are gitignored; see `.env.example` files for templates. +- React caches env vars at build/start time — restart the frontend process after changes. + +## Default Ports + +| Service | URL | +|---------|-----| +| Frontend | http://localhost:3000 | +| Backend API | http://localhost:3001 |