libmagic_rs/evaluator/engine/mod.rs
1// Copyright (c) 2025-2026 the libmagic-rs contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Core evaluation engine for magic rules.
5//!
6//! This module contains the core recursive evaluation logic for executing magic
7//! rules against file buffers. It is responsible for:
8//! - Evaluating a single rule via [`evaluate_single_rule`] (a thin wrapper
9//! around `evaluate_rules` that delegates one rule through the full
10//! context-aware pipeline)
11//! - Evaluating hierarchical rule sets with context (`evaluate_rules`)
12//! - Providing a convenience wrapper for evaluation with configuration
13//! (`evaluate_rules_with_config`)
14
15use crate::parser::ast::{MagicRule, MetaType, TypeKind};
16use crate::{EvaluationConfig, LibmagicError};
17
18use super::{EvaluationContext, RecursionGuard, RuleMatch, offset, operators, types};
19use log::{debug, warn};
20// Gated to debug builds: after the engine module split, mod.rs's only atomic
21// user is the `#[cfg(debug_assertions)]` INDIRECT_WITHOUT_RULE_ENV_WARNED guard
22// below. In release builds that item is compiled out, so an ungated import is
23// unused and the workspace `warnings = "deny"` lint rejects it.
24#[cfg(debug_assertions)]
25use std::sync::atomic::{AtomicBool, Ordering};
26
27mod output;
28mod pattern_recovery;
29mod subroutine;
30mod value_eval;
31
32pub(crate) use output::*;
33pub(crate) use pattern_recovery::*;
34pub(crate) use subroutine::*;
35pub(crate) use value_eval::*;
36
37/// RAII guard that saves the GNU `file` previous-match anchor **and**
38/// `base_offset` on entry and restores both on drop.
39///
40/// `MetaType::Indirect` re-evaluates the root rule list at the resolved
41/// offset. The re-entered rules are top-level-semantic (`base_offset=0`)
42/// and must start with a fresh anchor (the resolved indirect offset).
43/// When `indirect` fires inside a `MetaType::Use` subroutine, the outer
44/// subroutine's non-zero `base_offset` would otherwise leak into the
45/// root re-entry, causing every positive absolute offset in the re-entered
46/// database to be biased by the outer use-site -- producing reads at the
47/// wrong positions. Saving and restoring `base_offset` here prevents that.
48///
49/// Without an RAII wrapper, every early-return path inside the indirect
50/// branch would have to remember to restore both fields manually.
51struct AnchorScope<'a> {
52 context: &'a mut EvaluationContext,
53 saved_anchor: usize,
54 saved_base: usize,
55}
56
57impl<'a> AnchorScope<'a> {
58 /// Save the current anchor and `base_offset`, then seed the context
59 /// with `new_anchor` and reset `base_offset` to 0.
60 fn enter(context: &'a mut EvaluationContext, new_anchor: usize) -> Self {
61 let saved_anchor = context.last_match_end();
62 let saved_base = context.base_offset();
63 context.set_last_match_end(new_anchor);
64 context.set_base_offset(0);
65 Self {
66 context,
67 saved_anchor,
68 saved_base,
69 }
70 }
71
72 /// Access the underlying context for the duration of the guard.
73 fn context(&mut self) -> &mut EvaluationContext {
74 self.context
75 }
76}
77
78impl Drop for AnchorScope<'_> {
79 fn drop(&mut self) {
80 self.context.set_last_match_end(self.saved_anchor);
81 self.context.set_base_offset(self.saved_base);
82 }
83}
84
85/// Process-local once guard for the "`evaluate_rules_with_config` called
86/// with an `indirect` rule but without a `RuleEnvironment`" warning.
87/// Same rationale as `USE_WITHOUT_RULE_ENV_WARNED`: surface the
88/// misconfiguration exactly once per process so a large corpus of
89/// env-less `indirect` rules does not flood the log.
90// Gated to debug builds like its only use site (the diagnostic guard in
91// `evaluate_rules_with_config`); in release builds the item would be dead
92// code, which the workspace `warnings = "deny"` lint rejects.
93#[cfg(debug_assertions)]
94static INDIRECT_WITHOUT_RULE_ENV_WARNED: AtomicBool = AtomicBool::new(false);
95
96/// Evaluate a single magic rule against a file buffer
97///
98/// This is a thin wrapper around [`evaluate_rules`] that evaluates exactly
99/// one top-level rule (and any of its children) against a buffer, using the
100/// caller-provided [`EvaluationContext`] to enforce timeout, recursion, and
101/// string-size limits. It is a BREAKING API change introduced in pre-1.0:
102/// earlier versions took no context and returned `Option<(usize, Value)>`.
103///
104/// # Arguments
105///
106/// * `rule` - The magic rule to evaluate
107/// * `buffer` - The file buffer to evaluate against
108/// * `context` - Mutable evaluation context that carries the configured
109/// safety limits (timeout, max recursion depth, max string length) and
110/// the GNU `file` previous-match anchor used for relative-offset
111/// resolution. Callers reusing a context across multiple buffers must
112/// call [`EvaluationContext::reset`](crate::evaluator::EvaluationContext::reset)
113/// between calls -- see [`evaluate_rules`] for details.
114///
115/// # Returns
116///
117/// Returns `Ok(Vec<RuleMatch>)` containing the parent match (if the rule
118/// matched) plus any child matches collected recursively. An empty vector
119/// means the rule did not match or was skipped due to a data-dependent
120/// evaluation error (buffer overrun, invalid offset, etc.). Only critical
121/// failures such as `LibmagicError::Timeout` or recursion-limit exhaustion
122/// are returned as `Err`.
123///
124/// # Examples
125///
126/// ```rust
127/// use libmagic_rs::evaluator::{evaluate_single_rule, EvaluationContext};
128/// use libmagic_rs::EvaluationConfig;
129/// use libmagic_rs::parser::ast::{MagicRule, OffsetSpec, TypeKind, Operator, Value};
130///
131/// // Create a rule to check for ELF magic bytes at offset 0
132/// let rule = MagicRule::new(OffsetSpec::Absolute(0), TypeKind::Byte { signed: true }, Operator::Equal, Value::Uint(0x7f), "ELF magic".to_string());
133///
134/// let mut context = EvaluationContext::new(EvaluationConfig::default());
135/// let elf_buffer = &[0x7f, 0x45, 0x4c, 0x46]; // ELF magic bytes
136/// let matches = evaluate_single_rule(&rule, elf_buffer, &mut context).unwrap();
137/// assert_eq!(matches.len(), 1); // Should match
138///
139/// context.reset();
140/// let non_elf_buffer = &[0x50, 0x4b, 0x03, 0x04]; // ZIP magic bytes
141/// let matches = evaluate_single_rule(&rule, non_elf_buffer, &mut context).unwrap();
142/// assert!(matches.is_empty()); // Should not match
143/// ```
144///
145/// # Errors
146///
147/// * `LibmagicError::Timeout` - If evaluation exceeds the configured timeout
148/// * `LibmagicError::EvaluationError` - For critical failures such as the
149/// recursion limit being exceeded. Data-dependent errors (buffer overrun,
150/// invalid offset, malformed pstring length) are handled gracefully by
151/// [`evaluate_rules`] and surface as an empty match vector rather than
152/// an error.
153pub fn evaluate_single_rule(
154 rule: &MagicRule,
155 buffer: &[u8],
156 context: &mut EvaluationContext,
157) -> Result<Vec<RuleMatch>, LibmagicError> {
158 evaluate_rules(std::slice::from_ref(rule), buffer, context)
159}
160
161/// Internal: evaluate a single rule against a buffer, supplying an explicit
162/// anchor for relative-offset resolution.
163///
164/// This is the worker behind both [`evaluate_single_rule`] (which defaults
165/// the anchor to 0) and [`evaluate_rules`] (which threads the anchor from
166/// `EvaluationContext::last_match_end()`).
167fn evaluate_single_rule_with_anchor(
168 rule: &MagicRule,
169 buffer: &[u8],
170 last_match_end: usize,
171 base_offset: usize,
172 max_string_length: usize,
173 flip_endian: bool,
174) -> Result<Option<(usize, crate::parser::ast::Value)>, LibmagicError> {
175 use crate::parser::ast::TypeKind;
176
177 // Step 1: Resolve the offset specification to an absolute position.
178 // `base_offset` is non-zero only inside a `MetaType::Use` subroutine
179 // body, where it biases positive absolute offsets to the use-site.
180 let absolute_offset =
181 offset::resolve_offset_with_base(&rule.offset, buffer, last_match_end, base_offset)?;
182
183 // Step 2 & 3: Dispatch on type category. Pattern-bearing types
184 // (Regex, Search) take a different path from fixed-width types
185 // because the rule's `value` operand is the *pattern*, not an
186 // expected matched value. Running those through `apply_operator`
187 // would compare matched text ("123") against the pattern literal
188 // ("[0-9]+") and produce false negatives on any regex with
189 // metacharacters.
190 //
191 // Meta-type directives (`default`, `clear`, `name`, `use`,
192 // `indirect`, `offset`) are dispatched by `evaluate_rules` at the
193 // outer loop level (not here) -- this single-rule helper is only
194 // invoked for non-meta rules. Short-circuiting the Meta arms here
195 // with `Ok(None)` is defense-in-depth for programmatic callers
196 // (property tests, fuzz harnesses) that hand-build a Meta rule
197 // and feed it directly to `evaluate_single_rule`; without the
198 // guard, the value/pattern paths would surface
199 // `TypeReadError::UnsupportedType`.
200 let (matched, read_value) = match &rule.typ {
201 TypeKind::Meta(MetaType::Name(name)) => {
202 // `Name` rules are normally hoisted into the name table at
203 // parse time and should not reach the evaluator. Programmatic
204 // consumers (e.g. fuzz harnesses, property tests) can still
205 // construct them directly; treat that as a no-op rather than
206 // a hard failure so the evaluator-never-panics invariant is
207 // preserved.
208 debug!(
209 "Name rule '{name}' reached evaluator (likely bypassed name-table extraction); treating as no-op"
210 );
211 return Ok(None);
212 }
213 TypeKind::Meta(MetaType::Use { .. }) => {
214 // `Use` is dispatched inline by `evaluate_rules` so it can
215 // push the subroutine's matches into the caller's match
216 // vector. Reaching this arm means the rule went through the
217 // single-rule path (e.g. via `evaluate_single_rule`) which
218 // lacks that wiring; treat it as a silent no-op.
219 return Ok(None);
220 }
221 TypeKind::Meta(_) => return Ok(None),
222 TypeKind::Regex { .. } | TypeKind::Search { .. } => {
223 evaluate_pattern_rule(rule, buffer, absolute_offset, max_string_length)?
224 }
225 // Flagged `string` rules route through the pattern-bearing path
226 // (see GOTCHAS S2.4 for the contract) so `compare_string_with_flags`
227 // can do the case-fold / whitespace-flexible match in one pass --
228 // but ONLY for the equality operators the pattern path supports.
229 // An ORDERING operator on a flagged string (e.g. the ubiquitous
230 // `string/t >\0` / `string/b >\0` "non-empty text here, print it with
231 // %s" idiom in `varied.script`, `sgml`, `linux`, ...) is a
232 // lexicographic comparison, not a pattern match; routing it to the
233 // pattern path made it a fatal `UnsupportedType` abort that killed the
234 // whole file's evaluation. The `/t`/`/b` flags are MIME-output hints
235 // with no comparison effect, so such a rule behaves like an unflagged
236 // `string >VALUE` and belongs on the value path. Default-flag strings
237 // (the common case) also take that value-rule fast path.
238 TypeKind::String { flags, .. }
239 if !flags.is_empty()
240 && matches!(
241 rule.op,
242 crate::parser::ast::Operator::Equal | crate::parser::ast::Operator::NotEqual
243 ) =>
244 {
245 evaluate_pattern_rule(rule, buffer, absolute_offset, max_string_length)?
246 }
247 _ => evaluate_value_rule(
248 rule,
249 buffer,
250 absolute_offset,
251 max_string_length,
252 flip_endian,
253 )?,
254 };
255 Ok(matched.then_some((absolute_offset, read_value)))
256}
257
258/// Evaluate a list of magic rules against a file buffer with hierarchical processing
259///
260/// This function implements the core hierarchical rule evaluation algorithm with graceful
261/// error handling:
262/// 1. Evaluates each top-level rule in sequence
263/// 2. If a parent rule matches, evaluates its child rules for refinement
264/// 3. Collects all matches or stops at first match based on configuration
265/// 4. Maintains evaluation context for recursion limits and state
266/// 5. Implements graceful degradation by skipping problematic rules and continuing evaluation
267///
268/// The hierarchical evaluation follows these principles:
269/// - Parent rules must match before children are evaluated
270/// - Child rules provide refinement and additional detail
271/// - Evaluation can stop at first match or continue for all matches
272/// - Recursion depth is limited to prevent infinite loops
273/// - Problematic rules are skipped to allow evaluation to continue
274///
275/// # Arguments
276///
277/// * `rules` - The list of magic rules to evaluate
278/// * `buffer` - The file buffer to evaluate against
279/// * `context` - Mutable evaluation context for state management. **Callers
280/// reusing a context across multiple buffers must call
281/// [`EvaluationContext::reset`](crate::evaluator::EvaluationContext::reset)
282/// between calls** -- the GNU `file` previous-match anchor and the
283/// recursion-depth counter both advance during evaluation and would
284/// otherwise leak across buffers. The same applies when this function
285/// returns `Err` mid-evaluation (e.g., `LibmagicError::Timeout` or
286/// `RecursionLimitExceeded`): both the anchor and (potentially) the
287/// recursion depth are left in a partially-advanced state, and a retry
288/// on the same context without `reset()` will resolve relative offsets
289/// against the stale anchor and apply the wrong recursion budget.
290/// [`evaluate_rules_with_config`] always builds a fresh context and is the
291/// safer choice when context reuse isn't required.
292///
293/// # Returns
294///
295/// Returns `Ok(Vec<RuleMatch>)` containing all matches found. Errors in individual rules
296/// are skipped to allow evaluation to continue. Only returns `Err(LibmagicError)`
297/// for critical failures like timeout or recursion limit exceeded.
298///
299/// # Examples
300///
301/// ```rust
302/// use libmagic_rs::evaluator::{evaluate_rules, EvaluationContext, RuleMatch};
303/// use libmagic_rs::parser::ast::{MagicRule, OffsetSpec, TypeKind, Operator, Value};
304/// use libmagic_rs::EvaluationConfig;
305///
306/// // Create a hierarchical rule set for ELF files
307/// let parent_rule = MagicRule::new(
308/// OffsetSpec::Absolute(0),
309/// TypeKind::Byte { signed: true },
310/// Operator::Equal,
311/// Value::Uint(0x7f),
312/// "ELF".to_string(),
313/// )
314/// .with_children(vec![
315/// MagicRule::new(
316/// OffsetSpec::Absolute(4),
317/// TypeKind::Byte { signed: true },
318/// Operator::Equal,
319/// Value::Uint(2),
320/// "64-bit".to_string(),
321/// )
322/// .with_level(1),
323/// ]);
324///
325/// let rules = vec![parent_rule];
326/// let buffer = &[0x7f, 0x45, 0x4c, 0x46, 0x02, 0x01]; // ELF64 header
327/// let config = EvaluationConfig::default();
328/// let mut context = EvaluationContext::new(config);
329///
330/// let matches = evaluate_rules(&rules, buffer, &mut context).unwrap();
331/// assert_eq!(matches.len(), 2); // Parent and child should both match
332/// ```
333///
334/// # Errors
335///
336/// * `LibmagicError::Timeout` - If evaluation exceeds configured timeout
337/// * `LibmagicError::EvaluationError` - Only for critical failures like recursion limit exceeded
338///
339/// Individual rule evaluation errors are handled gracefully and do not stop the overall evaluation.
340#[allow(clippy::too_many_lines)]
341pub fn evaluate_rules(
342 rules: &[MagicRule],
343 buffer: &[u8],
344 context: &mut EvaluationContext,
345) -> Result<Vec<RuleMatch>, LibmagicError> {
346 let mut matches = Vec::with_capacity(8);
347 let start_time = std::time::Instant::now();
348 let mut rule_count = 0u32;
349
350 // Per-level "did any sibling match yet?" flag for `default`/`clear`
351 // dispatch. Each recursive descent gets its own fresh flag, so child
352 // sibling chains track their own state independently of the parent.
353 let mut sibling_matched = false;
354
355 // Per-level entry anchor: captured at the start of this sibling list's
356 // evaluation. For CHILD sibling lists (recursion_depth > 0), the
357 // GNU `file`/libmagic previous-match anchor is reset to this value
358 // between sibling iterations so that `&N` offsets on continuation
359 // siblings resolve against the parent-level anchor, not against
360 // whatever the *previous sibling* left the anchor at. This matches
361 // libmagic's continuation-level model (`ms->c.li[cont_level]`)
362 // where each level tracks its own anchor; a sibling at level L does
363 // not inherit the post-match anchor of another sibling at level L.
364 //
365 // TOP-LEVEL siblings (recursion_depth == 0) are independent
366 // classification attempts -- each top-level rule intentionally sees
367 // the anchor advance that prior top-level rules produced (see
368 // GOTCHAS S3.8 and the `relative_anchor_can_decrease_...`
369 // integration test). Gate the reset on recursion_depth to preserve
370 // that documented discipline while still fixing the continuation-
371 // sibling behavior that the GNU `file` `searchbug.magic` fixture
372 // relies on.
373 //
374 // Recursing into a matched rule's children still carries forward the
375 // post-match anchor (via the current value of `last_match_end()` at
376 // the point of recursion), so child sibling lists see their parent's
377 // resolved position as their own entry anchor.
378 //
379 // INDIRECT RE-ENTRY exception: `MetaType::Indirect` dispatches its
380 // sub-evaluation via `RecursionGuard::enter` (to bound the recursion
381 // cycle), which forces `recursion_depth > 0`. But an indirect
382 // re-entry semantically evaluates the root rule list with TOP-LEVEL
383 // sibling semantics -- each rule is an independent classification
384 // attempt against the re-entered sub-buffer, NOT a continuation
385 // list. The indirect dispatch sets `context.set_indirect_reentry(true)`
386 // just before this call; `take_indirect_reentry()` consumes it at
387 // entry so only this iteration treats siblings as top-level.
388 // Children of matched rules inside the re-entry still see the flag
389 // as false (consumed) and correctly fall back to continuation
390 // semantics via `recursion_depth > 0`.
391 let entry_anchor = context.last_match_end();
392 let is_indirect_reentry = context.take_indirect_reentry();
393 let is_child_sibling_list = context.recursion_depth() > 0 && !is_indirect_reentry;
394
395 // `stop_at_first_match` is a TOP-LEVEL classification concept (see the
396 // `EvaluationConfig::stop_at_first_match` doc): once an outermost rule --
397 // or an indirect re-entry, which is itself a fresh top-level
398 // classification -- produces a message-bearing match, we stop trying
399 // other top-level candidates. It must NOT short-circuit a child /
400 // continuation sibling list or a `use` subroutine body: every matching
401 // sibling there contributes a detail fragment to the description (e.g.
402 // gzip's "max compression", "from Unix", "original size modulo 2^32 N"),
403 // and truncating them silently drops multi-part descriptions. This
404 // mirrors libmagic, where continuation levels always evaluate every
405 // sibling and only the top-level `match()` loop stops at first success.
406 // (An earlier revision applied the break at every recursion level, which
407 // violated the documented top-level-only contract and truncated gzip's
408 // trailing detail after its first message-bearing child.)
409 let stop_at_first_match_applies = !is_child_sibling_list;
410
411 // Entry-point timeout check: ensures every recursive descent is bounded
412 // and that evaluations of small rule sets (< 16 rules) are still guarded.
413 // Without this, the periodic every-16-rules check below never fires for
414 // flat rule lists with fewer than 16 rules, and recursion into children
415 // also restarts `rule_count` at 0.
416 if let Some(timeout_ms) = context.timeout_ms()
417 && start_time.elapsed().as_millis() >= u128::from(timeout_ms)
418 {
419 return Err(LibmagicError::Timeout { timeout_ms });
420 }
421
422 for rule in rules {
423 // For continuation siblings (child recursion), reset the
424 // previous-match anchor to the entry anchor so `&N` offsets
425 // resolve against the parent-level position. Top-level
426 // siblings (depth 0) keep the chaining behavior documented in
427 // GOTCHAS S3.8. See the `entry_anchor` comment above.
428 if is_child_sibling_list {
429 context.set_last_match_end(entry_anchor);
430 }
431
432 // Check timeout periodically (every 16 rules) to reduce syscall overhead
433 rule_count = rule_count.wrapping_add(1);
434 if rule_count.trailing_zeros() >= 4
435 && let Some(timeout_ms) = context.timeout_ms()
436 && start_time.elapsed().as_millis() >= u128::from(timeout_ms)
437 {
438 return Err(LibmagicError::Timeout { timeout_ms });
439 }
440
441 // `Clear` resets the per-level "sibling matched" flag so a
442 // subsequent `default` sibling can fire even if an earlier
443 // sibling matched. Matching libmagic's `FILE_CLEAR`, the flag is
444 // unconditionally reset and NEVER re-set to `true` afterward
445 // (clear does not participate in the "a sibling matched" chain).
446 //
447 // libmagic's `FILE_CLEAR` also COUNTS as a match -- its `x` test
448 // always succeeds -- and `mprint` renders its description when it
449 // is non-empty. So a `clear` carrying message text must emit that
450 // text (c-lang's `>>&0 clear x program text` is the only such rule
451 // in the system DB, producing the "program text" fragment of
452 // `c program text`). Verified against real `file` (file-5.41):
453 // a message-bearing `clear` child prints its message AND still
454 // resets the flag so a trailing `default` sibling fires.
455 //
456 // Emission is guarded on a non-empty message so the many bare
457 // `clear x` flag-reset directives throughout the system DB (apple,
458 // coff, elf, pmem, ...) behave exactly as before -- no match, no
459 // anchor advance. `clear` is 0-width, so the previous-match anchor
460 // is intentionally not advanced in either case. Children are
461 // evaluated for a message-bearing clear for libmagic fidelity;
462 // `evaluate_children_or_warn` is a no-op when there are none.
463 if let TypeKind::Meta(MetaType::Clear) = &rule.typ {
464 sibling_matched = false;
465
466 if !rule.message.is_empty() {
467 let matches_before = matches.len();
468
469 let match_result = RuleMatch::new(
470 rule.message.clone(),
471 context.last_match_end(),
472 rule.level,
473 crate::parser::ast::Value::Uint(0),
474 rule.typ.clone(),
475 RuleMatch::calculate_confidence(rule.level),
476 );
477 matches.push(match_result);
478
479 evaluate_children_or_warn(rule, "clear", buffer, context, &mut matches)?;
480
481 if stop_at_first_match_applies
482 && matches.len() > matches_before
483 && context.should_stop_at_first_match()
484 && has_message_bearing_match(&matches, matches_before)
485 {
486 break;
487 }
488 }
489 continue;
490 }
491
492 // `Default` fires only when no earlier sibling at this level has
493 // matched yet. The anchor is intentionally not advanced -- the
494 // directive does not consume bytes -- but its children are
495 // evaluated and the per-level "sibling matched" flag is set so
496 // any later `default` sibling at the same level is suppressed.
497 if let TypeKind::Meta(MetaType::Default) = &rule.typ {
498 if !sibling_matched {
499 let matches_before = matches.len();
500
501 let match_result = RuleMatch::new(
502 rule.message.clone(),
503 context.last_match_end(),
504 rule.level,
505 crate::parser::ast::Value::Uint(0),
506 rule.typ.clone(),
507 RuleMatch::calculate_confidence(rule.level),
508 );
509 matches.push(match_result);
510
511 // `default` is treated as a successful match at this
512 // level, so its children are evaluated under the same
513 // recursion-guard pattern as every other successful rule.
514 evaluate_children_or_warn(rule, "default", buffer, context, &mut matches)?;
515
516 sibling_matched = true;
517
518 if stop_at_first_match_applies
519 && matches.len() > matches_before
520 && context.should_stop_at_first_match()
521 && has_message_bearing_match(&matches, matches_before)
522 {
523 break;
524 }
525 }
526 continue;
527 }
528
529 // `Indirect` re-evaluates the root rule list at the resolved
530 // offset, mirroring libmagic's indirect-type semantics. The
531 // sub-evaluation runs against `buffer[absolute_offset..]` with a
532 // fresh anchor (0) so relative offsets inside the root rules
533 // resolve correctly; the caller's anchor is restored on exit
534 // via `AnchorScope`. Without an attached `RuleEnvironment`
535 // (programmatic consumers bypassing `MagicDatabase`) the
536 // directive is a silent no-op.
537 if let TypeKind::Meta(MetaType::Indirect) = &rule.typ {
538 // Resolve the offset first so a malformed offset surfaces
539 // as a graceful skip rather than a hard error.
540 let absolute_offset = match offset::resolve_offset_with_base(
541 &rule.offset,
542 buffer,
543 context.last_match_end(),
544 context.base_offset(),
545 ) {
546 Ok(o) => o,
547 Err(
548 e @ LibmagicError::EvaluationError(
549 crate::error::EvaluationError::BufferOverrun { .. }
550 | crate::error::EvaluationError::InvalidOffset { .. },
551 ),
552 ) => {
553 debug!("Skipping indirect rule '{}': {}", rule.message, e);
554 continue;
555 }
556 Err(e) => return Err(e),
557 };
558
559 // Pull the root rules out of the rule environment. Without
560 // an environment there is nothing to re-enter, so this is a
561 // silent no-op (matching the `Use`-without-env behavior).
562 //
563 // We use `debug!` rather than `debug_assert!` here because
564 // property tests (`prop_arbitrary_rule_evaluation_never_panics`)
565 // synthesize arbitrary `TypeKind::Meta(MetaType::Indirect)`
566 // rules and run them without attaching a `RuleEnvironment`;
567 // a panic on this path would break the never-panics invariant.
568 // See GOTCHAS S2.1 for the same rationale on the leaked-Name arm.
569 let Some(root_rules) = context
570 .rule_env()
571 .map(|e| std::sync::Arc::clone(&e.root_rules))
572 else {
573 debug!(
574 "indirect rule '{}' evaluated without a rule environment; treating as no-op",
575 rule.message
576 );
577 continue;
578 };
579
580 // Bounds-check before slicing. An indirect offset past the
581 // end of the buffer is a data-dependent skip, not an error.
582 let Some(sub_buffer) = buffer.get(absolute_offset..) else {
583 debug!(
584 "Skipping indirect rule '{}': offset {} past buffer end ({} bytes)",
585 rule.message,
586 absolute_offset,
587 buffer.len()
588 );
589 continue;
590 };
591
592 let matches_before = matches.len();
593
594 // Advance the GNU `file` previous-match anchor to the indirect's
595 // resolved offset and emit a `RuleMatch` for the indirect rule
596 // itself BEFORE descending into the root re-entry or children.
597 // This matches the shared successful-match flow used by every
598 // other rule kind: advance anchor first, record the match, then
599 // recurse. Without this, sibling rules of the `indirect` resolve
600 // their relative offsets against the stale anchor and the
601 // directive's own `message` never surfaces in the output.
602 context.set_last_match_end(absolute_offset);
603
604 let indirect_match = RuleMatch::new(
605 rule.message.clone(),
606 absolute_offset,
607 rule.level,
608 crate::parser::ast::Value::String("indirect".to_string()),
609 rule.typ.clone(),
610 RuleMatch::calculate_confidence(rule.level),
611 );
612 matches.push(indirect_match);
613
614 // Indirect counts as a match for `sibling_matched` regardless of
615 // whether the sub-evaluation produced any matches -- the directive
616 // itself successfully dispatched.
617 sibling_matched = true;
618
619 // Recursion guard + anchor scope: nested indirect / use cycles
620 // surface as `RecursionLimitExceeded` instead of a stack overflow,
621 // and the caller's anchor is restored on every exit path.
622 //
623 // Mark the upcoming `evaluate_rules` call as a top-level
624 // re-entry (consumed at entry) so sibling anchor-reset
625 // semantics do NOT fire -- root rules in the re-entered
626 // database chain their anchors across siblings like any
627 // other top-level evaluation.
628 {
629 let mut guard = RecursionGuard::enter(context)?;
630 let mut anchor_scope = AnchorScope::enter(guard.context(), 0);
631 anchor_scope.context().set_indirect_reentry(true);
632 match evaluate_rules(&root_rules, sub_buffer, anchor_scope.context()) {
633 Ok(sub_matches) => {
634 // The re-entered classification always continues the
635 // preceding fragment rather than starting a new one.
636 // Two independent cases agree: mach-o's `\b:` renders
637 // `:Mach-O ...`, and jpeg's message-less
638 // `>>>10 indirect/r x` must render `[TIFF ...` after
639 // its sibling's `[`. Magic files supply their own
640 // spacing when they want it -- `archive`'s
641 // `\b, contains ` ends with a space for this reason.
642 matches.extend(output::attach_no_separator_to_first(sub_matches));
643 }
644 Err(LibmagicError::Timeout { timeout_ms }) => {
645 return Err(LibmagicError::Timeout { timeout_ms });
646 }
647 Err(e) => return Err(e),
648 }
649 // anchor_scope drops here, restoring the saved anchor
650 // (which is now `absolute_offset`, set above before the
651 // scope was entered).
652 // guard drops next, decrementing the recursion depth.
653 }
654
655 // Evaluate the indirect rule's own children under the same
656 // recursion-guard pattern used by every other successful rule.
657 evaluate_children_or_warn(rule, "indirect", buffer, context, &mut matches)?;
658
659 if stop_at_first_match_applies
660 && matches.len() > matches_before
661 && context.should_stop_at_first_match()
662 && has_message_bearing_match(&matches, matches_before)
663 {
664 break;
665 }
666 continue;
667 }
668
669 // `Offset` reports the resolved file offset as the rule's read
670 // value, matching GNU `file`'s `FILE_OFFSET` semantics: the match
671 // emits a value-bearing `RuleMatch` whose `value` is the absolute
672 // position, which downstream message formatting substitutes into
673 // `%lld` / `%d` specifiers via `output::format::format_magic_message`.
674 //
675 // Per magic(5) the only legal operator is `x` (AnyValue); any
676 // other operator is a magic-file semantic error. Matching the
677 // evaluator's graceful-skip discipline, we `debug!`-log and skip
678 // rather than erroring -- a rogue rule shouldn't poison the rest
679 // of the evaluation.
680 if let TypeKind::Meta(MetaType::Offset) = &rule.typ {
681 // Resolve the offset first so a malformed offset surfaces as
682 // a graceful skip rather than a hard error. Mirrors the
683 // `Indirect` dispatch above.
684 let absolute_offset = match offset::resolve_offset_with_base(
685 &rule.offset,
686 buffer,
687 context.last_match_end(),
688 context.base_offset(),
689 ) {
690 Ok(o) => o,
691 Err(
692 e @ LibmagicError::EvaluationError(
693 crate::error::EvaluationError::BufferOverrun { .. }
694 | crate::error::EvaluationError::InvalidOffset { .. },
695 ),
696 ) => {
697 debug!("Skipping offset rule '{}': {}", rule.message, e);
698 continue;
699 }
700 Err(e) => return Err(e),
701 };
702
703 // The magic(5) `offset` pseudo-type treats the resolved offset
704 // itself as the read value. `offset x` is a bare AnyValue
705 // placeholder that always matches (used purely to report the
706 // position via `%lld`). A comparison operator (`offset >48`,
707 // `offset <48`, `offset =N`, ...) tests the resolved offset
708 // against the operand -- e.g. gzip's `>>-0 offset >48` gates
709 // the trailing "original size modulo 2^32" trailer on the file
710 // being long enough to carry it, and its `>>-0 offset <48`
711 // sibling reports "truncated" otherwise. Skip the rule (a
712 // non-match) when the comparison fails so the false branch and
713 // its children do not render.
714 let offset_value = crate::parser::ast::Value::Uint(absolute_offset as u64);
715 let offset_matched = match &rule.op {
716 crate::parser::ast::Operator::AnyValue => true,
717 op => operators::apply_operator(op, &offset_value, &rule.value),
718 };
719 if !offset_matched {
720 continue;
721 }
722
723 let matches_before = matches.len();
724
725 // Advance the anchor BEFORE emitting the match so sibling
726 // rules resolve their relative offsets against the offset
727 // directive's resolved position. Same discipline as
728 // `Indirect` and every other value-bearing rule.
729 context.set_last_match_end(absolute_offset);
730
731 let offset_match = RuleMatch::new(
732 rule.message.clone(),
733 absolute_offset,
734 rule.level,
735 offset_value,
736 rule.typ.clone(),
737 RuleMatch::calculate_confidence(rule.level),
738 );
739 matches.push(offset_match);
740
741 sibling_matched = true;
742
743 // Evaluate children under the recursion-guard pattern used
744 // by every other successful rule.
745 evaluate_children_or_warn(rule, "offset", buffer, context, &mut matches)?;
746
747 if stop_at_first_match_applies
748 && matches.len() > matches_before
749 && context.should_stop_at_first_match()
750 && has_message_bearing_match(&matches, matches_before)
751 {
752 break;
753 }
754 continue;
755 }
756
757 // `Use` is handled inline so the subroutine's matches can be
758 // spliced into the caller's match vector in document order.
759 // Routing this through `evaluate_single_rule_with_anchor` would
760 // force the helper to return a `Vec<RuleMatch>`, which would
761 // reshape the single-rule return type for every other variant.
762 //
763 // On a successful use path we must also descend into the rule's
764 // own children, matching the flow of every other successful rule
765 // kind. libmagic chains like `>>0 use part2` often carry
766 // continuation rules (siblings and descendants of the `use` site)
767 // that depend on the anchor the subroutine left behind; skipping
768 // them produces user-visible false negatives.
769 if let TypeKind::Meta(MetaType::Use { name, flip_endian }) = &rule.typ {
770 let matches_before = matches.len();
771 let use_resolved = match evaluate_use_rule(rule, name, *flip_endian, buffer, context) {
772 Ok((Some(terminal_anchor), subroutine_matches)) => {
773 matches.extend(subroutine_matches);
774
775 // A `use` rule does not produce a surface
776 // `RuleMatch` itself -- the subroutine's rules
777 // carry the visible messages. Advance the
778 // caller's anchor to the subroutine's TERMINAL
779 // anchor (where the subroutine left `last_match_end`),
780 // not the use-site offset. This makes `use`
781 // behave like inlining the subroutine: sibling
782 // rules after the `use` see `&N` resolve against
783 // the subroutine's final match position.
784 context.set_last_match_end(terminal_anchor);
785 true
786 }
787 Ok((None, _)) => {
788 // No environment, or name not found -- silent no-op.
789 false
790 }
791 Err(
792 e @ LibmagicError::EvaluationError(
793 crate::error::EvaluationError::BufferOverrun { .. }
794 | crate::error::EvaluationError::InvalidOffset { .. }
795 | crate::error::EvaluationError::RecursionLimitExceeded { .. },
796 ),
797 ) => {
798 // A `use` chain deeper than the configured limit stops
799 // descending and keeps what the shallower levels already
800 // matched, rather than failing the whole file. Real magic
801 // walks a segment chain one `use` per element -- jpeg's
802 // `jpeg_segment` needs a level per JPEG segment -- so a
803 // long but legitimate chain must degrade, not abort. The
804 // guard still prevents stack overflow; only its reporting
805 // changes here.
806 debug!("Skipping use rule '{name}': {e}");
807 false
808 }
809 Err(e) => return Err(e),
810 };
811
812 // Evaluate the use rule's own children exactly like any other
813 // successful rule. Subroutine matches are already appended
814 // above, so children are spliced in after them to preserve
815 // document order. The recursion guard mirrors the non-`Use`
816 // path so a `use`-site chain cannot blow past the configured
817 // recursion limit.
818 if use_resolved {
819 evaluate_children_or_warn(rule, "use", buffer, context, &mut matches)?;
820 }
821
822 // A successful `use` site is treated as a sibling match for
823 // `default`/`clear` dispatch purposes -- subsequent `default`
824 // siblings should not fire if the subroutine resolved.
825 if use_resolved {
826 sibling_matched = true;
827 }
828
829 // Apply stop-at-first-match with the same semantics as every
830 // other successful rule kind: if this `use` site contributed
831 // any matches (either from the subroutine or from its own
832 // children) and the caller configured first-match
833 // short-circuiting, halt evaluation of further siblings --
834 // but only once one of those matches actually carries usable
835 // description text (see `has_message_bearing_match`).
836 if stop_at_first_match_applies
837 && matches.len() > matches_before
838 && context.should_stop_at_first_match()
839 && has_message_bearing_match(&matches, matches_before)
840 {
841 break;
842 }
843 continue;
844 }
845
846 // Evaluate the current rule with graceful error handling.
847 // Pass the GNU `file` anchor so OffsetSpec::Relative resolves
848 // correctly against the previous match's end position.
849 let match_data = match evaluate_single_rule_with_anchor(
850 rule,
851 buffer,
852 context.last_match_end(),
853 context.base_offset(),
854 context.max_string_length(),
855 context.flip_endian(),
856 ) {
857 Ok(data) => data,
858 Err(
859 e @ (LibmagicError::EvaluationError(
860 crate::error::EvaluationError::BufferOverrun { .. }
861 | crate::error::EvaluationError::InvalidOffset { .. }
862 | crate::error::EvaluationError::InvalidValueTransform { .. }
863 | crate::error::EvaluationError::TypeReadError(
864 crate::evaluator::types::TypeReadError::BufferOverrun { .. }
865 | crate::evaluator::types::TypeReadError::InvalidPStringLength { .. },
866 ),
867 )
868 | LibmagicError::IoError(_)),
869 ) => {
870 // Expected data-dependent evaluation errors -- skip gracefully.
871 // TypeReadError::UnsupportedType is intentionally NOT caught
872 // here (except the narrow exception in the arm immediately
873 // below) so that evaluator capability gaps propagate as
874 // errors.
875 debug!("Skipping rule '{}': {}", rule.message, e);
876 continue;
877 }
878 // Narrow graceful-skip (KTD4, fix-system-magic-regex-graceful
879 // plan; variant-keyed since issue #391 item 2): a pattern-bearing
880 // type (`Regex`/`Search`/flagged `String`) evaluated without a
881 // usable `String`/`Bytes` pattern operand, or a regex compile
882 // failure (including the `REGEX_COMPILE_SIZE_LIMIT` CWE-1333 DoS
883 // guard), must not abort the whole file's evaluation (R1/R2).
884 // The skip is keyed on the dedicated `MissingPatternOperand` /
885 // `RegexCompileError` variants via `TypeReadError::is_pattern_skip`
886 // -- NOT on `UnsupportedType`, so any genuine capability gap
887 // (an unwired `TypeKind` variant, a non-Equal/NotEqual operator
888 // on a pattern-bearing type, a `Meta` read as a value) stays an
889 // `UnsupportedType` and falls through to the catch-all below and
890 // propagates (R3). See `log_pattern_operand_skip` for the
891 // debug!/warn! split.
892 Err(LibmagicError::EvaluationError(crate::error::EvaluationError::TypeReadError(
893 ref tre,
894 ))) if tre.is_pattern_skip() => {
895 log_pattern_operand_skip("top-level", &rule.message, tre);
896 continue;
897 }
898 Err(e) => {
899 // Unexpected errors (InternalError, other UnsupportedType
900 // conditions, etc.) should propagate.
901 return Err(e);
902 }
903 };
904
905 if let Some((absolute_offset, read_value)) = match_data {
906 let matches_before = matches.len();
907
908 // Advance the GNU `file` previous-match anchor BEFORE recursing
909 // into children, so children and their descendants see the new
910 // anchor. The anchor is updated unconditionally to the end of
911 // this match -- it may move forward or backward depending on
912 // where successive rules match (it is *not* a high-watermark).
913 let consumed = types::bytes_consumed_with_pattern(
914 buffer,
915 absolute_offset,
916 &rule.typ,
917 Some(&rule.value),
918 );
919 let new_anchor = absolute_offset.saturating_add(consumed);
920 context.set_last_match_end(new_anchor);
921
922 // Mark this level as "matched" so any subsequent `default`
923 // sibling at the same level is suppressed, matching libmagic's
924 // default-after-match semantics.
925 sibling_matched = true;
926
927 let match_result = RuleMatch::new(
928 rule.message.clone(),
929 absolute_offset,
930 rule.level,
931 read_value,
932 rule.typ.clone(),
933 RuleMatch::calculate_confidence(rule.level),
934 );
935 matches.push(match_result);
936
937 // If this rule has children, evaluate them recursively
938 if !rule.children.is_empty() {
939 // Check recursion depth limit - this is a critical error that should stop evaluation.
940 // `RecursionGuard` decrements the depth on drop, so every exit path below
941 // (Ok, graceful warn!, or early-return via `?`) restores the counter.
942 let mut guard = RecursionGuard::enter(context)?;
943
944 // Recursively evaluate child rules with graceful error handling
945 match evaluate_rules(&rule.children, buffer, guard.context()) {
946 Ok(child_matches) => {
947 matches.extend(child_matches);
948 }
949 Err(LibmagicError::Timeout { timeout_ms }) => {
950 // Timeout is critical, propagate it up (guard drops here).
951 return Err(LibmagicError::Timeout { timeout_ms });
952 }
953 Err(
954 e @ (LibmagicError::EvaluationError(
955 crate::error::EvaluationError::BufferOverrun { .. }
956 | crate::error::EvaluationError::InvalidOffset { .. }
957 | crate::error::EvaluationError::InvalidValueTransform { .. }
958 | crate::error::EvaluationError::TypeReadError(
959 crate::evaluator::types::TypeReadError::BufferOverrun { .. }
960 | crate::evaluator::types::TypeReadError::InvalidPStringLength {
961 ..
962 },
963 ),
964 )
965 | LibmagicError::IoError(_)),
966 ) => {
967 // Defensive: under the current implementation, individual child
968 // failures are caught and logged inside the recursive evaluate_rules
969 // call (they never propagate here). This arm guards against future
970 // changes that might alter that error-handling strategy.
971 //
972 // If this fires, the parent match is still emitted but the entire
973 // child subtree is silently dropped -- which means a partial,
974 // possibly-incorrect classification is returned to the caller.
975 // Logged at warn! (not debug!) so the asymmetry is visible.
976 warn!(
977 "Discarding child evaluation under rule '{}' due to unexpected error: {} -- parent match is still emitted; investigate the recursive evaluate_rules error-handling path",
978 rule.message, e
979 );
980 }
981 // Narrow graceful-skip (KTD4): same allowlist as the
982 // top-level dispatch match above and
983 // `evaluate_children_or_warn` -- a pattern-bearing type
984 // evaluated without a usable pattern operand, or a
985 // regex compile failure, must not abort the parent's
986 // match. Defensive: individual child failures are
987 // already caught inside the recursive `evaluate_rules`
988 // call and never reach here under the current
989 // implementation; this arm guards against a future
990 // change to that strategy.
991 Err(LibmagicError::EvaluationError(
992 crate::error::EvaluationError::TypeReadError(ref tre),
993 )) if tre.is_pattern_skip() => {
994 log_pattern_operand_skip("child", &rule.message, tre);
995 }
996 Err(e) => {
997 // Unexpected errors in children (including RecursionLimitExceeded)
998 // should propagate. The guard drops here, decrementing the depth.
999 return Err(e);
1000 }
1001 }
1002 // `guard` drops here, decrementing the recursion depth.
1003 }
1004
1005 // Stop at first match if configured to do so -- but only once
1006 // this rule (or one of its descendants) actually contributed
1007 // usable description text. A message-less match (e.g. a
1008 // gating rule used purely to trigger a child) must not shadow
1009 // a later, more specific top-level rule that would otherwise
1010 // produce real output (GOTCHAS S13.2).
1011 if stop_at_first_match_applies
1012 && context.should_stop_at_first_match()
1013 && has_message_bearing_match(&matches, matches_before)
1014 {
1015 break;
1016 }
1017 }
1018 }
1019
1020 Ok(matches)
1021}
1022
1023/// Evaluate magic rules with a fresh context
1024///
1025/// This is a convenience function that creates a new evaluation context
1026/// and evaluates the rules. Useful for simple evaluation scenarios.
1027///
1028/// # Arguments
1029///
1030/// * `rules` - The list of magic rules to evaluate
1031/// * `buffer` - The file buffer to evaluate against
1032/// * `config` - Configuration for evaluation behavior
1033///
1034/// # Returns
1035///
1036/// Returns `Ok(Vec<RuleMatch>)` containing all matches found, or `Err(LibmagicError)`
1037/// if evaluation fails.
1038///
1039/// # Examples
1040///
1041/// ```rust
1042/// use libmagic_rs::evaluator::{evaluate_rules_with_config, RuleMatch};
1043/// use libmagic_rs::parser::ast::{MagicRule, OffsetSpec, TypeKind, Operator, Value};
1044/// use libmagic_rs::EvaluationConfig;
1045///
1046/// let rule = MagicRule::new(OffsetSpec::Absolute(0), TypeKind::Byte { signed: true }, Operator::Equal, Value::Uint(0x7f), "ELF magic".to_string());
1047///
1048/// let rules = vec![rule];
1049/// let buffer = &[0x7f, 0x45, 0x4c, 0x46];
1050/// let config = EvaluationConfig::default();
1051///
1052/// let matches = evaluate_rules_with_config(&rules, buffer, &config).unwrap();
1053/// assert_eq!(matches.len(), 1);
1054/// assert_eq!(matches[0].message, "ELF magic");
1055/// ```
1056///
1057/// # Errors
1058///
1059/// * `LibmagicError::EvaluationError` - If rule evaluation fails
1060/// * `LibmagicError::Timeout` - If evaluation exceeds configured timeout
1061pub fn evaluate_rules_with_config(
1062 rules: &[MagicRule],
1063 buffer: &[u8],
1064 config: &EvaluationConfig,
1065) -> Result<Vec<RuleMatch>, LibmagicError> {
1066 // Validate the configuration before constructing a context so that
1067 // out-of-range values (e.g. zero recursion depth, excessive timeouts)
1068 // are rejected at the API boundary rather than triggering subtle
1069 // failures during evaluation.
1070 config.validate()?;
1071 // Diagnostic guard: `evaluate_rules_with_config` builds a context
1072 // without an attached `RuleEnvironment`, which means any
1073 // `MetaType::Indirect` rule reached during evaluation is silently
1074 // no-op'd at runtime. That is the intentional behavior for low-level
1075 // callers (matching the `Use`-without-env contract), but we surface
1076 // the misconfiguration at `warn!` level (once per process) so a
1077 // consumer who wires up env-less `indirect` rules will see the
1078 // diagnostic in default logging rather than only at debug level.
1079 // The tree walk runs only in debug builds -- in release builds the
1080 // `cfg(debug_assertions)` gate prevents the O(n) scan on every
1081 // top-level evaluation. Using `debug_assert!` would panic in test
1082 // builds and break the "evaluator never panics" invariant documented
1083 // in GOTCHAS S2.4 -- a misconfigured caller should get a no-op with
1084 // a log entry, not a crash.
1085 #[cfg(debug_assertions)]
1086 if contains_indirect_rule(rules)
1087 && !INDIRECT_WITHOUT_RULE_ENV_WARNED.swap(true, Ordering::Relaxed)
1088 {
1089 warn!(
1090 "{} (subsequent occurrences suppressed)",
1091 crate::error::EvaluationError::indirect_without_environment()
1092 );
1093 }
1094 // Clear the thread-local regex compile cache so it is bounded to
1095 // the lifetime of a single top-level evaluation call. Cache
1096 // entries from a previous rule set would otherwise persist on the
1097 // current thread until process exit. See
1098 // `evaluator::types::regex::reset_regex_cache` for rationale.
1099 crate::evaluator::types::regex::reset_regex_cache();
1100 let mut context = EvaluationContext::new(config.clone());
1101 evaluate_rules(rules, buffer, &mut context)
1102}
1103
1104/// Recursively walk `rules` (including children) looking for any
1105/// [`MetaType::Indirect`] directive.
1106///
1107/// Used by the diagnostic guard in [`evaluate_rules_with_config`]: the
1108/// low-level `_with_config` entry point builds a context without a
1109/// [`crate::evaluator::RuleEnvironment`], so any `indirect` rule is
1110/// silently no-op'd at runtime. The check logs the misconfiguration at
1111/// `debug!` level so consumer tests can detect it without panicking (see
1112/// GOTCHAS S2.4 for why `debug_assert!` would be wrong here).
1113// Gated to debug builds like its only caller (see the diagnostic guard in
1114// `evaluate_rules_with_config`).
1115#[cfg(debug_assertions)]
1116fn contains_indirect_rule(rules: &[MagicRule]) -> bool {
1117 rules.iter().any(|rule| {
1118 matches!(rule.typ, TypeKind::Meta(MetaType::Indirect))
1119 || contains_indirect_rule(&rule.children)
1120 })
1121}
1122
1123#[cfg(test)]
1124mod tests;