Security Report Library - Upgrade Implementation Plan

AUDIT FINDINGS

✅ What Already Works

Data Flow:

CLI → /api/upload → MongoDB → /api/scans → TanStack Query → UI

Architecture:

• ✅ Scan model with summary fields (no need to parse full JSON)
• ✅ TanStack Query with 5-minute caching
• ✅ Manual refresh button
• ✅ User ownership verification
• ✅ Pagination support (limit/skip params in API)
• ✅ ImageKit storage reference
• ✅ Cache cleanup on logout

Data Available:

• scanPath - project/path name
• timestamp - scan date
• totalFindings, criticalCount, highCount, mediumCount, lowCount, infoCount
• sensorsUsed - scanners used
• createdAt - record creation time
• Full scanData.findings array in detail view

What's NOT Available:

• Security score (0-100)
• Scan duration
• Files scanned count
• Project name (separate from path)

❌ What Needs Improvement

1. No Summary Dashboard - Missing overview of security posture
2. No Search - Can't find specific scans
3. No Filters - Can't filter by severity or status
4. No Sorting - Only newest first (hardcoded)
5. Limited Visual Hierarchy - Hard to scan quickly
6. No Security Status Badge - Just raw severity counts
7. Basic Empty State - Could be more helpful
8. No Pagination UI - API supports it, but UI doesn't show it

IMPLEMENTATION PLAN

Phase 1: Summary Dashboard (Top Priority)

Add Summary Cards at Top:

[Total Scans] [Secure Projects] [Critical Issues] [Last Scan]

Data Source:

• Calculated from existing scan array (already fetched)
• NO additional API calls
• NO parsing full reports

Implementation:

const summary = useMemo(() => {
  return {
    totalScans: scans.length,
    secureScans: scans.filter((s) => s.criticalCount === 0 && s.highCount === 0)
      .length,
    criticalIssues: scans.reduce((sum, s) => sum + s.criticalCount, 0),
    lastScan: scans[0]?.createdAt,
  };
}, [scans]);

Phase 2: Search Functionality

Search Field:

[🔍 Search scans by path or project name...]

Implementation:

• Client-side filtering of already-loaded scans
• Search in scanPath field
• Instant, no API calls
• Clear button to reset

Phase 3: Filters

Filter Buttons:

[All] [Secure] [Needs Attention] [Critical Issues]

Filter Logic:

• All: no filter
• Secure: criticalCount === 0 && highCount === 0
• Needs Attention: mediumCount > 0 || lowCount > 0
• Critical Issues: criticalCount > 0

Implementation:

• Client-side filtering
• Show count on each filter button
• Active filter highlighted

Phase 4: Sorting

Sort Dropdown:

Sort: [Newest First ▼]
  - Newest First
  - Oldest First
  - Most Critical
  - Most Issues

Implementation:

• Client-side sorting
• Persist selection in localStorage

Phase 5: Enhanced Scan Cards

Improve Visual Design:

• Add security status badge (Secure/Good/Needs Attention/Critical)
• Better visual hierarchy
• Add quick stats (files scanned if available)
• Hover effects
• Better spacing

Status Calculation:

function getSecurityStatus(scan) {
  if (scan.criticalCount > 0) return "CRITICAL";
  if (scan.highCount > 0) return "NEEDS_ATTENTION";
  if (scan.mediumCount > 0) return "GOOD";
  return "SECURE";
}

Phase 6: Pagination UI

Add Pagination Controls:

[← Previous] [Page 1 of 5] [Next →]

Implementation:

• Use existing API limit/skip params
• Show 20 per page
• Update URL query params (?page=2)
• Maintain during search/filter

Phase 7: Polish

• Skeleton loading states
• Empty states for search/filter
• Responsive mobile design
• Accessibility improvements
• Error recovery

TECHNICAL CONSTRAINTS

DO NOT:

• ❌ Parse full scanData.findings for list view
• ❌ Add new database queries
• ❌ Create new API endpoints
• ❌ Modify CLI upload
• ❌ Change ImageKit integration
• ❌ Use window.location.reload()
• ❌ Break existing 5-minute cache
• ❌ Expose other users' data

DO:

• ✅ Use existing summary fields
• ✅ Client-side filtering/sorting
• ✅ Reuse TanStack Query
• ✅ Maintain existing cache policy
• ✅ Use existing design system
• ✅ Progressive enhancement

IMPLEMENTATION ORDER

1. Summary Dashboard (highest impact, simple)
2. Search (high value, simple)
3. Filters (high value, medium complexity)
4. Enhanced Scan Cards (visual improvement)
5. Sorting (nice to have)
6. Pagination UI (if needed for large datasets)

FILES TO MODIFY

1. app/dashboard/scans/page.tsx - Main scans list
2. components/dashboard/ScanCard.tsx - NEW component
3. components/dashboard/ScansSummary.tsx - NEW component
4. lib/hooks/useScans.ts - Add client-side utils (optional)

FILES NOT TO MODIFY

• ❌ /api/scans/route.ts - Already perfect
• ❌ /api/upload/route.ts - Already working
• ❌ lib/models/Scan.ts - Already has everything
• ❌ CLI files - Not part of this task

PERFORMANCE

Current:

• 1 API call per page load
• Cached 5 minutes
• Lightweight metadata only

After Upgrade:

• Same performance (client-side only)
• No additional API calls
• Same caching behavior
• Faster perceived performance (better UX)

SECURITY

• ✅ User ownership already verified server-side
• ✅ Cache already clears on logout
• ✅ No client-side authorization logic
• ✅ All filtering/sorting client-side (no SQL injection risk)

TESTING CHECKLIST

• Summary calculates correctly
• Search works with partial matches
• Filters show correct scans
• Sorting orders correctly
• Pagination fetches correctly
• Mobile responsive
• Empty states work
• Loading states work
• Error recovery works
• Cache still works
• Logout clears data
• User isolation maintained