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

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