/**
 * @fileoverview Taint Propagator - Track taint flow across function boundaries
 * @module @nahisaho/musubix-security/analysis/interprocedural/taint-propagator
 * @trace REQ-SEC-001 (EARS: WHEN tainted data flows through function calls, THE system SHALL track it)
 */
import type { CallGraph, CallGraphEdge } from './call-graph-builder.js';
import type { TaintSinkCategory } from '../../types/taint.js';
import type { SourceDefinition } from '../sources/types.js';
import type { SinkDefinition } from '../sinks/types.js';
import type { SanitizerDefinition } from '../sanitizers/types.js';
/**
 * Simplified source info for findings
 */
export interface TaintSourceInfo {
    id: string;
    name: string;
    location: {
        file: string;
        line: number;
        column: number;
    };
    type: string;
    confidence: number;
}
/**
 * Simplified sink info for findings
 */
export interface TaintSinkInfo {
    id: string;
    name: string;
    location: {
        file: string;
        line: number;
        column: number;
    };
    category: TaintSinkCategory;
    confidence: number;
}
/**
 * Taint state for a variable/parameter
 */
export interface TaintState {
    /** Whether the value is tainted */
    isTainted: boolean;
    /** Source of taint (if tainted) */
    source?: TaintSourceInfo;
    /** Confidence level (0-1) */
    confidence: number;
    /** Sanitizers applied */
    sanitizers: string[];
    /** Categories this taint affects */
    affectedCategories: TaintSinkCategory[];
}
/**
 * Taint context within a function
 */
export interface FunctionTaintContext {
    /** Node ID */
    nodeId: string;
    /** Parameter taint states (by index) */
    parameterTaints: Map<number, TaintState>;
    /** Local variable taint states */
    localTaints: Map<string, TaintState>;
    /** Return value taint state */
    returnTaint?: TaintState;
    /** Whether function has side effects */
    hasSideEffects: boolean;
}
/**
 * Taint flow edge - represents taint flowing from one location to another
 */
export interface TaintFlowEdge {
    /** Unique ID */
    id: string;
    /** Source location */
    from: TaintLocation;
    /** Destination location */
    to: TaintLocation;
    /** Type of flow */
    flowType: TaintFlowType;
    /** Associated call edge (if interprocedural) */
    callEdge?: CallGraphEdge;
    /** Sanitizers in path */
    sanitizersApplied: string[];
    /** Confidence (0-1) */
    confidence: number;
}
/**
 * Location of taint
 */
export interface TaintLocation {
    /** Function node ID */
    nodeId: string;
    /** Variable name or parameter index */
    identifier: string;
    /** Line number */
    line: number;
    /** Column number */
    column: number;
    /** File path */
    filePath: string;
}
/**
 * Type of taint flow
 */
export type TaintFlowType = 'assignment' | 'parameter' | 'return' | 'property-access' | 'method-call' | 'callback' | 'implicit';
/**
 * Taint finding - vulnerability detected
 */
export interface TaintFinding {
    /** Unique ID */
    id: string;
    /** Severity level */
    severity: 'critical' | 'high' | 'medium' | 'low' | 'info';
    /** Vulnerability title */
    title: string;
    /** Description */
    description: string;
    /** CWE ID */
    cwe?: string;
    /** Source of taint */
    source: TaintSourceInfo;
    /** Sink where taint flows */
    sink: TaintSinkInfo;
    /** Complete taint flow path */
    flowPath: TaintFlowEdge[];
    /** Sanitizers in path (may be incomplete) */
    sanitizersInPath: string[];
    /** Whether sanitization is complete */
    sanitizationComplete: boolean;
    /** Confidence (0-1) */
    confidence: number;
    /** Suggested remediation */
    remediation?: string;
}
/**
 * Summary of taint analysis results
 */
export interface TaintSummary {
    /** Node ID */
    nodeId: string;
    /** Parameters that propagate taint to return */
    taintPropagatingParams: number[];
    /** Whether function sanitizes input */
    isSanitizer: boolean;
    /** Categories sanitized */
    sanitizesCategories: TaintSinkCategory[];
    /** Whether function is a sink */
    isSink: boolean;
    /** Sink category if applicable */
    sinkCategory?: TaintSinkCategory;
    /** Whether function is a source */
    isSource: boolean;
    /** Source type if applicable */
    sourceType?: string;
}
/**
 * Options for taint propagation
 */
export interface TaintPropagatorOptions {
    /** Maximum call depth to analyze */
    maxDepth?: number;
    /** Track implicit flows (control dependencies) */
    trackImplicitFlows?: boolean;
    /** Minimum confidence threshold */
    minConfidence?: number;
    /** Custom sources */
    customSources?: SourceDefinition[];
    /** Custom sinks */
    customSinks?: SinkDefinition[];
    /** Custom sanitizers */
    customSanitizers?: SanitizerDefinition[];
}
/**
 * Taint Propagator - Performs interprocedural taint analysis
 * @trace REQ-SEC-001
 */
export declare class TaintPropagator {
    private options;
    private functionSummaries;
    private sources;
    private sinks;
    private sanitizers;
    constructor(sources: SourceDefinition[], sinks: SinkDefinition[], sanitizers: SanitizerDefinition[], options?: TaintPropagatorOptions);
    /**
     * Analyze a call graph for taint vulnerabilities
     */
    analyze(callGraph: CallGraph, sourceLocations: TaintLocation[], functionContexts?: Map<string, FunctionTaintContext>): TaintFinding[];
    /**
     * Build summaries of each function's taint behavior
     */
    private buildFunctionSummaries;
    /**
     * Analyze a single function's taint behavior
     */
    private analyzeFunctionTaint;
    /**
     * Trace taint flow from a source location
     */
    private traceTaintFlow;
    /**
     * Find if a tainted value is passed as an argument
     */
    private findTaintedArgument;
    /**
     * Check if a flow path represents a vulnerability
     */
    private checkForVulnerability;
    /**
     * Check if sanitization is complete for a category
     */
    private checkSanitizationComplete;
    /**
     * Calculate severity based on sink category and sanitization
     */
    private calculateSeverity;
    /**
     * Generate vulnerability description
     */
    private generateDescription;
    /**
     * Generate remediation suggestion
     */
    private generateRemediation;
    /**
     * Deduplicate findings with same source and sink
     */
    private deduplicateFindings;
    /**
     * Match function name against pattern
     */
    private matchesFunctionName;
    /**
     * Get function summary by node ID
     */
    getFunctionSummary(nodeId: string): TaintSummary | undefined;
    /**
     * Get all source functions
     */
    getSourceFunctions(): TaintSummary[];
    /**
     * Get all sink functions
     */
    getSinkFunctions(): TaintSummary[];
    /**
     * Get all sanitizer functions
     */
    getSanitizerFunctions(): TaintSummary[];
}
//# sourceMappingURL=taint-propagator.d.ts.map