guardrail-compliance 1.0.0

package/src/pii/detector.ts

@@ -0,0 +1,327 @@
+import { prisma } from '@guardrail/database';
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { PII_PATTERNS, PII_FIELD_PATTERNS, PII_TEST_VALUES, NON_PII_CONTEXT_INDICATORS } from './patterns';
+import { dataFlowTracker, PIIFinding, DataFlow } from './data-flow';
+
+export interface PIIDetectionResult {
+  projectId: string;
+  summary: {
+    totalFindings: number;
+    byCategory: Record<string, number>;
+    riskLevel: 'high' | 'medium' | 'low';
+  };
+  findings: PIIFinding[];
+  dataFlows: DataFlow[];
+  recommendations: string[];
+}
+
+export class PIIDetector {
+  /**
+   * Detect PII in entire project
+   */
+  async detectPII(projectPath: string, projectId: string): Promise<PIIDetectionResult> {
+    const allFindings: PIIFinding[] = [];
+
+    // Find all source files
+    const sourceFiles = this.findSourceFiles(projectPath);
+
+    // Scan each file
+    for (const filePath of sourceFiles) {
+      try {
+        const content = readFileSync(filePath, 'utf-8');
+        const findings = this.scanContent(content, filePath);
+        allFindings.push(...findings);
+
+        // Also scan for PII field names
+        const fieldFindings = this.scanFieldNames(content, filePath);
+        allFindings.push(...fieldFindings);
+      } catch (error) {
+        console.error(`Error scanning file ${filePath}:`, error);
+      }
+    }
+
+    // Track data flows
+    const dataFlows = await this.trackPIIDataFlows(projectPath, allFindings);
+
+    // Generate recommendations
+    const recommendations = this.generateRecommendations(allFindings, dataFlows);
+
+    // Calculate summary
+    const byCategory: Record<string, number> = {};
+    for (const finding of allFindings) {
+      byCategory[finding.category] = (byCategory[finding.category] || 0) + 1;
+    }
+
+    const highSeverityCount = allFindings.filter(f => f.severity === 'high').length;
+    const riskLevel: 'high' | 'medium' | 'low' =
+      highSeverityCount > 5 ? 'high' :
+      highSeverityCount > 0 ? 'medium' : 'low';
+
+    const result: PIIDetectionResult = {
+      projectId,
+      summary: {
+        totalFindings: allFindings.length,
+        byCategory,
+        riskLevel
+      },
+      findings: allFindings,
+      dataFlows,
+      recommendations
+    };
+
+    // Save to database
+    try {
+      await prisma.pIIDetection.create({
+        data: {
+          projectId
+        } as any
+      });
+    } catch (error) {
+      // Table may not exist - continue
+    }
+
+    return result;
+  }
+
+  /**
+   * Scan file content for PII patterns
+   */
+  private scanContent(content: string, filePath: string): PIIFinding[] {
+    const findings: PIIFinding[] = [];
+    const lines = content.split('\n');
+
+    for (const pattern of PII_PATTERNS) {
+      let match;
+      while ((match = pattern.pattern.exec(content)) !== null) {
+        const value = match[0];
+
+        // Skip test values
+        if (this.isTestValue(value)) {
+          continue;
+        }
+
+        // Get line and column
+        const position = this.getLineAndColumn(content, match.index);
+
+        // Get context
+        const context = this.getContext(lines, position.line);
+
+        // Skip if in non-PII context
+        if (this.isNonPIIContext(context)) {
+          continue;
+        }
+
+        findings.push({
+          category: pattern.category,
+          value: this.maskValue(value, pattern.category),
+          location: {
+            file: filePath,
+            line: position.line + 1,
+            column: position.column
+          },
+          context,
+          severity: pattern.severity
+        });
+      }
+
+      // Reset lastIndex for global regex
+      pattern.pattern.lastIndex = 0;
+    }
+
+    return findings;
+  }
+
+  /**
+   * Scan AST for PII field names
+   */
+  private scanFieldNames(content: string, filePath: string): PIIFinding[] {
+    const findings: PIIFinding[] = [];
+    const lines = content.split('\n');
+
+    // Simple pattern matching for field names
+    // In production, would use proper AST parsing
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (!line) continue;
+
+      for (const fieldPattern of PII_FIELD_PATTERNS) {
+        const matches = line.matchAll(fieldPattern.pattern);
+
+        for (const match of matches) {
+          const fieldName = match[0];
+          const context = this.getContext(lines, i);
+
+          // Skip if in comments or strings
+          if (line.trim().startsWith('//') || line.trim().startsWith('*')) {
+            continue;
+          }
+
+          findings.push({
+            category: fieldPattern.category,
+            value: fieldName,
+            location: {
+              file: filePath,
+              line: i + 1,
+              column: match.index || 0
+            },
+            context,
+            severity: fieldPattern.severity
+          });
+        }
+      }
+    }
+
+    return findings;
+  }
+
+  /**
+   * Track data flows for PII
+   */
+  private async trackPIIDataFlows(_projectPath: string, findings: PIIFinding[]): Promise<DataFlow[]> {
+    // Use data flow tracker to analyze flows
+    return dataFlowTracker.analyzeDataFlows(findings);
+  }
+
+  /**
+   * Generate recommendations based on findings
+   */
+  private generateRecommendations(findings: PIIFinding[], dataFlows: DataFlow[]): string[] {
+    const recommendations: string[] = [];
+
+    // Count findings by category
+    const bySeverity = {
+      high: findings.filter(f => f.severity === 'high').length,
+      medium: findings.filter(f => f.severity === 'medium').length,
+      low: findings.filter(f => f.severity === 'low').length
+    };
+
+    if (bySeverity.high > 0) {
+      recommendations.push(`🔴 Found ${bySeverity.high} high-severity PII findings - immediate action required`);
+      recommendations.push('Implement encryption for sensitive data fields');
+      recommendations.push('Review and minimize PII storage');
+    }
+
+    // Check for unencrypted storage
+    const unencryptedStorage = dataFlows.some(flow =>
+      flow.storage.some(s => !s.encrypted)
+    );
+
+    if (unencryptedStorage) {
+      recommendations.push('⚠️ PII detected in unencrypted storage - enable encryption at rest');
+    }
+
+    // Check for external transfers
+    const hasExternalTransfers = dataFlows.some(flow => flow.externalTransfers.length > 0);
+
+    if (hasExternalTransfers) {
+      recommendations.push('📡 PII transferred to external systems - ensure proper data processing agreements');
+    }
+
+    // General recommendations
+    if (findings.length > 0) {
+      recommendations.push('Implement data retention policies');
+      recommendations.push('Add user consent mechanisms for PII collection');
+      recommendations.push('Consider pseudonymization or anonymization techniques');
+      recommendations.push('Implement access controls for PII data');
+      recommendations.push('Add audit logging for PII access');
+    }
+
+    return recommendations;
+  }
+
+  /**
+   * Find source files in project
+   */
+  private findSourceFiles(dir: string): string[] {
+    const files: string[] = [];
+    const extensions = ['.ts', '.js', '.tsx', '.jsx', '.py', '.java', '.go', '.rb', '.php'];
+
+    try {
+      const entries = readdirSync(dir);
+
+      for (const entry of entries) {
+        const fullPath = join(dir, entry);
+        const stat = statSync(fullPath);
+
+        if (stat.isDirectory() && !entry.startsWith('.') && entry !== 'node_modules' && entry !== 'dist') {
+          files.push(...this.findSourceFiles(fullPath));
+        } else if (stat.isFile()) {
+          if (extensions.some(ext => entry.endsWith(ext))) {
+            files.push(fullPath);
+          }
+        }
+      }
+    } catch (error) {
+      // Ignore permission errors
+    }
+
+    return files;
+  }
+
+  /**
+   * Check if value is a test value
+   */
+  private isTestValue(value: string): boolean {
+    return PII_TEST_VALUES.some(test => value.includes(test));
+  }
+
+  /**
+   * Check if context indicates non-PII usage
+   */
+  private isNonPIIContext(context: string): boolean {
+    const lowerContext = context.toLowerCase();
+    return NON_PII_CONTEXT_INDICATORS.some(indicator =>
+      lowerContext.includes(indicator)
+    );
+  }
+
+  /**
+   * Get line and column from position
+   */
+  private getLineAndColumn(content: string, position: number): { line: number; column: number } {
+    const lines = content.substring(0, position).split('\n');
+    const lastLine = lines[lines.length - 1] || '';
+    return {
+      line: lines.length - 1,
+      column: lastLine.length
+    };
+  }
+
+  /**
+   * Get context around a line
+   */
+  private getContext(lines: string[], lineIndex: number, contextSize: number = 2): string {
+    const start = Math.max(0, lineIndex - contextSize);
+    const end = Math.min(lines.length, lineIndex + contextSize + 1);
+    return lines.slice(start, end).join('\n');
+  }
+
+  /**
+   * Mask sensitive value
+   */
+  private maskValue(value: string, category: string): string {
+    if (category === 'email') {
+      const parts = value.split('@');
+      const local = parts[0];
+      const domain = parts[1];
+      if (local && domain) {
+        return `${local.charAt(0)}***@${domain}`;
+      }
+      return '***@***.com';
+    }
+
+    if (category === 'phone') {
+      return `***-***-${value.slice(-4)}`;
+    }
+
+    if (category === 'ssn' || category === 'credit-card') {
+      return `***-**-${value.slice(-4)}`;
+    }
+
+    return `${value.slice(0, 3)}***`;
+  }
+}
+
+export const piiDetector = new PIIDetector();

