# 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