pompelmi 0.35.5 → 1.0.0

package/dist/types/engines/hybrid-orchestrator.d.ts

@@ -1,65 +0,0 @@
-/**
- * Hybrid Analysis Orchestrator
- *
- * Advanced orchestration framework for coordinating multiple analysis engines
- * including Binary Ninja, Ghidra, dynamic taint tracking, and custom engines.
- */
-import type { AnalysisEngine, AnalysisPhase, EngineCapability, HybridAnalysisResult, HybridConfig, HybridOrchestrator } from "../types/taint-tracking";
-/**
- * Main hybrid orchestration engine
- */
-export declare class HybridAnalysisOrchestrator implements HybridOrchestrator {
-    private config;
-    private engines;
-    private correlator;
-    private activeSessions;
-    /**
-     * Configure the orchestrator
-     */
-    configure(config: HybridConfig): Promise<void>;
-    /**
-     * Register an analysis engine with the orchestrator
-     */
-    registerEngine(engine: AnalysisEngine, instance: any, capabilities: EngineCapability): Promise<void>;
-    /**
-     * Execute comprehensive hybrid analysis
-     */
-    analyze(data: Uint8Array): Promise<HybridAnalysisResult>;
-    /**
-     * Get available engines and their capabilities
-     */
-    getAvailableEngines(): Promise<EngineCapability[]>;
-    /**
-     * Cancel ongoing analysis
-     */
-    cancelAnalysis(sessionId: string): Promise<boolean>;
-    /**
-     * Get analysis progress
-     */
-    getProgress(sessionId: string): Promise<{
-        phase: AnalysisPhase;
-        completedTasks: number;
-        totalTasks: number;
-        estimatedTimeRemaining: number;
-    }>;
-    /**
-     * Generate analysis tasks based on orchestration strategy
-     */
-    private generateAnalysisTasks;
-    /**
-     * Execute tasks with proper scheduling and dependency management
-     */
-    private executeTasks;
-    /**
-     * Execute a single analysis task
-     */
-    private executeTask;
-    private calculateTaskDependencies;
-    private calculateTaskPriority;
-    private estimateTaskDuration;
-    private calculateResultConfidence;
-    private findTaskEngine;
-    private determineCurrentPhase;
-    private generateHybridResult;
-    private generateRecommendations;
-}

package/dist/types/engines/hybrid-taint-integration.d.ts