package/src/pii/index.ts

@@ -0,0 +1,3 @@
+export * from './detector';
+export * from './patterns';
+export * from './data-flow';

package/src/pii/patterns.ts

@@ -0,0 +1,128 @@
+export interface PIIPattern {
+  category: 'email' | 'phone' | 'ssn' | 'credit-card' | 'ip-address' | 'name-field' | 'address' | 'dob' | 'health' | 'financial';
+  description: string;
+  pattern: RegExp;
+  severity: 'high' | 'medium' | 'low';
+  examples: string[];
+}
+
+/**
+ * PII Detection Patterns
+ */
+export const PII_PATTERNS: PIIPattern[] = [
+  // Email Addresses
+  {
+    category: 'email',
+    description: 'Email address',
+    pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+    severity: 'medium',
+    examples: ['user@example.com', 'john.doe@company.co.uk']
+  },
+
+  // Phone Numbers
+  {
+    category: 'phone',
+    description: 'US Phone number',
+    pattern: /\b(\+1[-.\s]?)?(\(?\d{3}\)?[-.\s]?)?\d{3}[-.\s]?\d{4}\b/g,
+    severity: 'medium',
+    examples: ['+1-555-123-4567', '(555) 123-4567', '555-123-4567']
+  },
+
+  // Social Security Numbers
+  {
+    category: 'ssn',
+    description: 'US Social Security Number',
+    pattern: /\b\d{3}-\d{2}-\d{4}\b/g,
+    severity: 'high',
+    examples: ['123-45-6789']
+  },
+
+  // Credit Card Numbers (Luhn algorithm pattern)
+  {
+    category: 'credit-card',
+    description: 'Credit card number',
+    pattern: /\b(?:\d{4}[-\s]?){3}\d{4}\b/g,
+    severity: 'high',
+    examples: ['4532-1234-5678-9010', '5425 2334 3010 9903']
+  },
+
+  // IP Addresses
+  {
+    category: 'ip-address',
+    description: 'IPv4 address',
+    pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+    severity: 'low',
+    examples: ['192.168.1.1', '10.0.0.1']
+  }
+];
+
+/**
+ * Field name patterns that suggest PII
+ */
+export const PII_FIELD_PATTERNS = [
+  // Name fields
+  { pattern: /\b(first_?name|last_?name|full_?name|given_?name|family_?name)\b/i, category: 'name-field', severity: 'medium' as const },
+  { pattern: /\b(name)\b/i, category: 'name-field', severity: 'low' as const },
+
+  // Email fields
+  { pattern: /\b(email|e_?mail|email_?address)\b/i, category: 'email', severity: 'medium' as const },
+
+  // Phone fields
+  { pattern: /\b(phone|telephone|mobile|cell_?phone)\b/i, category: 'phone', severity: 'medium' as const },
+
+  // Address fields
+  { pattern: /\b(address|street|city|state|zip|postal_?code|country)\b/i, category: 'address', severity: 'medium' as const },
+  { pattern: /\b(billing_?address|shipping_?address|home_?address)\b/i, category: 'address', severity: 'high' as const },
+
+  // Date of Birth
+  { pattern: /\b(dob|date_?of_?birth|birth_?date|birthday)\b/i, category: 'dob', severity: 'high' as const },
+
+  // Social Security
+  { pattern: /\b(ssn|social_?security|national_?id)\b/i, category: 'ssn', severity: 'high' as const },
+
+  // Financial
+  { pattern: /\b(credit_?card|card_?number|cvv|cvc|account_?number|routing_?number|iban)\b/i, category: 'financial', severity: 'high' as const },
+  { pattern: /\b(salary|income|tax_?id|ein)\b/i, category: 'financial', severity: 'high' as const },
+
+  // Health
+  { pattern: /\b(medical_?record|patient_?id|diagnosis|prescription|health_?insurance)\b/i, category: 'health', severity: 'high' as const },
+  { pattern: /\b(blood_?type|allergies|medication)\b/i, category: 'health', severity: 'high' as const },
+
+  // Authentication
+  { pattern: /\b(password|passwd|pwd|secret|token|api_?key)\b/i, category: 'financial', severity: 'high' as const }
+];
+
+/**
+ * Test values that should be excluded
+ */
+export const PII_TEST_VALUES = [
+  'test@example.com',
+  'user@example.com',
+  'admin@example.com',
+  'noreply@example.com',
+  '555-0100', // Reserved for testing
+  '555-0199',
+  '000-00-0000', // Invalid SSN
+  '123-45-6789', // Well-known fake SSN
+  '127.0.0.1',
+  'localhost',
+  '0.0.0.0',
+  'example.com',
+  'test.com'
+];
+
+/**
+ * Context indicators that suggest non-PII usage
+ */
+export const NON_PII_CONTEXT_INDICATORS = [
+  'example',
+  'test',
+  'demo',
+  'sample',
+  'placeholder',
+  'fake',
+  'mock',
+  'dummy',
+  'template',
+  'default'
+];

package/src/policy/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Policy as Code Module
+ */
+
+export * from './opa-engine';