livedash-node/docs/csp-metrics-api.md

CSP Metrics and Monitoring API

This document describes the Content Security Policy (CSP) metrics and violation reporting APIs that provide real-time monitoring and analysis of CSP violations.

Overview

The CSP Metrics API provides comprehensive monitoring of Content Security Policy violations, including:

• Real-time violation tracking and metrics
• Bypass attempt detection and risk assessment
• Policy optimization recommendations
• Historical trend analysis
• Export capabilities for security analysis

API Endpoints

CSP Violation Reporting

Endpoint for browsers to report CSP violations (automatic).

POST /api/csp-report

Request Headers

• Content-Type: application/csp-report or application/json

Request Body (Automatic from Browser)

{
  "csp-report": {
    "document-uri": "https://example.com/page",
    "violated-directive": "script-src 'self'",
    "blocked-uri": "https://malicious.com/script.js",
    "source-file": "https://example.com/page",
    "line-number": 42,
    "script-sample": "eval(maliciousCode)"
  }
}

Features

• Rate Limiting: 10 reports per minute per IP
• Risk Assessment: Automatic classification of violation severity
• Bypass Detection: Identifies potential CSP bypass attempts
• Real-time Processing: Immediate analysis and alerting

CSP Metrics API

Retrieve CSP violation metrics and analytics.

GET /api/csp-metrics

Query Parameters

Parameter	Type	Description	Default	Example
timeRange	string	Time range for metrics	24h	?timeRange=7d
format	string	Response format	json	?format=csv
groupBy	string	Group results by field	hour	?groupBy=directive
includeDetails	boolean	Include violation details	false	?includeDetails=true

Time Range Options

• 1h - Last 1 hour
• 6h - Last 6 hours
• 24h - Last 24 hours (default)
• 7d - Last 7 days
• 30d - Last 30 days

Example Request

const response = await fetch('/api/csp-metrics?' + new URLSearchParams({
  timeRange: '24h',
  groupBy: 'directive',
  includeDetails: 'true'
}));

const metrics = await response.json();

Response Format

{
  "success": true,
  "data": {
    "summary": {
      "totalViolations": 45,
      "uniqueViolations": 12,
      "highRiskViolations": 3,
      "bypassAttempts": 1,
      "timeRange": "24h",
      "generatedAt": "2024-01-01T12:00:00Z"
    },
    "trends": {
      "hourlyCount": [
        { "hour": "2024-01-01T11:00:00Z", "count": 5 },
        { "hour": "2024-01-01T12:00:00Z", "count": 8 }
      ],
      "trendDirection": "increasing",
      "changePercent": 25.5
    },
    "topViolations": [
      {
        "directive": "script-src",
        "count": 15,
        "percentage": 33.3,
        "riskLevel": "medium",
        "topBlockedUris": [
          "https://malicious.com/script.js",
          "inline"
        ]
      }
    ],
    "riskAnalysis": {
      "overallRiskScore": 65,
      "riskLevel": "medium",
      "criticalIssues": 1,
      "recommendations": [
        "Review script-src policy for external domains",
        "Consider implementing nonce-based CSP"
      ]
    },
    "violations": [
      {
        "timestamp": "2024-01-01T12:00:00Z",
        "directive": "script-src",
        "blockedUri": "https://malicious.com/script.js",
        "sourceFile": "https://example.com/page",
        "riskLevel": "high",
        "bypassAttempt": true,
        "ipAddress": "192.168.1.100",
        "userAgent": "Mozilla/5.0..."
      }
    ]
  }
}

CSP Monitoring Service

The monitoring service (lib/csp-monitoring.ts) provides advanced violation analysis.

Key Features

1. Real-time Violation Processing

// Automatic processing when violations are reported
const result = await cspMonitoring.processViolation(
  violationReport,
  clientIP,
  userAgent
);

console.log(result.alertLevel);       // low, medium, high, critical
console.log(result.shouldAlert);     // boolean
console.log(result.recommendations); // array of suggestions

2. Risk Assessment

The service automatically assesses violation risk based on:

• Directive Type: Script violations are higher risk than style violations
• Source Pattern: External domains vs inline vs data URIs
• Bypass Indicators: Known CSP bypass techniques
• Frequency: Repeated violations from same source
• Geographic Factors: Unusual source locations

