@litko/yara-x/index.d.ts

- High Performance: Built with [napi-rs](https://napi-rs.com) and [VirusTotal/yara-x](https://github.com/VirusTotal/yara-x) - Async Support: First-class support for asynchronous scanning - WASM Compilation: Compile rules to WebAssembly for portable execut

/* auto-generated by NAPI-RS */
/* eslint-disable */
/**
 * The main YARA-X scanner struct.
 *
 * This struct represents compiled YARA rules and provides methods for scanning
 * data and files. It includes performance optimizations like scanner caching.
 */
export declare class YaraX {
  /** Returns the compiler warnings generated during the compilation process. */
  getWarnings(): Array<CompilerWarning>
  /**
   * Sets the maximum number of matches per pattern.
   *
   * # Arguments
   *
   * * `max_matches` - The maximum number of matches per pattern
   */
  setMaxMatchesPerPattern(maxMatches: number): void
  /**
   * Sets whether to use memory-mapped files for scanning.
   *
   * # Arguments
   *
   * * `use_mmap` - Whether to use memory-mapped files
   */
  setUseMmap(useMmap: boolean): void
  /** Sets the scan timeout in milliseconds. */
  setTimeout(timeoutMs: number): void
  /**
   * Scans the provided data using the compiled YARA rules.
   *
   * # Arguments
   *
   * * `env` - The N-API environment
   * * `data` - The data to scan
   * * `variables` - Optional variables to set for this scan
   *
   * # Returns
   *
   * A vector of matching rules
   */
  scan(data: Buffer, variables?: Record<string, string | number | boolean>): Array<RuleMatch>
  /**
   * Scans a file using the compiled YARA rules.
   *
   * # Arguments
   *
   * * `env` - The N-API environment
   * * `file_path` - Path to the file to scan
   * * `variables` - Optional variables to set for this scan
   *
   * # Returns
   *
   * A vector of matching rules
   */
  scanFile(filePath: string, variables?: Record<string, string | number | boolean>): Array<RuleMatch>
  /**
   * Emits a WASM file from the compiled YARA rules.
   *
   * # Arguments
   *
   * * `output_path` - Path where the WASM file should be written
   *
   * # Returns
   *
   * Ok(()) on success, or an error if emission fails
   */
  emitWasmFile(outputPath: string): void
  /**
   * Scans the provided data asynchronously using the compiled YARA rules.
   *
   * # Arguments
   *
   * * `data` - The data to scan
   * * `variables` - Optional variables to set for this scan
   *
   * # Returns
   *
   * An async task that resolves to a vector of matching rules
   */
  scanAsync(data: Buffer, variables?: object | undefined | null): Promise<Array<RuleMatch>>
  /**
   * Scans a file asynchronously using the compiled YARA rules.
   *
   * # Arguments
   *
   * * `file_path` - Path to the file to scan
   * * `variables` - Optional variables to set for this scan
   *
   * # Returns
   *
   * An async task that resolves to a vector of matching rules
   */
  scanFileAsync(filePath: string, variables?: object | undefined | null): Promise<Array<RuleMatch>>
  /**
   * Emits a WASM file asynchronously from the compiled YARA rules.
   *
   * # Arguments
   *
   * * `output_path` - Path where the WASM file should be written
   *
   * # Returns
   *
   * An async task that completes when the WASM file is written
   */
  emitWasmFileAsync(outputPath: string): Promise<unknown>
  /**
   * Adds a rule source to the YARA compiler.
   *
   * # Arguments
   *
   * * `rule_source` - The YARA rule source code to add
   *
   * # Returns
   *
   * Ok(()) on success, or an error if compilation fails
   */
  addRuleSource(ruleSource: string, namespace?: string | undefined | null): void
  /**
   * Adds a rule file to the YARA compiler.
   *
   * # Arguments
   *
   * * `file_path` - Path to the file containing YARA rules
   *
   * # Returns
   *
   * Ok(()) on success, or an error if reading or compilation fails
   */
  addRuleFile(filePath: string, namespace?: string | undefined | null): void
  /**
   * Defines a variable for the YARA compiler.
   *
   * # Arguments
   *
   * * `name` - The variable name
   * * `value` - The variable value
   *
   * # Returns
   *
   * Ok(()) on success, or an error if compilation fails
   */
  defineVariable(name: string, value: string): void
}

/**
 * Represents a module that is banned from being used in YARA rules.
 *
 * When a banned module is encountered, compilation will fail with the
 * specified error message.
 */
export interface BannedModule {
  /** The name of the banned module. */
  name: string
  /** The title of the error message if the module is used. */
  errorTitle: string
  /** The error message if the module is used. */
  errorMessage: string
}

/**
 * Compiles a YARA rule source string and returns a YaraX instance with the compiled rules.
 *
 * # Arguments
 *
 * * `rule_source` - The YARA rule source code
 * * `options` - Optional compiler options
 *
 * # Returns
 *
 * A YaraX instance with compiled rules
 */
export declare function compile(ruleSource: string, options?: CompilerOptionsType | undefined | null): YaraXImpl

/**
 * Compiles a YARA rule file to a WASM file.
 *
 * # Arguments
 *
 * * `rule_path` - Path to the file containing YARA rules
 * * `output_path` - Path where the WASM file should be written
 * * `options` - Optional compiler options
 *
 * # Returns
 *
 * Ok(()) on success, or an error if reading, compilation, or emission fails
 */
export declare function compileFileToWasm(rulePath: string, outputPath: string, options?: CompilerOptionsType | undefined | null): void

/**
 * An error generated by the YARA compiler.
 *
 * Errors prevent successful compilation and must be resolved before
 * the rules can be used.
 */
export interface CompilerError {
  /** The code of the error. */
  code: string
  /** The message of the error. */
  message: string
  /** The source of the error, if available. */
  source?: string
  /** The line number where the error occurred, if available. */
  line?: number
  /** The column number where the error occurred, if available. */
  column?: number
}

/**
 * The result of compiling YARA rules.
 *
 * Contains any warnings or errors generated during the compilation process.
 * If errors are present, the compilation failed.
 */
export interface CompileResult {
  /** Any warnings generated during the compilation process. */
  warnings: Array<CompilerWarning>
  /** Any errors generated during the compilation process. */
  errors: Array<CompilerError>
}

/**
 * Options for configuring the YARA compiler.
 *
 * These options control various aspects of rule compilation including
 * module handling, optimization, and feature flags.
 */
export interface CompilerOptions {
  /** The namespace where the YARA rules should be compiled. */
  namespace?: string
  /** Defines global variables for the YARA rules. */
  defineVariables?: object
  /** A list of module names to ignore during compilation. */
  ignoreModules?: Array<string>
  /** A list of banned modules that cannot be used in the YARA rules. */
  bannedModules?: Array<BannedModule>
  /** A list of features to enable for the YARA rules. */
  features?: Array<string>
  /** Whether to use relaxed regular expression syntax. */
  relaxedReSyntax?: boolean
  /** Whether to optimize conditions in the YARA rules. */
  conditionOptimization?: boolean
  /** Whether to raise an error on slow patterns. */
  errorOnSlowPattern?: boolean
  /** Whether to raise an error on slow loops. */
  errorOnSlowLoop?: boolean
  /** A list of directories where the compiler should look for included files. */
  includeDirectories?: Array<string>
  /** Whether to enable include statements in YARA rules. */
  enableIncludes?: boolean
}

/**
 * A warning generated by the YARA compiler.
 *
 * Warnings indicate potential issues that don't prevent compilation
 * but may indicate problems with the rules.
 */
export interface CompilerWarning {
  /** The code of the warning. */
  code: string
  /** The message of the warning. */
  message: string
  /** The source of the warning, if available. */
  source?: string
  /** The line number where the warning occurred, if available. */
  line?: number
  /** The column number where the warning occurred, if available. */
  column?: number
}

/**
 * Compiles a YARA rule source string to a WASM file.
 *
 * # Arguments
 *
 * * `rule_source` - The YARA rule source code
 * * `output_path` - Path where the WASM file should be written
 * * `options` - Optional compiler options
 *
 * # Returns
 *
 * Ok(()) on success, or an error if compilation or emission fails
 */
export declare function compileToWasm(ruleSource: string, outputPath: string, options?: CompilerOptionsType | undefined | null): void

/**
 * Creates a new YaraX instance with empty rules and no source code.
 *
 * # Returns
 *
 * A new YaraX instance with empty rules
 */
export declare function create(): YaraXImpl

/**
 * Creates a new YaraX instance from a file containing YARA rules.
 *
 * # Arguments
 *
 * * `rule_path` - Path to the file containing YARA rules
 * * `options` - Optional compiler options
 *
 * # Returns
 *
 * A YaraX instance with compiled rules from the file
 */
export declare function fromFile(rulePath: string, options?: CompilerOptionsType | undefined | null): YaraXImpl

/**
 * Represents a match found by a YARA rule pattern.
 *
 * Contains information about where the match occurred and what data was matched.
 */
export interface MatchData {
  /** The offset of the match in the scanned data. */
  offset: number
  /** The length of the matched data. */
  length: number
  /** The matched data as a string. */
  data: string
  /** The identifier of the pattern that matched. */
  identifier: string
}

/**
 * Represents a matching rule found during scanning.
 *
 * Contains the rule's metadata, tags, and all pattern matches.
 */
export interface RuleMatch {
  /** The identifier of the rule that matched. */
  ruleIdentifier: string
  /** The namespace of the rule that matched. */
  namespace: string
  /** The metadata associated with the rule that matched. */
  meta: object
  /** The tags associated with the rule that matched. */
  tags: Array<string>
  /** The matches found by the rule. */
  matches: Array<MatchData>
}

/**
 * Options for configuring scanning operations.
 *
 * These options control resource usage and performance characteristics
 * during rule scanning.
 */
export interface ScanOptions {
  /** Maximum number of matches per pattern. When a pattern reaches this limit, it won't produce more matches. */
  maxMatchesPerPattern?: number
  /** Whether to use memory-mapped files for scanning. Disabling this is safer but slower. */
  useMmap?: boolean
  /** Scan timeout in milliseconds. */
  timeoutMs?: number
}

/**
 * Compiles a YARA rule source string and returns any warnings or errors generated during the
 * compilation process.
 *
 * This function validates YARA rules without creating a scanner instance.
 *
 * # Arguments
 *
 * * `rule_source` - The YARA rule source code
 * * `options` - Optional compiler options
 *
 * # Returns
 *
 * A CompileResult containing any warnings and errors
 */
export declare function validate(ruleSource: string, options?: CompilerOptionsType | undefined | null): CompileResult