index.d.ts

/* 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
  /** Sets the match context size. */
  setMatchContextSize(size: 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
   *
   * # Performance Note
   *
   * This method recompiles all rules (existing + new) on each call, resulting
   * in O(n) time per call and O(n²) total for n incremental additions.
   * For better performance with many rules, use `compile()` with all sources
   * at once, or use `add_rule_sources()` for batch addition.
   */
  addRuleSource(ruleSource: string, namespace?: string | undefined | null): void
  /**
   * Adds multiple rule sources to the YARA compiler in a single compilation pass.
   *
   * This is more efficient than calling `add_rule_source()` multiple times,
   * as it compiles all sources in a single pass instead of recompiling
   * existing rules for each addition.
   *
   * # Arguments
   *
   * * `rule_sources` - Vector of rule sources to add
   *
   * # Returns
   *
   * Ok(()) on success, or an error if compilation fails
   *
   * # Performance
   *
   * O(n + m) where n = existing rules, m = new rules (single compilation pass).
   * Compared to calling `add_rule_source()` m times: O(n × m + m²).
   */
  addRuleSources(ruleSources: Array<RuleSource>): 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
  /**
   * Maximum number of warnings the compiler will report.
   *
   * When set, only the first `n` warnings are emitted; additional warnings
   * are dropped. Useful for taming noisy rule corpora, particularly when
   * the compiler warns on single-byte patterns and duplicate pattern values.
   */
  maxWarnings?: number
  /**
   * Warning codes to disable during compilation.
   *
   * Each entry must be a valid YARA-X warning code (e.g. `"slow_pattern"`,
   * `"duplicate_pattern_value"`, `"potentially_slow_loop"`). An invalid
   * code produces a compilation error.
   */
  disableWarnings?: Array<string>
  /**
   * Whether to enable or disable all compiler warnings.
   *
   * `true` (the default) leaves all warning types enabled. `false` silences
   * every warning. Individual codes in `disable_warnings` are applied after
   * this flag, so an explicitly disabled code stays off even when this is
   * `true`.
   */
  enableAllWarnings?: 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
  /** The context around the matched data, if match_context_size is set. */
  contextData?: string
  /** The start offset of the actual match within the context data. */
  contextMatchOffset?: number
}

/**
 * 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>
}

/** A YARA rule source and the namespace it belongs to. */
export interface RuleSource {
  /** The YARA rule source code. */
  source: string
  /** The namespace for the source. `None` means the default namespace. */
  namespace?: string
}

/**
 * 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
  /** Optional number of bytes to include before and after the match. */
  matchContextSize?: 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