livedash-node/docs/security-monitoring.md

Security Monitoring and Alerting System

Overview

The Security Monitoring and Alerting System provides comprehensive real-time security monitoring, anomaly detection, and threat alerting for the LiveDash-Node application. It integrates with the existing audit logging system to provide proactive security monitoring and incident response capabilities.

Architecture

Core Components

1. Security Monitoring Service (lib/securityMonitoring.ts)

• Real-time event processing
• Anomaly detection algorithms
• Alert generation and management
• Security score calculation
• Threat level assessment

2. Enhanced Security Logging (enhancedSecurityLog)

• Integrates with existing audit logger
• Processes events through monitoring system
• Triggers immediate threat detection

3. API Endpoints (app/api/admin/security-monitoring/)

• /api/admin/security-monitoring - Main metrics and configuration
• /api/admin/security-monitoring/alerts - Alert management
• /api/admin/security-monitoring/export - Data export
• /api/admin/security-monitoring/threat-analysis - Threat analysis

4. Dashboard UI (app/platform/security/page.tsx)

• Real-time security metrics
• Active alerts management
• Threat analysis visualization
• Configuration management

Features

Real-time Monitoring

• Authentication Events: Login attempts, failures, brute force attacks
• Rate Limiting: Excessive request patterns, API abuse
• Admin Activity: Unusual administrative actions
• Geographic Anomalies: Logins from unusual locations
• Temporal Anomalies: Activity spikes outside normal patterns

Alert Types

enum AlertType {
  AUTHENTICATION_ANOMALY = "AUTHENTICATION_ANOMALY",
  RATE_LIMIT_BREACH = "RATE_LIMIT_BREACH",
  MULTIPLE_FAILED_LOGINS = "MULTIPLE_FAILED_LOGINS",
  SUSPICIOUS_IP_ACTIVITY = "SUSPICIOUS_IP_ACTIVITY",
  PRIVILEGE_ESCALATION = "PRIVILEGE_ESCALATION",
  DATA_BREACH_ATTEMPT = "DATA_BREACH_ATTEMPT",
  CSRF_ATTACK = "CSRF_ATTACK",
  CSP_VIOLATION_SPIKE = "CSP_VIOLATION_SPIKE",
  ACCOUNT_ENUMERATION = "ACCOUNT_ENUMERATION",
  BRUTE_FORCE_ATTACK = "BRUTE_FORCE_ATTACK",
  UNUSUAL_ADMIN_ACTIVITY = "UNUSUAL_ADMIN_ACTIVITY",
  GEOLOCATION_ANOMALY = "GEOLOCATION_ANOMALY",
  MASS_DATA_ACCESS = "MASS_DATA_ACCESS",
  SUSPICIOUS_USER_AGENT = "SUSPICIOUS_USER_AGENT",
  SESSION_HIJACKING = "SESSION_HIJACKING",
}

Anomaly Detection

The system implements several anomaly detection algorithms:

1. Geographic Anomaly Detection

• Detects logins from unusual countries
• Compares against historical user patterns
• Confidence scoring based on deviation

2. Temporal Anomaly Detection

• Identifies activity spikes during unusual hours
• Compares current activity to historical averages
• Configurable thresholds for different event types

3. Behavioral Anomaly Detection

• Multiple failed login attempts
• Rapid succession of actions
• Pattern deviation analysis

Security Scoring

The system calculates a real-time security score (0-100) based on:

• Critical security events (weight: 25)
• Active unresolved alerts (weight: 30)
• High-severity threats (weight: 20)
• Overall event volume (weight: 15)
• System stability factors (weight: 10)

Threat Levels

enum ThreatLevel {
  LOW = "LOW", // Score: 85-100
  MODERATE = "MODERATE", // Score: 70-84
  HIGH = "HIGH", // Score: 50-69
  CRITICAL = "CRITICAL", // Score: 0-49
}

Configuration

Default Thresholds

const defaultThresholds = {
  failedLoginsPerMinute: 5,
  failedLoginsPerHour: 20,
  rateLimitViolationsPerMinute: 10,
  cspViolationsPerMinute: 15,
  adminActionsPerHour: 25,
  massDataAccessThreshold: 100,
  suspiciousIPThreshold: 10,
};

Alerting Configuration

const alertingConfig = {
  enabled: true,
  channels: ["EMAIL", "WEBHOOK", "SLACK", "DISCORD", "PAGERDUTY"],
  suppressDuplicateMinutes: 10,
  escalationTimeoutMinutes: 60,
};

Data Retention

const retentionConfig = {
  alertRetentionDays: 90,
  metricsRetentionDays: 365,
};

API Usage

Get Security Metrics

const response = await fetch(
  "/api/admin/security-monitoring?startDate=2024-01-01T00:00:00Z&endDate=2024-01-02T00:00:00Z"
);
const data = await response.json();

console.log(data.metrics.securityScore); // 0-100
console.log(data.metrics.threatLevel); // LOW, MODERATE, HIGH, CRITICAL
console.log(data.alerts); // Active alerts array

Acknowledge Alert

await fetch("/api/admin/security-monitoring/alerts", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    alertId: "alert-123",
    action: "acknowledge",
  }),
});

Export Security Data

