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

```typescript
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

```typescript
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

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

### Alerting Configuration

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

### Data Retention

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

## API Usage

### Get Security Metrics

```javascript
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

```javascript
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

```javascript
// 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

```javascript
const analysis = await fetch("/api/admin/security-monitoring/threat-analysis", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    ipAddress: "192.168.1.100",
    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()`:

```typescript
// 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:

```typescript
// 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:

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

Check alert generation:

```typescript
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:

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