3. Bypass Detection

Automatic detection of common CSP bypass attempts:

const bypassPatterns = [
  /javascript:/i,           // javascript: protocol injection
  /data:text\/html/i,       // HTML data URI injection  
  /eval\(/i,                // Direct eval() calls
  /Function\(/i,            // Function constructor
  /setTimeout.*string/i,    // Timer string execution
  /location\s*=/i,          // Location manipulation
  /document\.write/i,       // Document.write injection
];

4. Policy Recommendations

Based on violation patterns, the service provides actionable recommendations:

• Tighten Policies: Suggest removing broad allowlists
• Add Domains: Recommend allowing legitimate external resources
• Implement Nonces: Suggest nonce-based policies for inline content
• Upgrade Directives: Recommend modern CSP features

Violation Analysis

Risk Levels

Risk Level	Score	Description	Action
Critical	90-100	Active bypass attempts, known attack patterns	Immediate investigation
High	70-89	Suspicious patterns, potential security risks	Urgent review
Medium	40-69	Policy violations, may need attention	Regular monitoring
Low	0-39	Minor violations, likely legitimate	Log for trends

Alert Conditions

// High-risk violations trigger immediate alerts
const alertConditions = {
  critical: {
    bypassAttempt: true,
    unknownExternalDomain: true,
    suspiciousUserAgent: true
  },
  high: {
    repeatedViolations: '>5 in 10 minutes',
    scriptInjectionAttempt: true,
    dataUriWithScript: true
  },
  medium: {
    newExternalDomain: true,
    inlineScriptViolation: true,
    unknownSource: true
  }
};

Usage Examples

Real-time Violation Monitoring

// Monitor violations in real-time
async function monitorViolations() {
  const metrics = await fetch('/api/csp-metrics?timeRange=1h');
  const data = await metrics.json();
  
  if (data.data.summary.highRiskViolations > 0) {
    console.warn('High-risk CSP violations detected:', 
                 data.data.summary.highRiskViolations);
    
    // Get violation details
    const details = await fetch('/api/csp-metrics?includeDetails=true');
    const violations = await details.json();
    
    violations.data.violations
      .filter(v => v.riskLevel === 'high')
      .forEach(violation => {
        console.error('High-risk violation:', {
          directive: violation.directive,
          blockedUri: violation.blockedUri,
          timestamp: violation.timestamp
        });
      });
  }
}

// Run every 5 minutes
setInterval(monitorViolations, 5 * 60 * 1000);

Security Dashboard Integration

// Get CSP metrics for security dashboard
async function getCSPDashboardData() {
  const [current, previous] = await Promise.all([
    fetch('/api/csp-metrics?timeRange=24h').then(r => r.json()),
    fetch('/api/csp-metrics?timeRange=24h&offset=24h').then(r => r.json())
  ]);
  
  return {
    currentViolations: current.data.summary.totalViolations,
    previousViolations: previous.data.summary.totalViolations,
    trend: current.data.trends.trendDirection,
    riskScore: current.data.riskAnalysis.overallRiskScore,
    recommendations: current.data.riskAnalysis.recommendations.slice(0, 3)
  };
}

Export Violation Data

// Export violations for external analysis
async function exportViolations(format = 'csv', timeRange = '7d') {
  const response = await fetch(`/api/csp-metrics?format=${format}&timeRange=${timeRange}`);
  
  if (format === 'csv') {
    const csvData = await response.text();
    downloadFile(csvData, `csp-violations-${timeRange}.csv`, 'text/csv');
  } else {
    const jsonData = await response.json();
    downloadFile(JSON.stringify(jsonData, null, 2), 
                `csp-violations-${timeRange}.json`, 
                'application/json');
  }
}

function downloadFile(content, filename, contentType) {
  const blob = new Blob([content], { type: contentType });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = filename;
  a.click();
  URL.revokeObjectURL(url);
}

Policy Optimization

// Analyze violations to optimize CSP policy
async function optimizeCSPPolicy() {
  const metrics = await fetch('/api/csp-metrics?timeRange=30d&includeDetails=true');
  const data = await metrics.json();
  
  // Group violations by directive
  const violationsByDirective = data.data.violations.reduce((acc, violation) => {
    if (!acc[violation.directive]) {
      acc[violation.directive] = [];
    }
    acc[violation.directive].push(violation);
    return acc;
  }, {});
  
  // Generate recommendations
  const recommendations = Object.entries(violationsByDirective).map(([directive, violations]) => {
    const uniqueDomains = [...new Set(violations.map(v => v.blockedUri))];
    const legitimateCount = violations.filter(v => v.riskLevel === 'low').length;
    
    if (legitimateCount > violations.length * 0.8) {
      return {
        directive,
        action: 'allow',
        domains: uniqueDomains.slice(0, 5),
        confidence: 'high'
      };
    } else {
      return {
        directive,
        action: 'investigate',
        riskDomains: uniqueDomains.filter((_, i) => 
          violations.find(v => v.blockedUri === uniqueDomains[i])?.riskLevel === 'high'
        ),
        confidence: 'medium'
      };
    }
  });
  
  return recommendations;
}

Configuration and Setup

CSP Header Configuration

The CSP metrics system requires proper CSP headers with reporting:

// In next.config.js or middleware
const cspDirectives = {
  'default-src': "'self'",
  'script-src': "'self' 'nonce-{NONCE}'",
  'report-uri': '/api/csp-report',
  'report-to': 'csp-endpoint'
};

Report-To Header

For modern browsers, configure the Report-To header:

const reportToHeader = JSON.stringify({
  group: 'csp-endpoint',
  max_age: 86400,
  endpoints: [{ url: '/api/csp-report' }]
});

// Add to response headers
headers['Report-To'] = reportToHeader;

Environment Configuration

# Enable CSP monitoring in production
NODE_ENV=production

# Optional: Configure monitoring sensitivity
CSP_MONITORING_SENSITIVITY=medium  # low, medium, high
CSP_ALERT_THRESHOLD=5              # violations per 10 minutes

Performance Considerations

Rate Limiting

• 10 reports per minute per IP prevents spam attacks
• Exponential backoff for repeated violations from same source
• Memory cleanup removes old violations automatically

Memory Management

• Violation buffer limited to 1 hour of data in memory
• Automatic cleanup runs every 100 requests (1% probability)
• Efficient storage using Map data structures

Database Impact

• No persistent storage for real-time metrics (memory only)
• Optional logging to database for long-term analysis
• Indexed queries for historical data retrieval

Security Considerations

Privacy Protection

• IP anonymization option for GDPR compliance
• User agent sanitization removes sensitive information
• No personal data stored in violation reports

Rate Limiting Protection

• Per-IP limits prevent DoS attacks on reporting endpoint
• Content-type validation ensures proper report format
• Request size limits prevent memory exhaustion

False Positive Handling

• Learning mode for new deployments
• Whitelist support for known legitimate violations
• Risk score adjustment based on historical patterns

Troubleshooting

Common Issues

High False Positive Rate

// Check for legitimate violations being flagged
const metrics = await fetch('/api/csp-metrics?includeDetails=true');
const data = await metrics.json();

const falsePositives = data.data.violations.filter(v => 
  v.riskLevel === 'high' && 
  v.blockedUri.includes('legitimate-domain.com')
);

if (falsePositives.length > 0) {
  console.log('Consider whitelisting:', falsePositives[0].blockedUri);
}

Missing Violation Reports

// Check if CSP headers are properly configured
fetch('/').then(response => {
  const csp = response.headers.get('Content-Security-Policy');
  if (!csp.includes('report-uri')) {
    console.error('CSP report-uri directive missing');
  }
});

Performance Issues

// Monitor API response times
const start = performance.now();
const response = await fetch('/api/csp-metrics');
const duration = performance.now() - start;

if (duration > 2000) {
  console.warn('CSP metrics API slow response:', duration + 'ms');
}

Related Documentation

• Enhanced CSP Implementation
• Security Monitoring
• Security Headers
• Rate Limiting

API Reference Summary

Endpoint	Method	Purpose	Auth Required
/api/csp-report	POST	Receive CSP violation reports	No (public)
/api/csp-metrics	GET	Get violation metrics and analytics	Admin

Both APIs are production-ready and provide comprehensive CSP monitoring capabilities for enterprise security requirements.