// Export alerts as CSV
const response = await fetch(
  "/api/admin/security-monitoring/export?format=csv&type=alerts&startDate=2024-01-01T00:00:00Z&endDate=2024-01-02T00:00:00Z"
);
const csvData = await response.text();

// Export metrics as JSON
const response = await fetch(
  "/api/admin/security-monitoring/export?format=json&type=metrics&startDate=2024-01-01T00:00:00Z&endDate=2024-01-02T00:00:00Z"
);
const jsonData = await response.json();

Perform Threat Analysis

const analysis = await fetch("/api/admin/security-monitoring/threat-analysis", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    ipAddress: "192.168.1.***",
    timeRange: {
      start: "2024-01-01T00:00:00Z",
      end: "2024-01-02T00:00:00Z",
    },
  }),
});

const data = await analysis.json();
console.log(data.ipThreatAnalysis.threatLevel);
console.log(data.ipThreatAnalysis.riskFactors);
console.log(data.ipThreatAnalysis.recommendations);

Integration with Existing Systems

Enhanced Security Logging

Replace existing securityAuditLogger.log() calls with enhancedSecurityLog():

// Before
await securityAuditLogger.logAuthentication(
  "login_attempt",
  AuditOutcome.FAILURE,
  context,
  "Invalid password"
);

// After
await enhancedSecurityLog(
  SecurityEventType.AUTHENTICATION,
  "login_attempt",
  AuditOutcome.FAILURE,
  context,
  AuditSeverity.HIGH,
  "Invalid password",
  {
    attemptType: "invalid_password",
    endpoint: "/api/auth/signin",
  }
);

Rate Limiting Integration

The system automatically integrates with existing rate limiting middleware:

// middleware/authRateLimit.ts
await enhancedSecurityLog(
  SecurityEventType.RATE_LIMITING,
  "auth_rate_limit_exceeded",
  AuditOutcome.RATE_LIMITED,
  context,
  AuditSeverity.HIGH,
  "Authentication rate limit exceeded"
);

Dashboard Features

Security Overview

• Real-time security score (0-100)
• Current threat level indicator
• Active alerts count
• Security events summary

Alert Management

• View active and historical alerts
• Filter by severity and type
• Acknowledge alerts with tracking
• Detailed alert context and metadata

Threat Analysis

• Geographic distribution of events
• Top threat types and patterns
• User risk scoring
• IP threat level analysis

Configuration Management

• Adjust detection thresholds
• Configure alerting channels
• Set data retention policies
• Export capabilities

Performance Considerations

Memory Management

• Event buffer limited to 1 hour of data
• Automatic cleanup of old alerts (configurable)
• Efficient in-memory storage for real-time analysis

Database Impact

• Leverages existing audit log indexes
• Optimized queries for time-range filtering
• Background processing to avoid blocking operations

Scalability

• Stateless architecture (except for buffering)
• Horizontal scaling support
• Configurable processing intervals

Security Considerations

Access Control

• Platform admin authentication required
• Role-based access to security endpoints
• Audit logging of all monitoring activities

Data Privacy

• Sensitive data redaction in logs
• IP address anonymization options
• Configurable data retention periods

Alert Suppression

• Duplicate alert suppression (configurable window)
• Rate limiting on alert generation
• Escalation policies for critical threats

Monitoring and Maintenance

Health Checks

• Monitor service availability
• Check alert generation pipeline
• Verify data export functionality

Regular Tasks

• Review and adjust thresholds quarterly
• Analyze false positive rates
• Update threat detection patterns
• Clean up old alert data

Performance Metrics

• Alert response time
• False positive/negative rates
• System resource usage
• User engagement with alerts

Future Enhancements

Planned Features

1. Machine Learning Integration

• Behavioral pattern recognition
• Adaptive threshold adjustment
• Predictive threat modeling

2. Advanced Analytics

• Threat intelligence integration
• Cross-correlation analysis
• Risk trend analysis

3. Integration Enhancements

• SIEM system connectors
• Webhook customization
• Mobile app notifications

4. Automated Response

• IP blocking automation
• Account suspension workflows
• Incident response orchestration

Troubleshooting

Common Issues

High False Positive Rate

• Review and adjust detection thresholds
• Analyze user behavior patterns
• Consider geographical variations

Missing Alerts

• Check service configuration
• Verify audit log integration
• Review threshold settings

Performance Issues

• Monitor memory usage
• Adjust cleanup intervals
• Optimize database queries

Export Failures

• Check file permissions
• Verify date range validity
• Monitor server resources

Debugging

Enable debug logging:

securityMonitoring.updateConfig({
  alerting: {
    enabled: true,
    debugMode: true,
  },
});

Check alert generation:

const alerts = securityMonitoring.getActiveAlerts();
console.log("Active alerts:", alerts.length);

Testing

Unit Tests

• Alert generation logic
• Anomaly detection algorithms
• Configuration management
• Data export functionality

Integration Tests

• API endpoint security
• Database integration
• Real-time event processing
• Alert acknowledgment flow

Load Testing

• High-volume event processing
• Concurrent alert generation
• Database performance under load
• Memory usage patterns

Run tests:

pnpm test tests/unit/security-monitoring.test.ts
pnpm test tests/integration/security-monitoring-api.test.ts