@etcsec-com/etc-collector 1.4.0

package/src/services/audit/scoring.service.ts

@@ -0,0 +1,234 @@
+/**
+ * Security Scoring Service
+ *
+ * Calculates security scores based on vulnerability findings
+ * Story 1.7: AD Vulnerability Detection Engine
+ *
+ * Scoring Methodology (v1.1.1):
+ * - Weighted Findings = (Critical × 10) + (High × 3) + (Medium × 1) + (Low × 0.2)
+ * - Logarithmic scale to avoid extreme scores with high finding counts
+ * - Security Score = max(0, min(100, 100 - log10(ratio + 1) * 50))
+ *
+ * Interpretation:
+ * - 90-100: Excellent - Minimal vulnerabilities, strong security posture
+ * - 70-89: Good - Some issues to address, generally secure
+ * - 50-69: Fair - Multiple vulnerabilities requiring attention
+ * - 30-49: Poor - Significant security gaps, urgent remediation needed
+ * - 0-29: Critical - Severe security risk, immediate action required
+ */
+
+import { Finding, FindingCounts, CategoryCounts, Severity } from '../../types/finding.types';
+
+/**
+ * Security score result
+ */
+export interface SecurityScore {
+  score: number;
+  rating: 'excellent' | 'good' | 'fair' | 'poor' | 'critical';
+  weightedPoints: number;
+  totalUsers: number;
+  findings: FindingCounts;
+  categories: CategoryCounts;
+}
+
+/**
+ * Severity weights for scoring (v1.1.0 - aligned with SaaS)
+ */
+const SEVERITY_WEIGHTS: Record<Severity, number> = {
+  critical: 10,
+  high: 3,
+  medium: 1,
+  low: 0.2,
+};
+
+/**
+ * Calculate security score from findings
+ *
+ * @param findings Array of vulnerability findings
+ * @param totalUsers Total number of users in the directory (for normalization)
+ * @returns Security score object with rating and details
+ */
+export function calculateSecurityScore(findings: Finding[], totalUsers: number): SecurityScore {
+  // Count findings by severity
+  const counts: FindingCounts = {
+    critical: 0,
+    high: 0,
+    medium: 0,
+    low: 0,
+    total: 0,
+  };
+
+  // Count findings by category
+  const categories: CategoryCounts = {
+    passwords: 0,
+    kerberos: 0,
+    accounts: 0,
+    groups: 0,
+    computers: 0,
+    advanced: 0,
+    permissions: 0,
+    config: 0,
+    adcs: 0,
+    gpo: 0,
+    trusts: 0,
+    'attack-paths': 0,
+    monitoring: 0,
+    compliance: 0,
+    network: 0,
+    identity: 0,
+    applications: 0,
+    conditionalAccess: 0,
+    privilegedAccess: 0,
+  };
+
+  // Aggregate findings
+  findings.forEach((finding) => {
+    counts[finding.severity] += finding.count;
+    counts.total += finding.count;
+    categories[finding.category] += finding.count;
+  });
+
+  // Calculate weighted findings (v1.1.0 formula - aligned with SaaS)
+  const weightedFindings =
+    counts.critical * SEVERITY_WEIGHTS.critical +
+    counts.high * SEVERITY_WEIGHTS.high +
+    counts.medium * SEVERITY_WEIGHTS.medium +
+    counts.low * SEVERITY_WEIGHTS.low;
+
+  // Calculate security score (0-100) using logarithmic scale
+  // This prevents extreme scores (always 0) with high finding counts
+  // Multiplier 50 ensures vulnerable environments get appropriately low scores
+  const totalEntities = Math.max(totalUsers, 1);
+  const ratio = weightedFindings / totalEntities;
+  const normalizedRatio = Math.log10(ratio + 1) * 50;
+  const score = Math.max(0, Math.min(100, 100 - normalizedRatio));
+
+  // Determine rating
+  const rating = getSecurityRating(score);
+
+  return {
+    score: Math.round(score * 10) / 10, // Round to 1 decimal place
+    rating,
+    weightedPoints: weightedFindings,
+    totalUsers,
+    findings: counts,
+    categories,
+  };
+}
+
+/**
+ * Get security rating from score
+ *
+ * @param score Security score (0-100)
+ * @returns Rating category
+ */
+function getSecurityRating(score: number): 'excellent' | 'good' | 'fair' | 'poor' | 'critical' {
+  if (score >= 90) return 'excellent';
+  if (score >= 70) return 'good';
+  if (score >= 50) return 'fair';
+  if (score >= 30) return 'poor';
+  return 'critical';
+}
+
+/**
+ * Get human-readable description for rating
+ *
+ * @param rating Security rating
+ * @returns Description string
+ */
+export function getRatingDescription(rating: string): string {
+  const descriptions: Record<string, string> = {
+    excellent: 'Excellent - Minimal vulnerabilities, strong security posture',
+    good: 'Good - Some issues to address, generally secure',
+    fair: 'Fair - Multiple vulnerabilities requiring attention',
+    poor: 'Poor - Significant security gaps, urgent remediation needed',
+    critical: 'Critical - Severe security risk, immediate action required',
+  };
+
+  return descriptions[rating] || 'Unknown rating';
+}
+
+/**
+ * Calculate category-specific scores
+ *
+ * @param findings Array of vulnerability findings
+ * @returns Map of category to score (0-100)
+ */
+export function calculateCategoryScores(findings: Finding[]): Record<string, number> {
+  const categoryScores: Record<string, number> = {
+    passwords: 100,
+    kerberos: 100,
+    accounts: 100,
+    groups: 100,
+    computers: 100,
+    advanced: 100,
+    permissions: 100,
+    config: 100,
+  };
+
+  // Group findings by category
+  const categoryFindings = findings.reduce((acc, finding) => {
+    if (!acc[finding.category]) {
+      acc[finding.category] = [];
+    }
+    acc[finding.category]!.push(finding);
+    return acc;
+  }, {} as Record<string, Finding[]>);
+
+  // Calculate score for each category
+  Object.keys(categoryFindings).forEach((category) => {
+    const categoryFindingsList = categoryFindings[category];
+    if (!categoryFindingsList) return;
+
+    const weightedPoints = categoryFindingsList.reduce((sum, finding) => {
+      return sum + finding.count * SEVERITY_WEIGHTS[finding.severity];
+    }, 0);
+
+    // Simple deduction: -1 point per weighted point (capped at 0)
+    categoryScores[category] = Math.max(0, 100 - weightedPoints);
+  });
+
+  return categoryScores;
+}
+
+/**
+ * Get top N most critical findings
+ *
+ * @param findings Array of vulnerability findings
+ * @param limit Number of findings to return
+ * @returns Top N findings sorted by severity and count
+ */
+export function getTopFindings(findings: Finding[], limit: number = 10): Finding[] {
+  // Sort by severity weight * count (descending)
+  const sorted = [...findings].sort((a, b) => {
+    const weightA = SEVERITY_WEIGHTS[a.severity] * a.count;
+    const weightB = SEVERITY_WEIGHTS[b.severity] * b.count;
+    return weightB - weightA;
+  });
+
+  return sorted.slice(0, limit);
+}
+
+/**
+ * Generate security summary
+ *
+ * @param score Security score object
+ * @returns Human-readable summary string
+ */
+export function generateSecuritySummary(score: SecurityScore): string {
+  const { score: scoreValue, rating, findings } = score;
+
+  const lines = [
+    `Security Score: ${scoreValue}/100 (${rating.toUpperCase()})`,
+    getRatingDescription(rating),
+    '',
+    'Vulnerability Summary:',
+    `- Critical: ${findings.critical}`,
+    `- High: ${findings.high}`,
+    `- Medium: ${findings.medium}`,
+    `- Low: ${findings.low}`,
+    `- Total: ${findings.total}`,
+  ];
+
+  return lines.join('\n');
+}