@@ -1,129 +0,0 @@
-/**
- * Hybrid Taint Analysis Integration
- *
- * Complete integration package for dynamic taint tracking and hybrid orchestration
- * with existing Pompelmi decompilation engines and HIPAA compliance.
- */
-import type { DecompilationResult, DecompilationScanner } from "../types/decompilation";
-import type { AnalysisEngine, HybridAnalysisResult, HybridConfig, TaintAnalysisResult, TaintConfig } from "../types/taint-tracking";
-import type { TaintPolicy } from "./taint-policies";
-/**
- * Enhanced analysis result combining all engines
- */
-export interface EnhancedAnalysisResult {
-    /** Analysis session ID */
-    sessionId: string;
-    /** Overall success status */
-    success: boolean;
-    /** Total analysis time */
-    totalTime: number;
-    /** Static analysis results */
-    static?: {
-        binaryNinja?: DecompilationResult;
-        ghidra?: DecompilationResult;
-    };
-    /** Dynamic taint analysis results */
-    taint?: TaintAnalysisResult;
-    /** Hybrid orchestration results */
-    hybrid?: HybridAnalysisResult;
-    /** Policy used for analysis */
-    policy?: TaintPolicy;
-    /** Security assessment */
-    security: {
-        riskScore: number;
-        vulnerabilities: Array<{
-            type: string;
-            severity: "low" | "medium" | "high" | "critical";
-            confidence: number;
-            description: string;
-            evidence: any;
-            mitigations: string[];
-        }>;
-        recommendations: string[];
-    };
-    /** Compliance assessment */
-    compliance?: {
-        hipaaCompliant: boolean;
-        issues: Array<{
-            type: string;
-            severity: "info" | "warning" | "critical";
-            description: string;
-            remediation: string;
-        }>;
-        auditTrail: any[];
-    };
-    /** Performance metrics */
-    performance: {
-        enginesUsed: AnalysisEngine[];
-        totalInstructions: number;
-        memoryPeak: number;
-        cpuTime: number;
-    };
-}
-/**
- * Main integration class for hybrid taint analysis
- */
-export declare class HybridTaintAnalyzer {
-    private orchestrator;
-    private policyManager;
-    private taintEngine;
-    private registeredEngines;
-    constructor();
-    /**
-     * Initialize the analyzer with registered engines
-     */
-    initialize(engines: {
-        binaryNinja?: DecompilationScanner;
-        ghidra?: DecompilationScanner;
-    }): Promise<void>;
-    /**
-     * Perform comprehensive analysis using specified policy
-     */
-    analyze(data: Uint8Array, policyName?: string, options?: {
-        enabledEngines?: AnalysisEngine[];
-        customConfig?: Partial<HybridConfig>;
-        includeCompliance?: boolean;
-    }): Promise<EnhancedAnalysisResult>;
-    /**
-     * Get available analysis policies
-     */
-    getAvailablePolicies(): TaintPolicy[];
-    /**
-     * Get policies by use case
-     */
-    getPoliciesByUseCase(useCase: "malware" | "vulnerability" | "compliance" | "forensics" | "general"): TaintPolicy[];
-    /**
-     * Register a custom analysis policy
-     */
-    registerPolicy(policy: TaintPolicy): void;
-    /**
-     * Perform quick taint analysis without full orchestration
-     */
-    quickTaintAnalysis(data: Uint8Array, config?: Partial<TaintConfig>): Promise<TaintAnalysisResult>;
-    /**
-     * Check if data contains taint at specific location
-     */
-    checkTaint(address: string): Promise<boolean>;
-    /**
-     * Add custom taint source for analysis
-     */
-    addTaintSource(address: string, source: string, metadata?: any): Promise<void>;
-    private registerEngine;
-    private createEngineCapabilities;
-    private createHybridConfig;
-    private mergeConfigs;
-    private processResults;
-    private extractStaticResults;
-    private calculateSecurityAssessment;
-    private calculateComplianceAssessment;
-    private calculatePerformanceMetrics;
-    private generateSecurityRecommendations;
-    private generateAuditTrail;
-    private getDefaultTaintConfig;
-    private generateSessionId;
-    private createFailureResult;
-}
-export declare function analyzeWithTaint(data: Uint8Array, engines: {
-    binaryNinja?: DecompilationScanner;
-    ghidra?: DecompilationScanner;
-}, policy?: string): Promise<EnhancedAnalysisResult>;

package/dist/types/engines/taint-policies.d.ts

@@ -1,84 +0,0 @@
-/**
- * Taint Analysis Policy Configuration
- *
- * Predefined and configurable taint analysis policies for different
- * analysis scenarios including malware analysis, vulnerability assessment,
- * and compliance auditing.
- */
-import type { AnalysisEngine, HybridConfig, OrchestrationStrategy, TaintConfig } from "../types/taint-tracking";
-/**
- * Policy template for different analysis scenarios
- */
-export interface TaintPolicy {
-    /** Policy identifier */
-    name: string;
-    /** Policy description */
-    description: string;
-    /** Target use case */
-    useCase: "malware" | "vulnerability" | "compliance" | "forensics" | "general";
-    /** Taint tracking configuration */
-    taintConfig: TaintConfig;
-    /** Hybrid orchestration strategy */
-    orchestrationStrategy: OrchestrationStrategy;
-    /** Additional metadata */
-    metadata: {
-        version: string;
-        author: string;
-        created: string;
-        tags: string[];
-        riskLevel: "low" | "medium" | "high" | "critical";
-    };
-}
-/**
- * Predefined taint policies for common analysis scenarios
- */
-export declare class TaintPolicyManager {
-    private policies;
-    private customRules;
-    constructor();
-    /**
-     * Get a policy by name
-     */
-    getPolicy(name: string): TaintPolicy | null;
-    /**
-     * Get all available policies
-     */
-    getAllPolicies(): TaintPolicy[];
-    /**
-     * Get policies by use case
-     */
-    getPoliciesByUseCase(useCase: TaintPolicy["useCase"]): TaintPolicy[];
-    /**
-     * Register a custom policy
-     */
-    registerPolicy(policy: TaintPolicy): void;
-    /**
-     * Create a hybrid configuration from a policy
-     */
-    createHybridConfig(policyName: string, engineOverrides?: {
-        [engine in AnalysisEngine]?: {
-            enabled: boolean;
-            config?: any;
-        };
-    }): HybridConfig;
-    /**
-     * Initialize predefined policies
-     */
-    private initializePredefinedPolicies;
-    /**
-     * Create orchestration strategies for different policies
-     */
-    private createMalwareStrategy;
-    private createVulnerabilityStrategy;
-    private createComplianceStrategy;
-    private createForensicsStrategy;
-    private createFastScreeningStrategy;
-    /**
-     * Generate custom taint propagation rules for different use cases
-     */
-    private getMalwareAnalysisRules;
-    private getVulnerabilityAssessmentRules;
-    private getComplianceAuditRules;
-    private getForensicsAnalysisRules;
-    private getFastScreeningRules;
-}

