secure-scan 1.2.2

package/src/rules/vulnerabilities/types/index.ts

@@ -0,0 +1,1004 @@
+/**
+ * @fileoverview Vulnerability Detection Module - Type Definitions
+ * @module rules/vulnerabilities/types
+ * 
+ * Comprehensive type definitions for the vulnerability detection engine.
+ * Supports multi-language analysis, AST-aware detection, taint analysis,
+ * and enterprise-level reporting with OWASP/CWE/SANS/MITRE mappings.
+ */
+
+// ============================================================================
+// ENUMERATIONS
+// ============================================================================
+
+/**
+ * Supported programming languages for vulnerability detection
+ */
+export enum SupportedLanguage {
+  JAVASCRIPT = 'javascript',
+  TYPESCRIPT = 'typescript',
+  PYTHON = 'python',
+  PHP = 'php',
+  C = 'c',
+  CPP = 'cpp',
+  CSHARP = 'csharp',
+  JAVA = 'java',
+  RUBY = 'ruby',
+  GO = 'go',
+  RUST = 'rust',
+  SHELL = 'shell',
+  POWERSHELL = 'powershell',
+  DOCKERFILE = 'dockerfile',
+  YAML = 'yaml',
+  TERRAFORM = 'terraform'
+}
+
+/**
+ * Vulnerability categories based on OWASP classification
+ */
+export enum VulnerabilityCategory {
+  INJECTION = 'injection',
+  XSS = 'xss',
+  AUTHENTICATION = 'authentication',
+  SESSION_MANAGEMENT = 'session_management',
+  ACCESS_CONTROL = 'access_control',
+  BROKEN_ACCESS_CONTROL = 'broken_access_control',
+  CRYPTOGRAPHY = 'cryptography',
+  CRYPTOGRAPHIC_FAILURE = 'cryptographic_failure',
+  DESERIALIZATION = 'deserialization',
+  FILE_HANDLING = 'file_handling',
+  CONFIGURATION = 'configuration',
+  SECURITY_MISCONFIGURATION = 'security_misconfiguration',
+  INFORMATION_DISCLOSURE = 'information_disclosure',
+  SENSITIVE_DATA_EXPOSURE = 'sensitive_data_exposure',
+  INPUT_VALIDATION = 'input_validation',
+  INFRASTRUCTURE = 'infrastructure',
+  KNOWN_VULNERABLE_COMPONENT = 'known_vulnerable_component'
+}
+
+/**
+ * Specific vulnerability types
+ */
+export enum VulnerabilityType {
+  // Injection
+  SQL_INJECTION = 'sql_injection',
+  NOSQL_INJECTION = 'nosql_injection',
+  COMMAND_INJECTION = 'command_injection',
+  CODE_INJECTION = 'code_injection',
+  LDAP_INJECTION = 'ldap_injection',
+  XPATH_INJECTION = 'xpath_injection',
+  TEMPLATE_INJECTION = 'template_injection',
+  HEADER_INJECTION = 'header_injection',
+  
+  // XSS
+  XSS_REFLECTED = 'xss_reflected',
+  XSS_STORED = 'xss_stored',
+  XSS_DOM = 'xss_dom',
+  
+  // Request Forgery
+  CSRF = 'csrf',
+  SSRF = 'ssrf',
+  
+  // Deserialization
+  INSECURE_DESERIALIZATION = 'insecure_deserialization',
+  PROTOTYPE_POLLUTION = 'prototype_pollution',
+  
+  // File Handling
+  PATH_TRAVERSAL = 'path_traversal',
+  UNSAFE_FILE_UPLOAD = 'unsafe_file_upload',
+  FILE_UPLOAD = 'file_upload',
+  ARBITRARY_FILE_READ = 'arbitrary_file_read',
+  ARBITRARY_FILE_WRITE = 'arbitrary_file_write',
+  
+  // Authentication & Session
+  INSECURE_AUTHENTICATION = 'insecure_authentication',
+  BROKEN_AUTHENTICATION = 'broken_authentication',
+  BROKEN_SESSION = 'broken_session',
+  HARDCODED_CREDENTIALS = 'hardcoded_credentials',
+  HARDCODED_SECRETS = 'hardcoded_secrets',
+  WEAK_PASSWORD_POLICY = 'weak_password_policy',
+  
+  // Cryptography
+  WEAK_CRYPTO = 'weak_crypto',
+  WEAK_RANDOM = 'weak_random',
+  INSECURE_TLS = 'insecure_tls',
+  MISSING_ENCRYPTION = 'missing_encryption',
+  
+  // Access Control
+  BROKEN_ACCESS_CONTROL = 'broken_access_control',
+  IDOR = 'idor',
+  PRIVILEGE_ESCALATION = 'privilege_escalation',
+  
+  // Information Disclosure
+  INFORMATION_EXPOSURE = 'information_exposure',
+  ERROR_DISCLOSURE = 'error_disclosure',
+  DEBUG_ENABLED = 'debug_enabled',
+  
+  // Configuration
+  SECURITY_MISCONFIGURATION = 'security_misconfiguration',
+  CORS_MISCONFIGURATION = 'cors_misconfiguration',
+  INSECURE_HEADERS = 'insecure_headers',
+  DANGEROUS_FUNCTION = 'dangerous_function',
+  
+  // Infrastructure
+  DOCKERFILE_ISSUE = 'dockerfile_issue',
+  CICD_VULNERABILITY = 'cicd_vulnerability',
+  IaC_ISSUE = 'iac_issue'
+}
+
+/**
+ * Severity levels for vulnerability findings
+ */
+export enum VulnerabilitySeverity {
+  CRITICAL = 'critical',    // Immediate exploitation risk
+  HIGH = 'high',            // Serious vulnerability
+  MEDIUM = 'medium',        // Moderate risk
+  LOW = 'low',              // Minor concern
+  INFO = 'info'             // Informational only
+}
+
+/**
+ * Confidence level of the detection
+ */
+export enum ConfidenceLevel {
+  CONFIRMED = 'confirmed',  // 95%+ certainty, verified taint flow
+  HIGH = 'high',            // 80-95% certainty
+  MEDIUM = 'medium',        // 60-80% certainty
+  LOW = 'low',              // 40-60% certainty
+  TENTATIVE = 'tentative'   // <40% certainty
+}
+
+/**
+ * Pattern matching strategies
+ */
+export enum PatternType {
+  REGEX = 'regex',
+  LITERAL = 'literal',
+  AST = 'ast',
+  SEMANTIC = 'semantic',
+  TAINT = 'taint',
+  CFG = 'cfg'
+}
+
+/**
+ * Taint flow stages
+ */
+export enum TaintStage {
+  SOURCE = 'source',
+  PROPAGATION = 'propagation',
+  SANITIZER = 'sanitizer',
+  SINK = 'sink'
+}
+
+// ============================================================================
+// SECURITY STANDARDS REFERENCES
+// ============================================================================
+
+/**
+ * OWASP Top 10 reference
+ */
+export interface OwaspReference {
+  /** OWASP ID (e.g., A03:2021) */
+  id: string;
+  /** Category name */
+  name: string;
+  /** URL to OWASP documentation */
+  url?: string;
+}
+
+/**
+ * CWE reference
+ */
+export interface CweReference {
+  /** CWE ID (e.g., CWE-79) */
+  id: string;
+  /** CWE title */
+  title: string;
+  /** URL to CWE documentation */
+  url?: string;
+}
+
+/**
+ * SANS Top 25 reference
+ */
+export interface SansReference {
+  /** SANS ranking (1-25) */
+  rank: number;
+  /** Associated CWE ID */
+  cweId: string;
+  /** Category name */
+  category: string;
+}
+
+/**
+ * MITRE ATT&CK reference
+ */
+export interface MitreReference {
+  /** Tactic ID (e.g., TA0001) */
+  tacticId: string;
+  /** Tactic name */
+  tacticName: string;
+  /** Technique ID (e.g., T1059) */
+  techniqueId: string;
+  /** Technique name */
+  techniqueName: string;
+  /** Sub-technique ID if applicable */
+  subTechniqueId?: string;
+  /** URL to MITRE documentation */
+  url?: string;
+}
+
+/**
+ * CVE reference
+ */
+export interface CveReference {
+  /** CVE ID (e.g., CVE-2021-44228) */
+  cveId: string;
+  /** Brief description */
+  description: string;
+  /** CVSS score if available */
+  cvssScore?: number;
+  /** URL to CVE details */
+  url?: string;
+}
+
+/**
+ * Combined security standards for a vulnerability
+ */
+export interface SecurityStandards {
+  owasp?: OwaspReference[];
+  cwe?: CweReference[];
+  sans?: SansReference[];
+  mitre?: MitreReference[];
+  cve?: CveReference[];
+}
+
+// ============================================================================
+// PATTERN INTERFACES
+// ============================================================================
+
+/**
+ * Base pattern definition
+ */
+export interface VulnerabilityPatternBase {
+  /** Pattern type */
+  type: PatternType;
+  /** Pattern identifier for reference */
+  patternId?: string;
+  /** Languages this pattern applies to (empty = all) */
+  languages?: SupportedLanguage[];
+  /** Weight for scoring (0.0 - 1.0) */
+  weight?: number;
+  /** Description of what this pattern detects */
+  description?: string;
+}
+
+/**
+ * Regex-based pattern
+ */
+export interface RegexPattern extends VulnerabilityPatternBase {
+  type: PatternType.REGEX;
+  /** The regex pattern string */
+  pattern: string;
+  /** Regex flags (g, i, m, s, u) */
+  flags?: string;
+  /** Maximum execution time in ms (ReDoS protection) */
+  timeout?: number;
+  /** Maximum matches before stopping */
+  maxMatches?: number;
+}
+
+/**
+ * Literal string pattern
+ */
+export interface LiteralPattern extends VulnerabilityPatternBase {
+  type: PatternType.LITERAL;
+  /** The literal string to match */
+  value: string;
+  /** Case sensitive matching */
+  caseSensitive?: boolean;
+}
+
+/**
+ * AST-based pattern for structural matching
+ */
+export interface AstPattern extends VulnerabilityPatternBase {
+  type: PatternType.AST;
+  /** AST node type to match */
+  nodeType: string;
+  /** Properties to match on the node */
+  properties?: Record<string, unknown>;
+  /** Child patterns to match */
+  children?: AstPattern[];
+  /** Parent context requirements */
+  parentContext?: string[];
+}
+
+/**
+ * Taint analysis pattern
+ */
+export interface TaintPattern extends VulnerabilityPatternBase {
+  type: PatternType.TAINT;
+  /** Taint sources */
+  sources: TaintSource[];
+  /** Taint sinks */
+  sinks: TaintSink[];
+  /** Optional sanitizers that break the taint */
+  sanitizers?: TaintSanitizer[];
+  /** Required flow path */
+  requiredPath?: string[];
+}
+
+/**
+ * Semantic pattern for meaning-based matching
+ */
+export interface SemanticPattern extends VulnerabilityPatternBase {
+  type: PatternType.SEMANTIC;
+  /** Semantic concept to detect */
+  concept: string;
+  /** Required data flows */
+  dataFlows?: string[];
+}
+
+/**
+ * Control flow graph pattern
+ */
+export interface CfgPattern extends VulnerabilityPatternBase {
+  type: PatternType.CFG;
+  /** Entry point condition */
+  entryCondition: string;
+  /** Required path conditions */
+  pathConditions?: string[];
+  /** Exit point condition */
+  exitCondition: string;
+}
+
+/**
+ * Union type for all pattern types
+ */
+export type VulnerabilityPattern =
+  | RegexPattern
+  | LiteralPattern
+  | AstPattern
+  | TaintPattern
+  | SemanticPattern
+  | CfgPattern;
+
+// ============================================================================
+// TAINT ANALYSIS DEFINITIONS
+// ============================================================================
+
+/**
+ * Taint source definition
+ */
+export interface TaintSource {
+  /** Source identifier */
+  id: string;
+  /** Source name (e.g., req.body, $_GET) */
+  name: string;
+  /** Pattern to match the source */
+  pattern: string | RegExp;
+  /** Languages this source applies to */
+  languages?: SupportedLanguage[];
+  /** Trust level (0-100, lower = less trusted) */
+  trustLevel?: number;
+  /** Source category */
+  category?: 'user_input' | 'environment' | 'database' | 'network' | 'file';
+}
+
+/**
+ * Taint sink definition
+ */
+export interface TaintSink {
+  /** Sink identifier */
+  id: string;
+  /** Sink name (e.g., exec, innerHTML) */
+  name: string;
+  /** Pattern to match the sink */
+  pattern: string | RegExp;
+  /** Languages this sink applies to */
+  languages?: SupportedLanguage[];
+  /** Vulnerability type this sink can cause */
+  vulnerabilityType: VulnerabilityType;
+  /** Arguments that are dangerous (0-indexed) */
+  dangerousArgs?: number[];
+}
+
+/**
+ * Taint sanitizer definition
+ */
+export interface TaintSanitizer {
+  /** Sanitizer identifier */
+  id: string;
+  /** Sanitizer name */
+  name: string;
+  /** Pattern to match the sanitizer */
+  pattern: string | RegExp;
+  /** Languages this sanitizer applies to */
+  languages?: SupportedLanguage[];
+  /** Vulnerability types this sanitizer protects against */
+  protectsAgainst: VulnerabilityType[];
+  /** Effectiveness (0-100) */
+  effectiveness?: number;
+}
+
+/**
+ * Detected taint flow
+ */
+export interface TaintFlow {
+  /** Source of the taint */
+  source: TaintSource;
+  /** Sink where taint reaches */
+  sink: TaintSink;
+  /** Propagation path */
+  path: TaintPathNode[];
+  /** Applied sanitizers */
+  sanitizers: TaintSanitizer[];
+  /** Is the flow exploitable */
+  isExploitable: boolean;
+  /** Confidence of the flow detection */
+  confidence: ConfidenceLevel;
+}
+
+/**
+ * Node in taint propagation path
+ */
+export interface TaintPathNode {
+  /** Variable or expression name */
+  name: string;
+  /** Location in source */
+  location: SourceLocation;
+  /** Operation performed */
+  operation?: string;
+}
+
+// ============================================================================
+// RULE DEFINITION
+// ============================================================================
+
+/**
+ * Example code for documentation
+ */
+export interface CodeExample {
+  /** The example code */
+  code: string;
+  /** Language of the example */
+  language: SupportedLanguage;
+  /** Whether this is a vulnerable example */
+  isVulnerable: boolean;
+  /** Description of the example */
+  description: string;
+  /** If safe, explanation of why */
+  safetyExplanation?: string;
+}
+
+/**
+ * Impact assessment following CVSS-like scoring
+ */
+export interface ImpactAssessment {
+  /** Confidentiality impact (none, low, medium, high) */
+  confidentiality: 'none' | 'low' | 'medium' | 'high';
+  /** Integrity impact (none, low, medium, high) */
+  integrity: 'none' | 'low' | 'medium' | 'high';
+  /** Availability impact (none, low, medium, high) */
+  availability: 'none' | 'low' | 'medium' | 'high';
+  /** Scope (unchanged, changed) */
+  scope?: 'unchanged' | 'changed';
+  /** Technical impact description */
+  technicalImpact: string;
+  /** Business impact description */
+  businessImpact: string;
+  /** Affected assets */
+  affectedAssets?: string[];
+  /** Data at risk */
+  dataAtRisk?: string[];
+}
+
+/**
+ * Exploitability assessment
+ */
+export interface ExploitabilityAssessment {
+  /** Attack vector (network, adjacent, local, physical) */
+  attackVector: 'network' | 'adjacent' | 'local' | 'physical';
+  /** Attack complexity (low, medium, high) */
+  attackComplexity: 'low' | 'medium' | 'high';
+  /** Privileges required (none, low, high) */
+  privilegesRequired: 'none' | 'low' | 'high';
+  /** User interaction (none, required) */
+  userInteraction: 'none' | 'required';
+  /** Known exploits in the wild */
+  knownExploits?: boolean;
+  /** Exploit difficulty description */
+  exploitDifficulty?: string;
+}
+
+/**
+ * Remediation guidance
+ */
+export interface RemediationGuidance {
+  /** Short remediation summary */
+  summary: string;
+  /** Detailed steps */
+  steps: string[];
+  /** Secure code example */
+  secureCodeExample?: string;
+  /** References for more information */
+  references?: string[];
+  /** Estimated effort (low, medium, high) */
+  effort?: 'low' | 'medium' | 'high';
+  /** Priority for fixing */
+  priority?: 'immediate' | 'high' | 'medium' | 'low';
+}
+
+/**
+ * Rule correlation configuration
+ */
+export interface RuleCorrelation {
+  /** Rules that increase severity when both match */
+  amplifyWith?: string[];
+  /** Rules that must also match for this rule to trigger */
+  requiresAlso?: string[];
+  /** Rules that suppress this rule when matched */
+  suppressedBy?: string[];
+  /** Severity boost when correlated rules match */
+  severityBoost?: number;
+}
+
+/**
+ * Context conditions for severity adjustment
+ */
+export interface ContextConditions {
+  /** Boost severity if in production code */
+  productionBoost?: number;
+  /** Reduce severity if in test code */
+  testCodePenalty?: number;
+  /** Boost if handles sensitive data */
+  sensitiveDataBoost?: number;
+  /** File path patterns to adjust severity */
+  filePatterns?: Array<{
+    pattern: string;
+    severityAdjustment: number;
+  }>;
+}
+
+/**
+ * Comprehensive vulnerability detection rule
+ */
+export interface VulnerabilityRule {
+  // === Identification ===
+  /** Unique rule identifier (e.g., VUL-SQLI-001) */
+  id: string;
+  /** Human-readable rule name */
+  name: string;
+  /** Detailed technical description */
+  description: string;
+  /** Version of the rule */
+  version?: string;
+
+  // === Classification ===
+  /** Specific vulnerability type */
+  vulnerabilityType: VulnerabilityType;
+  /** Vulnerability category */
+  category: VulnerabilityCategory;
+  /** Languages this rule applies to */
+  languages: SupportedLanguage[];
+
+  // === Severity & Confidence ===
+  /** Base severity level */
+  severity: VulnerabilitySeverity;
+  /** Detection confidence */
+  confidence: ConfidenceLevel;
+
+  // === Detection Patterns ===
+  /** Primary detection patterns */
+  patterns: VulnerabilityPattern[];
+  /** Secondary patterns that increase severity */
+  amplifyingPatterns?: VulnerabilityPattern[];
+  /** Patterns that indicate false positive */
+  falsePositivePatterns?: VulnerabilityPattern[];
+
+  // === Taint Analysis ===
+  /** Taint sources for this vulnerability */
+  taintSources?: TaintSource[];
+  /** Taint sinks for this vulnerability */
+  taintSinks?: TaintSink[];
+  /** Sanitizers that prevent this vulnerability */
+  taintSanitizers?: TaintSanitizer[];
+  /** Simplified taint analysis config (sources, sinks, sanitizers as strings) */
+  taintAnalysis?: {
+    sources: string[];
+    sinks: string[];
+    sanitizers?: string[];
+  };
+
+  // === Correlation ===
+  /** Rule correlation configuration */
+  correlation?: RuleCorrelation;
+
+  // === Context-based Severity ===
+  /** Context conditions for severity adjustment */
+  contextConditions?: ContextConditions;
+
+  // === Scoring ===
+  /** Base score contribution (0-100) */
+  baseScore?: number;
+  /** Scoring factors */
+  scoringFactors?: ScoringFactors;
+
+  // === Impact & Exploitability ===
+  /** Impact assessment */
+  impact: ImpactAssessment;
+  /** Exploitability assessment */
+  exploitability?: ExploitabilityAssessment;
+
+  // === Documentation ===
+  /** Example vulnerable code */
+  vulnerableExamples?: CodeExample[];
+  /** Example secure code */
+  secureExamples?: CodeExample[];
+  /** Known false positive examples */
+  falsePositiveExamples?: CodeExample[];
+  /** Remediation guidance */
+  remediation: RemediationGuidance;
+
+  // === Security Standards ===
+  /** Security standard references */
+  standards: SecurityStandards;
+
+  // === Metadata ===
+  /** Tags for categorization */
+  tags: string[];
+  /** Whether the rule is enabled */
+  enabled: boolean;
+  /** Author of the rule */
+  author?: string;
+  /** Creation date */
+  createdAt?: string;
+  /** Last update date */
+  updatedAt?: string;
+}
+
+// ============================================================================
+// SCORING SYSTEM
+// ============================================================================
+
+/**
+ * Scoring factors for dynamic severity calculation
+ */
+export interface ScoringFactors {
+  /** Taint flow weight */
+  taintFlowWeight?: number;
+  /** Pattern count weight */
+  patternCountWeight?: number;
+  /** Exploitability weight */
+  exploitabilityWeight?: number;
+  /** Impact weight */
+  impactWeight?: number;
+  /** Context weight */
+  contextWeight?: number;
+}
+
+/**
+ * Vulnerability score breakdown
+ */
+export interface VulnerabilityScoreBreakdown {
+  /** Base score from rule */
+  baseScore: number;
+  /** Score from pattern matches */
+  patternScore: number;
+  /** Score from taint analysis */
+  taintScore: number;
+  /** Score from exploitability */
+  exploitabilityScore: number;
+  /** Score from impact assessment */
+  impactScore: number;
+  /** Score from context analysis */
+  contextScore: number;
+  /** Penalty for false positive indicators */
+  falsePositivePenalty: number;
+  /** Boost from correlated rules */
+  correlationBoost: number;
+  /** Final calculated score */
+  totalScore: number;
+}
+
+/**
+ * Complete vulnerability score result
+ */
+export interface VulnerabilityScore {
+  /** Numeric score (0-100) */
+  score: number;
+  /** Score breakdown */
+  breakdown: VulnerabilityScoreBreakdown;
+  /** Calculated severity from score */
+  calculatedSeverity: VulnerabilitySeverity;
+  /** Risk level description */
+  riskLevel: 'critical' | 'high' | 'medium' | 'low' | 'minimal';
+  /** Explanation of the score */
+  explanation: string;
+}
+
+// ============================================================================
+// FINDINGS
+// ============================================================================
+
+/**
+ * Location of a finding in source code
+ */
+export interface SourceLocation {
+  /** File path */
+  filePath: string;
+  /** Starting line number (1-based) */
+  startLine: number;
+  /** Ending line number (1-based) */
+  endLine: number;
+  /** Starting column (0-based) */
+  startColumn?: number;
+  /** Ending column (0-based) */
+  endColumn?: number;
+}
+
+/**
+ * Pattern match details
+ */
+export interface PatternMatch {
+  /** Pattern that matched */
+  pattern: VulnerabilityPattern;
+  /** Matched text */
+  matchedText: string;
+  /** Location of the match */
+  location: SourceLocation;
+  /** Capture groups if regex */
+  captures?: string[];
+}
+
+/**
+ * Data flow trace for audit reporting
+ */
+export interface DataFlowTrace {
+  /** Starting source */
+  source: {
+    name: string;
+    location: SourceLocation;
+    codeSnippet: string;
+  };
+  /** Intermediate steps */
+  propagation: Array<{
+    variable: string;
+    location: SourceLocation;
+    operation: string;
+    codeSnippet: string;
+  }>;
+  /** Ending sink */
+  sink: {
+    name: string;
+    location: SourceLocation;
+    codeSnippet: string;
+  };
+  /** Was the data sanitized? */
+  sanitized: boolean;
+  /** Sanitization details if applicable */
+  sanitizationDetails?: {
+    sanitizer: string;
+    location: SourceLocation;
+    effectiveness: number;
+  };
+}
+
+/**
+ * Complete vulnerability finding
+ */
+export interface VulnerabilityFinding {
+  // === Identification ===
+  /** Unique finding ID */
+  id: string;
+  /** Rule that triggered this finding */
+  ruleId: string;
+  /** Rule name */
+  ruleName: string;
+
+  // === Location ===
+  /** Source code location */
+  location: SourceLocation;
+  /** Code snippet */
+  codeSnippet: string;
+  /** Highlighted portion */
+  highlightedCode?: string;
+
+  // === Classification ===
+  /** Vulnerability type */
+  vulnerabilityType: VulnerabilityType;
+  /** Vulnerability category */
+  category: VulnerabilityCategory;
+  /** Final severity */
+  severity: VulnerabilitySeverity;
+  /** Confidence level */
+  confidence: ConfidenceLevel;
+
+  // === Scoring ===
+  /** Vulnerability score */
+  score: VulnerabilityScore;
+
+  // === Detection Details ===
+  /** Patterns that matched */
+  patternMatches: PatternMatch[];
+  /** Taint flow if detected */
+  taintFlow?: TaintFlow;
+  /** Data flow trace for audit */
+  dataFlowTrace?: DataFlowTrace;
+  /** Correlated findings */
+  correlatedFindings?: string[];
+
+  // === Reporting ===
+  /** Human-readable message */
+  message: string;
+  /** Detailed analysis for auditors */
+  auditAnalysis: string;
+  /** Developer-friendly explanation */
+  developerExplanation: string;
+  /** Remediation guidance */
+  remediation: RemediationGuidance;
+
+  // === Security Standards ===
+  /** Security standard references */
+  standards: SecurityStandards;
+
+  // === Metadata ===
+  /** Detection timestamp */
+  detectedAt: string;
+  /** Language of the code */
+  language: SupportedLanguage;
+  /** Is in test code */
+  isTestCode?: boolean;
+  /** Is in vendor/node_modules */
+  isVendorCode?: boolean;
+  /** Additional context */
+  context?: Record<string, unknown>;
+}
+
+// ============================================================================
+// ANALYSIS CONTEXT
+// ============================================================================
+
+/**
+ * Analysis context for rule evaluation
+ */
+export interface AnalysisContext {
+  /** File being analyzed */
+  filePath: string;
+  /** File content */
+  content: string;
+  /** Detected language */
+  language: SupportedLanguage;
+  /** AST if available */
+  ast?: unknown;
+  /** Control flow graph if available */
+  cfg?: unknown;
+  /** Call graph if available */
+  callGraph?: unknown;
+  /** Detected taint flows */
+  taintFlows?: TaintFlow[];
+  /** Dependencies if available */
+  dependencies?: string[];
+  /** Is this in node_modules or vendor */
+  isVendorCode?: boolean;
+  /** Is this a test file */
+  isTestFile?: boolean;
+  /** Is this production code */
+  isProductionCode?: boolean;
+  /** File handles sensitive data */
+  handlesSensitiveData?: boolean;
+  /** Previous findings in this file */
+  previousFindings?: VulnerabilityFinding[];
+  /** Findings from related files */
+  relatedFindings?: VulnerabilityFinding[];
+  /** Project configuration */
+  projectConfig?: ProjectConfig;
+}
+
+/**
+ * Project configuration for context-aware analysis
+ */
+export interface ProjectConfig {
+  /** Framework being used */
+  framework?: string;
+  /** Production vs development */
+  environment?: 'production' | 'development' | 'staging';
+  /** Configured security headers */
+  securityHeaders?: string[];
+  /** Enabled security features */
+  securityFeatures?: string[];
+}
+
+/**
+ * Analysis options
+ */
+export interface AnalysisOptions {
+  /** Enable taint analysis */
+  enableTaintAnalysis?: boolean;
+  /** Enable AST analysis */
+  enableAstAnalysis?: boolean;
+  /** Enable CFG analysis */
+  enableCfgAnalysis?: boolean;
+  /** Minimum confidence to report */
+  minConfidence?: ConfidenceLevel;
+  /** Maximum findings per file */
+  maxFindingsPerFile?: number;
+  /** Timeout per rule in ms */
+  ruleTimeoutMs?: number;
+  /** Include info severity */
+  includeInfo?: boolean;
+  /** Exclude test files */
+  excludeTestFiles?: boolean;
+  /** Exclude vendor code */
+  excludeVendorCode?: boolean;
+}
+
+// ============================================================================
+// ENGINE INTERFACES
+// ============================================================================
+
+/**
+ * Pattern matcher interface
+ */
+export interface IPatternMatcher {
+  match(
+    content: string,
+    patterns: VulnerabilityPattern[],
+    language: SupportedLanguage
+  ): PatternMatch[];
+
+  matchWithTimeout(
+    content: string,
+    patterns: VulnerabilityPattern[],
+    language: SupportedLanguage,
+    timeout: number
+  ): Promise<PatternMatch[]>;
+}
+
+/**
+ * Taint analyzer interface
+ */
+export interface ITaintAnalyzer {
+  analyze(
+    context: AnalysisContext,
+    sources: TaintSource[],
+    sinks: TaintSink[],
+    sanitizers?: TaintSanitizer[]
+  ): TaintFlow[];
+}
+
+/**
+ * Score calculator interface
+ */
+export interface IScoreCalculator {
+  calculateScore(
+    rule: VulnerabilityRule,
+    matches: PatternMatch[],
+    context: AnalysisContext,
+    taintFlow?: TaintFlow
+  ): VulnerabilityScore;
+}
+
+/**
+ * Vulnerability rule engine interface
+ */
+export interface IVulnerabilityRuleEngine {
+  /** Analyze code against all enabled rules */
+  analyze(
+    context: AnalysisContext,
+    options?: AnalysisOptions
+  ): Promise<VulnerabilityFinding[]>;
+
+  /** Get all registered rules */
+  getRules(): VulnerabilityRule[];
+
+  /** Get rule by ID */
+  getRule(id: string): VulnerabilityRule | undefined;
+
+  /** Enable/disable a rule */
+  setRuleEnabled(id: string, enabled: boolean): void;
+
+  /** Add a custom rule */
+  addRule(rule: VulnerabilityRule): void;
+}