package/src/services/auth/crypto.service.ts

@@ -0,0 +1,230 @@
+import crypto from 'crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'fs';
+import { dirname } from 'path';
+import type { Logger } from 'winston';
+import { logger } from '../../utils/logger';
+
+/**
+ * CryptoService
+ *
+ * Manages RSA key pairs for RS256 JWT signatures.
+ *
+ * Features:
+ * - Generates 2048-bit RSA key pairs
+ * - Persists keys to filesystem (PKCS#8 private, SPKI public)
+ * - Loads existing keys or auto-generates on first use
+ * - Sets secure file permissions (600 for private, 644 for public)
+ *
+ * Task 1: RS256 Key Management (Story 1.4)
+ *
+ * Integration Verifications:
+ * - IV1: Auto-generates key pair on first startup
+ * - IV2: Loads existing keys from filesystem
+ * - IV3: Private key has 600 permissions
+ * - IV4: Public key has 644 permissions
+ * - IV5: Keys persist across server restarts
+ */
+
+export interface KeyPair {
+  privateKey: string;
+  publicKey: string;
+}
+
+export class CryptoService {
+  private privateKey: string | null = null;
+  private publicKey: string | null = null;
+  private logger: Logger;
+
+  constructor(
+    private privateKeyPath: string,
+    private publicKeyPath: string
+  ) {
+    this.logger = logger;
+  }
+
+  /**
+   * Generate a new RSA key pair
+   *
+   * Specification:
+   * - Algorithm: RSA
+   * - Key size: 2048 bits
+   * - Private key format: PKCS#8 PEM
+   * - Public key format: SPKI PEM
+   *
+   * @returns KeyPair with private and public keys in PEM format
+   */
+  generateKeyPair(): KeyPair {
+    this.logger.info('Generating new RSA key pair (2048-bit)');
+
+    const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', {
+      modulusLength: 2048,
+      publicKeyEncoding: {
+        type: 'spki',
+        format: 'pem',
+      },
+      privateKeyEncoding: {
+        type: 'pkcs8',
+        format: 'pem',
+      },
+    });
+
+    this.logger.info('RSA key pair generated successfully');
+    return { privateKey, publicKey };
+  }
+
+  /**
+   * Load existing keys from filesystem or generate new ones
+   *
+   * Flow:
+   * 1. Check if both key files exist
+   * 2. If yes: load from files and cache in memory
+   * 3. If no: generate new key pair, save to files, cache in memory
+   *
+   * File permissions:
+   * - Private key: 600 (owner read/write only)
+   * - Public key: 644 (owner read/write, others read)
+   *
+   * @throws Error if key loading or generation fails
+   */
+  async loadOrGenerateKeys(): Promise<void> {
+    const privateKeyExists = existsSync(this.privateKeyPath);
+    const publicKeyExists = existsSync(this.publicKeyPath);
+
+    if (privateKeyExists && publicKeyExists) {
+      // Load existing keys
+      this.logger.info('Loading existing RSA keys from filesystem', {
+        privateKeyPath: this.privateKeyPath,
+        publicKeyPath: this.publicKeyPath,
+      });
+
+      try {
+        this.privateKey = readFileSync(this.privateKeyPath, 'utf-8');
+        this.publicKey = readFileSync(this.publicKeyPath, 'utf-8');
+
+        // Validate that keys are in correct PEM format
+        this.validateKeyFormat(this.privateKey, 'PRIVATE KEY');
+        this.validateKeyFormat(this.publicKey, 'PUBLIC KEY');
+
+        this.logger.info('RSA keys loaded successfully from filesystem');
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        this.logger.error('Failed to load RSA keys from filesystem', { error: message });
+        throw new Error(`Failed to load RSA keys: ${message}`);
+      }
+    } else {
+      // Generate and save new keys
+      if (privateKeyExists !== publicKeyExists) {
+        this.logger.warn('Only one key file exists, regenerating both', {
+          privateKeyExists,
+          publicKeyExists,
+        });
+      } else {
+        this.logger.info('No existing keys found, generating new RSA key pair');
+      }
+
+      try {
+        const keyPair = this.generateKeyPair();
+        this.privateKey = keyPair.privateKey;
+        this.publicKey = keyPair.publicKey;
+
+        this.saveKeys(keyPair);
+        this.logger.info('RSA keys generated and saved successfully');
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        this.logger.error('Failed to generate and save RSA keys', { error: message });
+        throw new Error(`Failed to generate RSA keys: ${message}`);
+      }
+    }
+  }
+
+  /**
+   * Get the cached private key
+   *
+   * @returns Private key in PEM format
+   * @throws Error if keys haven't been loaded yet
+   */
+  getPrivateKey(): string {
+    if (!this.privateKey) {
+      throw new Error('Keys not loaded. Call loadOrGenerateKeys() first.');
+    }
+    return this.privateKey;
+  }
+
+  /**
+   * Get the cached public key
+   *
+   * @returns Public key in PEM format
+   * @throws Error if keys haven't been loaded yet
+   */
+  getPublicKey(): string {
+    if (!this.publicKey) {
+      throw new Error('Keys not loaded. Call loadOrGenerateKeys() first.');
+    }
+    return this.publicKey;
+  }
+
+  /**
+   * Save key pair to filesystem with secure permissions
+   *
+   * Security:
+   * - Creates parent directories if needed
+   * - Sets private key to 600 (owner read/write only)
+   * - Sets public key to 644 (owner read/write, others read)
+   *
+   * @param keyPair The key pair to save
+   * @throws Error if file operations fail
+   */
+  private saveKeys(keyPair: KeyPair): void {
+    try {
+      // Ensure parent directories exist
+      const privateKeyDir = dirname(this.privateKeyPath);
+      const publicKeyDir = dirname(this.publicKeyPath);
+
+      if (!existsSync(privateKeyDir)) {
+        mkdirSync(privateKeyDir, { recursive: true });
+        this.logger.debug('Created directory for private key', { path: privateKeyDir });
+      }
+
+      if (!existsSync(publicKeyDir)) {
+        mkdirSync(publicKeyDir, { recursive: true });
+        this.logger.debug('Created directory for public key', { path: publicKeyDir });
+      }
+
+      // Write private key with restrictive permissions
+      writeFileSync(this.privateKeyPath, keyPair.privateKey, { mode: 0o600 });
+      chmodSync(this.privateKeyPath, 0o600);
+      this.logger.debug('Private key saved', {
+        path: this.privateKeyPath,
+        permissions: '600',
+      });
+
+      // Write public key with standard permissions
+      writeFileSync(this.publicKeyPath, keyPair.publicKey, { mode: 0o644 });
+      chmodSync(this.publicKeyPath, 0o644);
+      this.logger.debug('Public key saved', {
+        path: this.publicKeyPath,
+        permissions: '644',
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      this.logger.error('Failed to save keys to filesystem', { error: message });
+      throw new Error(`Failed to save keys: ${message}`);
+    }
+  }
+
+  /**
+   * Validate that a key string is in correct PEM format
+   *
+   * @param key The key string to validate
+   * @param keyType Expected key type ('PRIVATE KEY' or 'PUBLIC KEY')
+   * @throws Error if key format is invalid
+   */
+  private validateKeyFormat(key: string, keyType: string): void {
+    const beginMarker = `-----BEGIN ${keyType}-----`;
+    const endMarker = `-----END ${keyType}-----`;
+
+    if (!key.includes(beginMarker) || !key.includes(endMarker)) {
+      throw new Error(`Invalid ${keyType} format: missing PEM markers`);
+    }
+  }
+}

package/src/services/auth/errors.ts

@@ -0,0 +1,47 @@
+/**
+ * JWT Authentication Errors
+ *
+ * Custom error classes for token validation and authentication failures.
+ */
+
+export class TokenExpiredError extends Error {
+  constructor(message = 'Token has expired') {
+    super(message);
+    this.name = 'TokenExpiredError';
+  }
+}
+
+export class TokenRevokedError extends Error {
+  constructor(message = 'Token has been revoked') {
+    super(message);
+    this.name = 'TokenRevokedError';
+  }
+}
+
+export class UsageLimitExceededError extends Error {
+  constructor(message = 'Token usage limit exceeded') {
+    super(message);
+    this.name = 'UsageLimitExceededError';
+  }
+}
+
+export class TokenNotFoundError extends Error {
+  constructor(message = 'Token not found in database') {
+    super(message);
+    this.name = 'TokenNotFoundError';
+  }
+}
+
+export class InvalidSignatureError extends Error {
+  constructor(message = 'Invalid token signature') {
+    super(message);
+    this.name = 'InvalidSignatureError';
+  }
+}
+
+export class InvalidTokenError extends Error {
+  constructor(message = 'Invalid token') {
+    super(message);
+    this.name = 'InvalidTokenError';
+  }
+}