package/dist/types/hipaa-compliance.d.ts

@@ -1,110 +0,0 @@
-/**
- * HIPAA Compliance Module for Pompelmi
- *
- * This module provides comprehensive HIPAA compliance features for healthcare environments
- * where Pompelmi is used to analyze potentially compromised systems containing PHI.
- *
- * Key protections:
- * - Data sanitization and redaction
- * - Secure temporary file handling
- * - Audit logging
- * - Memory protection
- * - Error message sanitization
- */
-export interface HipaaConfig {
-    enabled: boolean;
-    auditLogPath?: string;
-    encryptTempFiles?: boolean;
-    sanitizeErrors?: boolean;
-    sanitizeFilenames?: boolean;
-    memoryProtection?: boolean;
-    requireSecureTransport?: boolean;
-}
-export interface AuditEvent {
-    timestamp: string;
-    eventType: "file_scan" | "temp_file_created" | "temp_file_deleted" | "error_occurred" | "phi_detected" | "security_violation";
-    sessionId: string;
-    userId?: string;
-    details: {
-        action: string;
-        fileHash?: string;
-        fileSizeBytes?: number;
-        success: boolean;
-        sanitizedError?: string;
-        metadata?: Record<string, unknown>;
-    };
-}
-declare class HipaaComplianceManager {
-    private config;
-    private sessionId;
-    private auditEvents;
-    constructor(config: HipaaConfig);
-    /**
-     * Sanitize filename to prevent PHI leakage in logs
-     */
-    sanitizeFilename(filename?: string): string;
-    /**
-     * Sanitize error messages to prevent PHI exposure
-     */
-    sanitizeError(error: Error | string): string;
-    /**
-     * Create secure temporary file path with encryption if enabled
-     */
-    createSecureTempPath(prefix?: string): string;
-    /**
-     * Get or create secure temporary directory with restricted permissions
-     */
-    private getSecureTempDir;
-    /**
-     * Secure file cleanup with multiple overwrite passes
-     */
-    secureFileCleanup(filePath: string): Promise<void>;
-    /**
-     * Calculate secure file hash for audit purposes
-     */
-    calculateFileHash(data: Uint8Array): string;
-    /**
-     * Log audit event
-     */
-    auditLog(eventType: AuditEvent["eventType"], details: Partial<AuditEvent["details"]>): void;
-    /**
-     * Write audit event to file
-     */
-    private writeAuditLog;
-    /**
-     * Generate cryptographically secure session ID
-     */
-    private generateSessionId;
-    /**
-     * Get current audit events for this session
-     */
-    getAuditEvents(): AuditEvent[];
-    /**
-     * Clear sensitive data from memory
-     */
-    clearSensitiveData(): void;
-    /**
-     * Validate transport security
-     */
-    validateTransportSecurity(url?: string): boolean;
-}
-/**
- * Initialize HIPAA compliance
- */
-export declare function initializeHipaaCompliance(config: HipaaConfig): HipaaComplianceManager;
-/**
- * Get current HIPAA compliance manager
- */
-export declare function getHipaaManager(): HipaaComplianceManager | null;
-/**
- * HIPAA-compliant error wrapper
- */
-export declare function createHipaaError(error: Error | string, context?: string): Error;
-/**
- * HIPAA-compliant temporary file utilities
- */
-export declare const HipaaTemp: {
-    createPath: (prefix?: string) => string;
-    cleanup: (filePath: string) => Promise<void>;
-};
-export { HipaaComplianceManager };

