secure-scan 1.2.2

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

@@ -0,0 +1,752 @@
+/**
+ * @fileoverview Malware Detection Module - Type Definitions
+ * @module rules/malware/types
+ * 
+ * Comprehensive type definitions for the malware detection engine.
+ * Supports multi-language analysis, AST-aware detection, and enterprise-level reporting.
+ */
+
+// ============================================================================
+// ENUMERATIONS
+// ============================================================================
+
+/**
+ * Supported programming languages for malware 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'
+}
+
+/**
+ * Malware threat categories based on behavior and intent
+ */
+export enum MalwareThreatType {
+  // Backdoors & Remote Access
+  REVERSE_SHELL = 'reverse_shell',
+  WEB_SHELL = 'web_shell',
+  BACKDOOR = 'backdoor',
+  RAT = 'remote_access_trojan',
+  
+  // Resource Abuse
+  CRYPTOMINER = 'cryptominer',
+  RESOURCE_HIJACKER = 'resource_hijacker',
+  
+  // Data Theft
+  KEYLOGGER = 'keylogger',
+  CREDENTIAL_STEALER = 'credential_stealer',
+  TOKEN_STEALER = 'token_stealer',
+  DATA_EXFILTRATION = 'data_exfiltration',
+  COOKIE_STEALER = 'cookie_stealer',
+  
+  // Loaders & Droppers
+  DROPPER = 'dropper',
+  LOADER = 'loader',
+  DOWNLOADER = 'downloader',
+  MULTI_STAGE = 'multi_stage',
+  
+  // Evasion & Obfuscation
+  OBFUSCATED_CODE = 'obfuscated_code',
+  ANTI_DEBUGGING = 'anti_debugging',
+  SANDBOX_EVASION = 'sandbox_evasion',
+  
+  // Network
+  BOTNET = 'botnet',
+  C2_COMMUNICATION = 'c2_communication',
+  DNS_TUNNELING = 'dns_tunneling',
+  
+  // Persistence
+  PERSISTENCE = 'persistence',
+  FILELESS = 'fileless',
+  LIVING_OFF_THE_LAND = 'lotl',
+  
+  // Supply Chain
+  SUPPLY_CHAIN = 'supply_chain',
+  DEPENDENCY_CONFUSION = 'dependency_confusion',
+  TYPOSQUATTING = 'typosquatting',
+  
+  // Other
+  EMBEDDED_PAYLOAD = 'embedded_payload',
+  SUSPICIOUS_NETWORK = 'suspicious_network',
+  TIME_BOMB = 'time_bomb',
+  LOGIC_BOMB = 'logic_bomb'
+}
+
+/**
+ * Severity levels for malware findings
+ */
+export enum MalwareSeverity {
+  CRITICAL = 'critical',    // Immediate threat, active malware
+  HIGH = 'high',            // Dangerous patterns, likely malicious
+  MEDIUM = 'medium',        // Suspicious behavior, needs review
+  LOW = 'low',              // Minor concern, potential FP
+  INFO = 'info'             // Informational, context-dependent
+}
+
+/**
+ * Confidence level of the detection
+ */
+export enum ConfidenceLevel {
+  CONFIRMED = 'confirmed',  // 95%+ certainty
+  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',
+  HEURISTIC = 'heuristic',
+  BEHAVIORAL = 'behavioral'
+}
+
+/**
+ * MITRE ATT&CK Tactics
+ */
+export enum MitreTactic {
+  INITIAL_ACCESS = 'TA0001',
+  EXECUTION = 'TA0002',
+  PERSISTENCE = 'TA0003',
+  PRIVILEGE_ESCALATION = 'TA0004',
+  DEFENSE_EVASION = 'TA0005',
+  CREDENTIAL_ACCESS = 'TA0006',
+  DISCOVERY = 'TA0007',
+  LATERAL_MOVEMENT = 'TA0008',
+  COLLECTION = 'TA0009',
+  COMMAND_AND_CONTROL = 'TA0011',
+  EXFILTRATION = 'TA0010',
+  IMPACT = 'TA0040'
+}
+
+// ============================================================================
+// PATTERN INTERFACES
+// ============================================================================
+
+/**
+ * Base pattern definition
+ */
+export interface MalwarePatternBase {
+  /** 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 MalwarePatternBase {
+  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 MalwarePatternBase {
+  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 MalwarePatternBase {
+  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[];
+}
+
+/**
+ * Semantic pattern for meaning-based matching
+ */
+export interface SemanticPattern extends MalwarePatternBase {
+  type: PatternType.SEMANTIC;
+  /** Semantic concept to detect */
+  concept: string;
+  /** Required data flows */
+  dataFlows?: string[];
+  /** Taint sources */
+  taintSources?: string[];
+  /** Taint sinks */
+  taintSinks?: string[];
+}
+
+/**
+ * Heuristic pattern for behavior-based detection
+ */
+export interface HeuristicPattern extends MalwarePatternBase {
+  type: PatternType.HEURISTIC;
+  /** Heuristic function name */
+  heuristicName: string;
+  /** Threshold for triggering */
+  threshold?: number;
+  /** Custom parameters */
+  params?: Record<string, unknown>;
+}
+
+/**
+ * Union type for all pattern types
+ */
+export type MalwarePattern = 
+  | RegexPattern 
+  | LiteralPattern 
+  | AstPattern 
+  | SemanticPattern 
+  | HeuristicPattern;
+
+// ============================================================================
+// MITRE ATT&CK MAPPING
+// ============================================================================
+
+/**
+ * MITRE ATT&CK technique reference
+ */
+export interface MitreReference {
+  /** Tactic ID (e.g., TA0002) */
+  tacticId: MitreTactic;
+  /** Tactic name */
+  tacticName: string;
+  /** Technique ID (e.g., T1059) */
+  techniqueId: string;
+  /** Technique name */
+  techniqueName: string;
+  /** Sub-technique ID if applicable */
+  subTechniqueId?: string;
+  /** Sub-technique name */
+  subTechniqueName?: 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;
+}
+
+// ============================================================================
+// RULE DEFINITION
+// ============================================================================
+
+/**
+ * Example code for documentation
+ */
+export interface CodeExample {
+  /** The example code */
+  code: string;
+  /** Language of the example */
+  language: SupportedLanguage;
+  /** Whether this is a malicious example */
+  isMalicious: boolean;
+  /** Description of the example */
+  description: string;
+}
+
+/**
+ * Impact assessment
+ */
+export interface ImpactAssessment {
+  /** Technical impact description */
+  technical: string;
+  /** Business impact description */
+  business: string;
+  /** Affected assets */
+  affectedAssets?: string[];
+  /** Potential data at risk */
+  dataAtRisk?: string[];
+}
+
+/**
+ * Remediation guidance
+ */
+export interface RemediationGuidance {
+  /** Short remediation summary */
+  summary: string;
+  /** Detailed steps */
+  steps?: string[];
+  /** Code fix example if applicable */
+  codeExample?: string;
+  /** References for more information */
+  references?: string[];
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Comprehensive malware detection rule
+ */
+export interface MalwareRule {
+  // === Identification ===
+  /** Unique rule identifier (e.g., MAL-BACK-001) */
+  id: string;
+  /** Human-readable rule name */
+  name: string;
+  /** Detailed technical description */
+  description: string;
+  /** Version of the rule */
+  version?: string;
+  
+  // === Classification ===
+  /** Type of malware this rule detects */
+  threatType: MalwareThreatType;
+  /** Threat category */
+  category: MalwareCategory;
+  /** Languages this rule applies to */
+  languages: SupportedLanguage[];
+  
+  // === Severity & Confidence ===
+  /** Base severity level */
+  severity: MalwareSeverity;
+  /** Detection confidence */
+  confidence: ConfidenceLevel;
+  
+  // === Detection Patterns ===
+  /** Primary detection patterns */
+  patterns: MalwarePattern[];
+  /** Secondary patterns that increase severity */
+  amplifyingPatterns?: MalwarePattern[];
+  /** Patterns that indicate false positive */
+  falsePositivePatterns?: MalwarePattern[];
+  
+  // === Correlation ===
+  /** Rule correlation configuration */
+  correlation?: RuleCorrelation;
+  
+  // === Scoring ===
+  /** Base score contribution (0-100) */
+  baseScore?: number;
+  /** Scoring factors */
+  scoringFactors?: ScoringFactors;
+  
+  // === Documentation ===
+  /** Example malicious code */
+  maliciousExamples?: CodeExample[];
+  /** Known false positive examples */
+  falsePositiveExamples?: CodeExample[];
+  /** Impact assessment */
+  impact?: ImpactAssessment;
+  /** Remediation guidance */
+  remediation: RemediationGuidance;
+  
+  // === References ===
+  /** MITRE ATT&CK mappings */
+  mitreAttack?: MitreReference[];
+  /** Related CVEs */
+  cves?: CveReference[];
+  /** Additional reference URLs */
+  references?: string[];
+  
+  // === 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 {
+  /** Patterns detected count weight */
+  patternCountWeight?: number;
+  /** Obfuscation level weight */
+  obfuscationWeight?: number;
+  /** Network access weight */
+  networkAccessWeight?: number;
+  /** Command execution weight */
+  commandExecutionWeight?: number;
+  /** Persistence mechanism weight */
+  persistenceWeight?: number;
+  /** Data access weight */
+  dataAccessWeight?: number;
+}
+
+/**
+ * Malware score breakdown
+ */
+export interface MalwareScoreBreakdown {
+  /** Base score from rule */
+  baseScore: number;
+  /** Score from pattern matches */
+  patternScore: number;
+  /** Score from obfuscation detection */
+  obfuscationScore: number;
+  /** Score from network indicators */
+  networkScore: number;
+  /** Score from execution indicators */
+  executionScore: number;
+  /** Score from persistence indicators */
+  persistenceScore: number;
+  /** Score from correlation with other rules */
+  correlationScore: number;
+  /** Penalty for false positive indicators */
+  falsePositivePenalty: number;
+  /** Final calculated score */
+  totalScore: number;
+}
+
+/**
+ * Complete malware score result
+ */
+export interface MalwareScore {
+  /** Numeric score (0-100) */
+  score: number;
+  /** Score breakdown */
+  breakdown: MalwareScoreBreakdown;
+  /** Calculated severity from score */
+  calculatedSeverity: MalwareSeverity;
+  /** 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: MalwarePattern;
+  /** Matched text */
+  matchedText: string;
+  /** Location of the match */
+  location: SourceLocation;
+  /** Capture groups if regex */
+  captures?: string[];
+}
+
+/**
+ * Complete malware finding
+ */
+export interface MalwareFinding {
+  // === 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 ===
+  /** Threat type */
+  threatType: MalwareThreatType;
+  /** Category */
+  category: MalwareCategory;
+  /** Final severity */
+  severity: MalwareSeverity;
+  /** Confidence level */
+  confidence: ConfidenceLevel;
+  
+  // === Scoring ===
+  /** Malware score */
+  malwareScore: MalwareScore;
+  
+  // === Detection Details ===
+  /** Patterns that matched */
+  patternMatches: PatternMatch[];
+  /** Correlated findings */
+  correlatedFindings?: string[];
+  
+  // === Reporting ===
+  /** Human-readable message */
+  message: string;
+  /** Detailed analysis */
+  analysis: string;
+  /** Remediation guidance */
+  remediation: RemediationGuidance;
+  
+  // === References ===
+  /** MITRE ATT&CK references */
+  mitreAttack?: MitreReference[];
+  /** CVE references */
+  cves?: CveReference[];
+  
+  // === Metadata ===
+  /** Detection timestamp */
+  detectedAt: string;
+  /** Language of the code */
+  language: SupportedLanguage;
+  /** 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;
+  /** Call graph if available */
+  callGraph?: unknown;
+  /** Dependencies if available */
+  dependencies?: string[];
+  /** Is this in node_modules or vendor */
+  isVendorCode?: boolean;
+  /** Is this a test file */
+  isTestFile?: boolean;
+  /** Previous findings in this file */
+  previousFindings?: MalwareFinding[];
+  /** Findings from related files */
+  relatedFindings?: MalwareFinding[];
+}
+
+/**
+ * Analysis options
+ */
+export interface AnalysisOptions {
+  /** Maximum findings per file */
+  maxFindingsPerFile?: number;
+  /** Maximum time per rule in ms */
+  ruleTimeout?: number;
+  /** Maximum time per file in ms */
+  fileTimeout?: number;
+  /** Include disabled rules */
+  includeDisabled?: boolean;
+  /** Minimum severity to report */
+  minSeverity?: MalwareSeverity;
+  /** Minimum confidence to report */
+  minConfidence?: ConfidenceLevel;
+  /** Enable AST-based detection */
+  enableAst?: boolean;
+  /** Enable heuristic detection */
+  enableHeuristics?: boolean;
+  /** Enable correlation analysis */
+  enableCorrelation?: boolean;
+  /** Ignore vendor/node_modules */
+  ignoreVendor?: boolean;
+  /** Ignore test files */
+  ignoreTests?: boolean;
+}
+
+/**
+ * Analysis result summary
+ */
+export interface AnalysisResult {
+  /** All findings */
+  findings: MalwareFinding[];
+  /** Summary statistics */
+  summary: {
+    totalFindings: number;
+    bySeverity: Record<MalwareSeverity, number>;
+    byThreatType: Record<string, number>;
+    byConfidence: Record<ConfidenceLevel, number>;
+    highestScore: number;
+    averageScore: number;
+  };
+  /** Files analyzed */
+  filesAnalyzed: string[];
+  /** Analysis duration in ms */
+  duration: number;
+  /** Any errors during analysis */
+  errors?: Array<{
+    file: string;
+    rule?: string;
+    error: string;
+  }>;
+}
+
+// ============================================================================
+// CATEGORIES
+// ============================================================================
+
+/**
+ * Malware finding categories
+ */
+export enum MalwareCategory {
+  BACKDOOR = 'backdoor',
+  CRYPTOMINER = 'cryptominer',
+  SPYWARE = 'spyware',
+  TROJAN = 'trojan',
+  WORM = 'worm',
+  RANSOMWARE = 'ransomware',
+  ADWARE = 'adware',
+  ROOTKIT = 'rootkit',
+  BOTNET = 'botnet',
+  EXPLOIT = 'exploit',
+  DROPPER = 'dropper',
+  OBFUSCATION = 'obfuscation',
+  EVASION = 'evasion',
+  SUPPLY_CHAIN = 'supply_chain',
+  SUSPICIOUS = 'suspicious'
+}
+
+// ============================================================================
+// ENGINE INTERFACES
+// ============================================================================
+
+/**
+ * Rule engine interface
+ */
+export interface IMalwareRuleEngine {
+  /** Analyze a file */
+  analyze(context: AnalysisContext, options?: AnalysisOptions): Promise<MalwareFinding[]>;
+  /** Get all available rules */
+  getRules(): MalwareRule[];
+  /** Get rules by category */
+  getRulesByCategory(category: MalwareCategory): MalwareRule[];
+  /** Get rules by threat type */
+  getRulesByThreatType(type: MalwareThreatType): MalwareRule[];
+  /** Enable/disable a rule */
+  setRuleEnabled(ruleId: string, enabled: boolean): void;
+  /** Add a custom rule */
+  addRule(rule: MalwareRule): void;
+  /** Remove a rule */
+  removeRule(ruleId: string): void;
+}
+
+/**
+ * Pattern matcher interface
+ */
+export interface IPatternMatcher {
+  /** Match patterns against content */
+  match(
+    content: string, 
+    patterns: MalwarePattern[], 
+    language: SupportedLanguage
+  ): PatternMatch[];
+  /** Match with timeout protection */
+  matchWithTimeout(
+    content: string, 
+    patterns: MalwarePattern[], 
+    language: SupportedLanguage,
+    timeout: number
+  ): Promise<PatternMatch[]>;
+}
+
+/**
+ * Score calculator interface
+ */
+export interface IScoreCalculator {
+  /** Calculate malware score for a finding */
+  calculateScore(
+    rule: MalwareRule,
+    matches: PatternMatch[],
+    context: AnalysisContext
+  ): MalwareScore;
+  /** Calculate combined score for multiple findings */
+  calculateCombinedScore(findings: MalwareFinding[]): MalwareScore;
+}
+
+/**
+ * Heuristic analyzer interface
+ */
+export interface IHeuristicAnalyzer {
+  /** Calculate entropy of content */
+  calculateEntropy(content: string): number;
+  /** Detect obfuscation level */
+  detectObfuscationLevel(content: string, language: SupportedLanguage): number;
+  /** Normalize code for analysis */
+  normalizeCode(content: string, language: SupportedLanguage): string;
+  /** Check for anti-debugging patterns */
+  hasAntiDebugging(content: string, language: SupportedLanguage): boolean;
+  /** Check for environment-dependent activation */
+  hasEnvironmentChecks(content: string): boolean;
+}