shortcommings

tasks/core-services-implementation/13-correlation-engine.md

@@ -0,0 +1,81 @@
+# 13. Cross-Service Threat Correlation Scoring and Unified Alert Feed
+
+meta:
+  id: core-services-13
+  feature: core-services-implementation
+  priority: P2
+  depends_on: [core-services-05, core-services-07, core-services-08]
+  tags: [correlation, threat-scoring, unified-alerts, intelligence, dashboard]
+
+objective:
+- Activate the correlation service to cross-reference findings across VoicePrint, DarkWatch, SpamShield, HomeTitle, and RemoveBrokers, generating unified threat scores and correlated alert narratives that explain multi-vector attacks.
+
+deliverables:
+- Cross-service correlation rules (e.g., breached email + spam call from same source = coordinated attack)
+- Unified threat score algorithm (0–100) per user and per family member
+- Correlated alert narratives: "Your email was breached on Monday, and today you received a spam call to that number — this may be a targeted attack"
+- Dashboard threat score widget with historical trend
+
+steps:
+1. Analyze existing correlation service (`services/correlation/`):
+   - Review current schema and logic in `correlation.service.ts`
+   - Identify data sources available from each service
+2. Define correlation rules:
+   - Rule 1: Same email found in HIBP breach AND receiving spam calls → coordinated attack (+30 threat score)
+   - Rule 2: Property lien filed AND data broker listing active → identity theft in progress (+40 threat score)
+   - Rule 3: Voice clone detected AND family member SSN on dark web → targeted family scam (+50 threat score)
+   - Rule 4: Multiple breaches in 30 days → compromised identity (+20 threat score)
+   - Rule 5: Spam call from number associated with known scam campaign → high risk (+25 threat score)
+3. Implement correlation detection pipeline:
+   - Subscribe to alert creation events from all 5 services
+   - Window function: look back 30 days for related findings
+   - Match on shared entities (email, phone, SSN, address, name)
+4. Implement threat scoring algorithm:
+   - Base score: sum of individual alert severities (info=1, warning=3, critical=5)
+   - Correlation bonus: +10–50 per matched rule
+   - Time decay: scores decrease by 10% per week (old alerts matter less)
+   - Family aggregation: highest individual score + average of others / 2
+   - Cap at 100, floor at 0
+5. Implement unified alert feed:
+   - Merge individual service alerts into chronological feed
+   - Group correlated alerts into "attack narratives"
+   - Show narrative summary: "3 related events detected — possible coordinated attack"
+6. Update dashboard widgets:
+   - Threat Score widget: current score with color coding (green <30, yellow 30–60, red >60)
+   - Trend graph: score over last 90 days
+   - Alert Feed widget: unified feed with narrative grouping
+7. Add proactive recommendations:
+   - If score > 60: recommend password changes, credit freeze, family notification
+   - If HomeTitle + RemoveBrokers correlated: recommend title insurance review
+   - If VoicePrint detected: recommend warning family members, filing FTC report
+
+tests:
+- Unit: Mock alerts from multiple services, verify correlation rules fire correctly
+- Integration: Create correlated alerts in database, verify threat score calculation
+- E2E: Trigger breach alert + spam alert for same email → verify unified narrative created
+
+acceptance_criteria:
+- [ ] Correlation rules detect cross-service relationships within 30-day window
+- [ ] Threat score is calculated from individual alert severities + correlation bonuses
+- [ ] Score decays by 10% per week (time-weighted relevance)
+- [ ] Family plan aggregates scores across members
+- [ ] Unified alert feed groups correlated events into narrative summaries
+- [ ] Dashboard threat score widget updates in real-time as new alerts arrive
+- [ ] Proactive recommendations appear based on current threat score and active correlations
+- [ ] Correlation engine doesn't create false positives (test with 100 random alerts, <5% false correlation rate)
+- [ ] Historical trend graph shows score changes over 90 days
+- [ ] Each correlated narrative links to individual alert details
+
+validation:
+- Run `vitest run correlation.test.ts` — all tests pass
+- Manual: Create test alerts (breached email + spam call), verify correlation detected
+- Dashboard: Threat score updates from 15 to 55 after correlation bonus applied
+- Trend: 90-day graph shows spike during test period
+
+notes:
+- The existing `correlation.service.ts` and `correlation.ts` router need activation — not just stubs
+- Correlation is the key differentiator from point-solution competitors (Aura, LifeLock)
+- False positive rate must be low — users will ignore alerts if too many are irrelevant
+- Consider using graph database (Neo4j) for complex relationship queries at scale
+- The existing `normalizedAlerts` table already stores cross-service alerts — use this as correlation source
+- Mobile apps should show simplified threat score and latest narrative, not full correlation graph