package/dist/types/hooks.d.ts

@@ -1,89 +0,0 @@
-/**
- * Scan lifecycle hooks for Pompelmi.
- *
- * Hooks let you observe and react to scan events without modifying the scan
- * pipeline itself.  They are the recommended integration point for:
- *   - logging / metrics collection
- *   - alerting on threats
- *   - triggering quarantine automatically
- *   - OpenTelemetry span creation
- *
- * Usage:
- * ```ts
- * import { scanBytes } from 'pompelmi';
- * import { createScanHooks, withHooks } from 'pompelmi/hooks';
- *
- * const hooks = createScanHooks({
- *   onScanComplete(ctx, report) {
- *     console.log(ctx.filename, report.verdict, report.durationMs + 'ms');
- *   },
- *   onThreatDetected(ctx, report) {
- *     alertTeam({ file: ctx.filename, verdict: report.verdict });
- *   },
- * });
- *
- * const scan = withHooks(scanBytes, hooks);
- * const report = await scan(bytes, { ctx: { filename: 'upload.zip' } });
- * ```
- *
- * @module hooks
- */
-import type { QuarantineEntry } from "./quarantine/types";
-import type { ScanContext, ScanReport } from "./types";
-export interface ScanStartContext extends ScanContext {
-    /** Unique identifier for this scan invocation (useful for correlating logs). */
-    scanId?: string;
-    /** Timestamp when the scan started (ms since epoch). */
-    startedAt: number;
-}
-export interface ScanCompleteContext extends ScanStartContext {
-    /** Duration of the scan in milliseconds. */
-    durationMs: number;
-}
-/**
- * Callbacks for the scan lifecycle.  All hooks are optional.
- *
- * Hooks MUST NOT throw — wrap logic in try/catch if it can fail.
- * Async hooks are fire-and-forget; they do not block the scan result.
- */
-export interface ScanHooks {
-    /**
-     * Called immediately before a scan begins.
-     */
-    onScanStart?: (ctx: ScanStartContext) => void | Promise<void>;
-    /**
-     * Called when a scan completes successfully (any verdict, including clean).
-     */
-    onScanComplete?: (ctx: ScanCompleteContext, report: ScanReport) => void | Promise<void>;
-    /**
-     * Called when the scan verdict is 'suspicious' or 'malicious'.
-     * Fired in addition to `onScanComplete`.
-     */
-    onThreatDetected?: (ctx: ScanCompleteContext, report: ScanReport) => void | Promise<void>;
-    /**
-     * Called when a file has been quarantined.
-     * Requires wiring with a `QuarantineManager`; not fired automatically by `scanBytes`.
-     */
-    onQuarantine?: (entry: QuarantineEntry) => void | Promise<void>;
-    /**
-     * Called when a scan throws an unexpected error.
-     */
-    onScanError?: (ctx: ScanStartContext, error: unknown) => void | Promise<void>;
-}
-/**
- * Create a `ScanHooks` object with optional defaults.
- * This is a thin factory — the value of using it is the inline TS types.
- */
-export declare function createScanHooks(hooks: ScanHooks): ScanHooks;
-type ScanFn = (bytes: Uint8Array, opts?: {
-    ctx?: ScanContext;
-    [k: string]: unknown;
-}) => Promise<ScanReport>;
-/**
- * Wrap a scan function with lifecycle hooks.
- *
- * Returns a new function with the same signature that fires the hooks
- * around each scan call.
- */
-export declare function withHooks(scanFn: ScanFn, hooks: ScanHooks): ScanFn;
-export {};

package/dist/types/index.d.ts

@@ -1,29 +0,0 @@
-/**
- * src/index.ts — Primary Node.js entry point for Pompelmi.
- *
- * This is the full API including Node.js-only modules (HIPAA compliance,
- * crypto-based caching and hashing, ZIP streaming, YARA native bindings).
- *
- * For browser-safe usage, import from 'pompelmi/browser'.
- * For React hooks, import from 'pompelmi/react'.
- */
-export { CONFIG_PRESETS, ConfigManager, createConfig, DEFAULT_CONFIG, getPresetConfig, type ScannerConfig, } from "./config";
-export { type AuditEvent, createHipaaError, getHipaaManager, type HipaaConfig, HipaaTemp, initializeHipaaCompliance, } from "./hipaa-compliance";
-export type { NodeFileEntry, NodeScanOptions } from "./node/scanDir";
-export { DEFAULT_POLICY, definePolicy } from "./policy";
-export { ARCHIVES, CONSERVATIVE_DEFAULT, DOCUMENTS_ONLY, getPolicyPack, IMAGES_ONLY, POLICY_PACKS, type PolicyPackName, STRICT_PUBLIC_UPLOAD, } from "./policy-packs";
-export { type ComposeScannerOptions, composeScanners, createPresetScanner, type NamedScanner, type PresetName, type PresetOptions, } from "./presets";
-export { type ScanOptions, scanBytes, scanFile, scanFiles } from "./scan";
-export { scanFilesWithRemoteYara } from "./scan/remote";
-export { CommonHeuristicsScanner } from "./scanners/common-heuristics";
-export { createZipBombGuard } from "./scanners/zip-bomb-guard";
-export * from "./types";
-export { analyzeNestedArchives, detectObfuscatedScripts, detectPolyglot, } from "./utils/advanced-detection";
-export { BatchScanner, type BatchScanOptions, type BatchScanResult, batchScan, type ScanTask, } from "./utils/batch-scanner";
-export { type CacheEntry, type CacheOptions, type CacheStats, getDefaultCache, resetDefaultCache, ScanCacheManager, } from "./utils/cache-manager";
-export { type ExportFormat, type ExportOptions, exportScanResults, ScanResultExporter, } from "./utils/export";
-export { aggregateScanStats, type PerformanceMetrics, PerformanceTracker, type ScanStatistics, } from "./utils/performance-metrics";
-export { createThreatIntelligence, type EnhancedScanReport, getFileHash, LocalThreatIntelligence, type ThreatInfo, ThreatIntelligenceAggregator, type ThreatIntelligenceSource, } from "./utils/threat-intelligence";
-export { validateFile } from "./validate";
-export { mapMatchesToVerdict } from "./verdict";
-export type { YaraMatch } from "./yara/index";

package/dist/types/magic.d.ts

@@ -1,7 +0,0 @@
-export type Sniff = {
-    mime: string;
-    extHint?: string;
-    confidence: number;
-};
-export declare function sniff(bytes: Uint8Array): Sniff | null;
-export declare function hasSuspiciousJpegTrailer(bytes: Uint8Array, maxTrailer?: number): boolean;

package/dist/types/node/scanDir.d.ts

@@ -1,30 +0,0 @@
-import type { YaraMatch } from "../yara/index";
-export interface NodeScanOptions {
-    enableYara?: boolean;
-    yaraRules?: string;
-    yaraRulesPath?: string;
-    includeExtensions?: string[];
-    yaraAsync?: boolean;
-    maxFileSizeBytes?: number;
-    yaraSampleBytes?: number;
-    yaraPreferBuffer?: boolean;
-}
-export type NodeYaraVerdict = "malicious" | "suspicious" | "clean";
-export interface NodeYaraResult {
-    matches: YaraMatch[];
-    status: "scanned" | "skipped" | "error";
-    /** per i 'skipped', perché abbiamo saltato */
-    reason?: "max-size" | "filtered-ext" | "not-enabled" | "engine-missing" | "error";
-    /** come abbiamo scansionato quando status = 'scanned' */
-    mode?: "async" | "file" | "buffer" | "buffer-sampled";
-    /** verdetto derivato dai match (solo quando status='scanned') */
-    verdict?: NodeYaraVerdict;
-}
-export interface NodeFileEntry {
-    path: string;
-    absPath: string;
-    isDir: boolean;
-    yara?: NodeYaraResult;
-}
-/** Scansiona una directory in modo ricorsivo, emettendo le entry e (opzionale) i match YARA. */
-export declare function scanDir(root: string, opts?: NodeScanOptions): AsyncGenerator<NodeFileEntry>;

package/dist/types/policy-packs.d.ts

@@ -1,98 +0,0 @@
-/**
- * Policy packs for Pompelmi.
- *
- * Pre-configured, named policies for common upload scenarios.  Each pack
- * defines the file type allowlist, size limits, and timeout appropriate for
- * its use case.
- *
- * All packs are built on `definePolicy` and are fully overridable:
- *
- * ```ts
- * import { POLICY_PACKS } from 'pompelmi/policy-packs';
- *
- * // Use a pack as-is:
- * const policy = POLICY_PACKS['images-only'];
- *
- * // Or override individual fields:
- * import { definePolicy } from 'pompelmi';
- * const custom = definePolicy({ ...POLICY_PACKS['documents-only'], maxFileSizeBytes: 5 * 1024 * 1024 });
- * ```
- *
- * These packs are *deterministic* and *descriptor-based* — they do not
- * depend on any external threat intelligence feed.
- *
- * @module policy-packs
- */
-import { type Policy } from "./policy";
-/**
- * Documents-only policy.
- *
- * Appropriate for: document management APIs, PDF/Office file upload endpoints,
- * data import pipelines.
- *
- * Allowed: PDF, Word (.docx/.doc), Excel (.xlsx/.xls), PowerPoint (.pptx/.ppt),
- *   CSV, plain text, JSON, YAML, ODT/ODS/ODP (OpenDocument).
- * Max size: 25 MB.
- */
-export declare const DOCUMENTS_ONLY: Policy;
-/**
- * Images-only policy.
- *
- * Appropriate for: avatar uploads, product image APIs, content platforms with
- * user-generated imagery.
- *
- * Allowed: JPEG, PNG, GIF, WebP, AVIF, TIFF, BMP, ICO.
- * Max size: 10 MB.
- * Note: SVG is intentionally excluded — inline SVGs can contain scripts.
- */
-export declare const IMAGES_ONLY: Policy;
-/**
- * Strict public-upload policy.
- *
- * Appropriate for: anonymous or low-trust upload endpoints, public APIs,
- * any surface exposed to untrusted users.
- *
- * Aggressive size limit (5 MB), short timeout, fail-closed, narrow MIME
- * allowlist.  Only allows plain images and PDF.
- */
-export declare const STRICT_PUBLIC_UPLOAD: Policy;
-/**
- * Conservative default policy.
- *
- * A hardened version of the built-in `DEFAULT_POLICY` suitable for
- * production without further customisation.  Stricter size limit and
- * shorter timeout than the permissive default.
- */
-export declare const CONSERVATIVE_DEFAULT: Policy;
-/**
- * Archives policy.
- *
- * Appropriate for: endpoints that accept ZIP, tar, or compressed archives.
- * Combines a generous size allowance with a longer timeout for deep inspection.
- *
- * NOTE: Pair this policy with `createZipBombGuard()` to defend against
- * decompression-bomb attacks:
- *
- * ```ts
- * import { composeScanners, createZipBombGuard, CommonHeuristicsScanner } from 'pompelmi';
- * const scanner = composeScanners(
- *   [['zipGuard', createZipBombGuard()], ['heuristics', CommonHeuristicsScanner]]
- * );
- * ```
- */
-export declare const ARCHIVES: Policy;
-export type PolicyPackName = "documents-only" | "images-only" | "strict-public-upload" | "conservative-default" | "archives";
-/**
- * Named map of all built-in policy packs.
- *
- * ```ts
- * import { POLICY_PACKS } from 'pompelmi/policy-packs';
- * const policy = POLICY_PACKS['strict-public-upload'];
- * ```
- */
-export declare const POLICY_PACKS: Record<PolicyPackName, Policy>;
-/**
- * Look up a policy pack by name.
- * Throws if the name is not recognised.
- */
-export declare function getPolicyPack(name: PolicyPackName): Policy;

package/dist/types/policy.d.ts

@@ -1,12 +0,0 @@
-export interface Policy {
-    includeExtensions: string[];
-    allowedMimeTypes: string[];
-    maxFileSizeBytes: number;
-    timeoutMs: number;
-    concurrency: number;
-    failClosed: boolean;
-    onScanEvent?: (ev: unknown) => void;
-}
-export type PolicyInput = Partial<Policy>;
-export declare const DEFAULT_POLICY: Policy;
-export declare function definePolicy(input?: PolicyInput): Policy;