Skip to content

Commit 6e07493

Browse files
committed
fix(static_yara): bind skip metadata to its rules and name rejected files
Addresses the three review findings on NVIDIA#557. All three share one shape: the dropped-rule total was reported through a channel not tied to the scan that produced it. 1. Skip count raced across concurrent scans (rng1995, P1) `node()` called `_load_rules()` and then read `rules_skipped_count()` as a separate step. Two concurrent MCP/graph scans can interleave between those: scan B loads its own rule set and overwrites `_rules_skipped_count` before scan A reads it, so A runs rules A while reporting B's total. If B skipped nothing, A reports `completed` even though one of A's own rules was dropped -- the false-clean result NVIDIA#554 exists to prevent. Adds `load_rules_with_skips()`, which returns the rules and their own skip count from one transaction guarded by a reentrant `_RULES_LOCK`, and switches `node()` to it. `_load_rules()` keeps its single-value signature, and `load_rules_with_skips` calls it through the module global, so every existing `monkeypatch.setattr(static_yara, "_load_rules", ...)` double still applies. `rules_skipped_count()` is retained for single-threaded callers and now reads under the lock. The three cache globals are documented as one logical value that must only be written or read as a set. The lock serializes rule compilation across concurrent scans. That is a deliberate trade: compilation is cached and already deadline-bounded, and a scanner reporting a false clean is worse than one loading rules serially. 2. Rule-load event collided with a component of the same name (yashrajp22) `ledger_event` derives the work identity as `analyzer_id or f"{record_type}:{phase}"`, and the synthetic `yara_rules/` scope normalizes to `yara_rules`. Passing `analyzer_id=ANALYZER_ID` therefore produced the same work ID as the planned work item for a scanned component literally named `yara_rules`: both planned targets resolved to two matching events, and reconciliation raised a fatal `unaccounted_work` with `execution_successful=false` and CLI exit 2, instead of the nonfatal partial scan this event is meant to record. Omits `analyzer_id` on that one event so the identity falls back to `system:static`, which is disjoint from every analyzer work item by construction. As the review noted, renaming the synthetic path alone would only move the collision to the next unlucky filename. 3. Rejected rules were invisible at default log level (yashrajp22, NVIDIA#554) Both rejection handlers logged at DEBUG, so a malformed `acme.yar`, a BOM rule, or a non-UTF-8 `.yar` produced no default-level warning, and the public ledger event is scoped to the rule set rather than the file. The operator could see that a detector was dropped but not which one to repair. Both handlers now log at WARNING, naming the file and a bounded reason. `_build_namespace_map` optionally fills a `{namespace: filename}` map -- passed in rather than returned, to keep its two-value signature -- so the compile path can name `acme.yar` instead of the extension-stripped namespace `acme`. `_bounded_rejection_reason` collapses newlines and caps the echoed text at 200 characters, because rule sources are attacker-influenced when `--yara-rules-dir` points at untrusted content and YARA errors can quote the offending source line. Tests New `TestRuleSkipAccounting` (9 tests): a deterministic pairing test, a serialization test that asserts the lock is genuinely held for the whole load-and-read transaction rather than racing and hoping, a contended two-thread test over 50 observations, the `yara_rules` work-ID collision case asserting both event and planned-work IDs stay distinct, three parametrized rejection-diagnostic cases (malformed, BOM, non-UTF-8), and two bounding tests. The contended test surfaces worker-thread exceptions and asserts an observation count, so it cannot pass vacuously when the scans never ran. The autouse cache fixture now also resets `_rules_skipped_count`, which is part of that cache and would otherwise leak between tests. Verification - Negative control: all 9 new tests fail with the source change reverted and the tests kept; 9/9 pass with it. - `tests/nodes/analyzers/test_static_yara.py`: 96 passed. - Full suite: 18 pre-existing failures, byte-identical to the same run on unmodified `4e753fe` (build_context, compare_scan_accuracy, create_github_release, input_handler, json_container_ownership, security_end_to_end -- all environmental, none in the touched files). - `ruff check`, `ruff format --check`, and `mypy` clean on both files. - Windows / Python 3.13 only; the pre-existing failures above are consistent with that environment rather than with this change. Signed-off-by: Souptik Chakraborty <[email protected]>
1 parent 4e753fe commit 6e07493

2 files changed

Lines changed: 387 additions & 38 deletions

File tree

‎src/skillspector/nodes/analyzers/static_yara.py‎

Lines changed: 142 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
import math
2929
import os
3030
import stat
31+
import threading
3132
import time
3233
from collections.abc import Callable
3334
from contextvars import ContextVar
@@ -174,10 +175,19 @@ def _enforce_rule_load_deadline() -> None:
174175

175176

176177
# Module-level cache keyed by a content hash of all rule directories.
178+
#
179+
# These three are one logical value: the compiled rules, the hash they were
180+
# compiled from, and how many files were dropped producing them. They must only
181+
# ever be written or read as a set, under ``_RULES_LOCK`` -- see
182+
# :func:`load_rules_with_skips` for why reading them separately is unsafe.
177183
_compiled_rules: yara.Rules | None = None
178184
_rules_hash: str | None = None
179185
_rules_skipped_count: int = 0
180186

187+
# Reentrant so the load-and-read transaction in :func:`load_rules_with_skips`
188+
# can hold it across its own call to :func:`_load_rules`.
189+
_RULES_LOCK = threading.RLock()
190+
181191

182192
def _collect_rule_files(*dirs: Path) -> list[Path]:
183193
"""Collect YARA files with bounded no-follow deterministic traversal."""
@@ -336,13 +346,36 @@ def _read_rule_source(rule_file: Path, data: bytes | None = None) -> str:
336346
return base64.b64decode("".join(encoded_source.split())).decode("utf-8")
337347

338348

349+
#: Cap on how much of a decode/compile error is echoed into logs. Rule sources
350+
#: are attacker-influenced when ``--yara-rules-dir`` points at untrusted content,
351+
#: and YARA syntax errors can quote the offending source line, so the reason is
352+
#: truncated rather than passed through whole.
353+
MAX_RULE_REJECTION_REASON_CHARS = 200
354+
355+
356+
def _bounded_rejection_reason(exc: Exception) -> str:
357+
"""Return a single-line, length-capped description of a rule rejection."""
358+
reason = " ".join(str(exc).split())
359+
if len(reason) > MAX_RULE_REJECTION_REASON_CHARS:
360+
reason = f"{reason[:MAX_RULE_REJECTION_REASON_CHARS]}..."
361+
return reason or exc.__class__.__name__
362+
363+
339364
def _build_namespace_map(
340365
rule_files: list[Path],
341366
temp_dir: Path | None = None,
342367
*,
343368
raw_cache: dict[Path, bytes] | None = None,
369+
namespace_files: dict[str, str] | None = None,
344370
) -> tuple[dict[str, str], int]:
345-
"""Build a {namespace: source} dict and count malformed rule files."""
371+
"""Build a {namespace: source} dict and count malformed rule files.
372+
373+
If ``namespace_files`` is given it is populated with ``{namespace: filename}``
374+
so a later compile failure can name the file the operator has to fix -- a
375+
namespace has its extension stripped, so it is not a usable filename on its
376+
own. Passed in rather than returned to keep this function's two-value
377+
signature, which existing callers and tests unpack directly.
378+
"""
346379
del temp_dir
347380
sources: dict[str, str] = {}
348381
skipped = 0
@@ -353,17 +386,35 @@ def _build_namespace_map(
353386
ns = _rule_namespace(rf)
354387
if ns in sources:
355388
ns = f"{rf.parent.name}/{ns}"
389+
if namespace_files is not None:
390+
namespace_files[ns] = rf.name
356391
try:
357392
sources[ns] = _read_rule_source(rf, raw_cache[rf])
358393
except (binascii.Error, UnicodeDecodeError, ValueError) as exc:
359394
skipped += 1
360-
logger.debug("%s: skipping malformed encoded rule %s: %s", ANALYZER_ID, rf, exc)
395+
# WARNING, not DEBUG: a dropped rule silently removes a detector, so
396+
# the operator has to be able to identify and repair the file from a
397+
# default-level run (#554). The filename is named explicitly because
398+
# the ledger event is scoped to the rule set, not to one file.
399+
logger.warning(
400+
"%s: rejected rule file %s (could not decode): %s",
401+
ANALYZER_ID,
402+
rf.name,
403+
_bounded_rejection_reason(exc),
404+
)
361405
return sources, skipped
362406

363407

364-
def _compile_rules(sources: dict[str, str]) -> tuple[yara.Rules | None, int]:
408+
def _compile_rules(
409+
sources: dict[str, str],
410+
*,
411+
namespace_files: dict[str, str] | None = None,
412+
) -> tuple[yara.Rules | None, int]:
365413
"""Compile YARA rules from a namespace map. Falls back to per-source compilation on error.
366414
415+
``namespace_files`` maps namespace to filename so a rejection can name the
416+
file the operator has to fix rather than its extension-stripped namespace.
417+
367418
Returns (compiled_rules, skipped_count).
368419
"""
369420
_enforce_rule_load_deadline()
@@ -384,7 +435,14 @@ def _compile_rules(sources: dict[str, str]) -> tuple[yara.Rules | None, int]:
384435
good[ns] = source
385436
except (yara.SyntaxError, yara.Error) as exc:
386437
skipped += 1
387-
logger.debug("%s: skipping %s: %s", ANALYZER_ID, ns, exc)
438+
# WARNING for the same reason as the decode path above: without it a
439+
# broken detector disappears with no default-level trace (#554).
440+
logger.warning(
441+
"%s: rejected rule file %s (could not compile): %s",
442+
ANALYZER_ID,
443+
(namespace_files or {}).get(ns, ns),
444+
_bounded_rejection_reason(exc),
445+
)
388446

389447
_enforce_rule_load_deadline()
390448
compiled = yara.compile(sources=good) if good else None
@@ -406,40 +464,69 @@ def _load_rules(extra_dir: Path | None = None) -> yara.Rules | None:
406464
valid; callers that care about the skip count must surface it themselves
407465
or a scan can report ``completed``/SAFE while some of its own detections
408466
never ran (#554).
467+
468+
Callers should prefer :func:`load_rules_with_skips`, which returns both
469+
halves as one value; reading the count separately after this returns is
470+
racy across concurrent scans.
409471
"""
410472
global _compiled_rules, _rules_hash, _rules_skipped_count # noqa: PLW0603
411473

412-
dirs = [_BUILTIN_RULES_DIR]
413-
if extra_dir and extra_dir.is_dir():
414-
dirs.append(extra_dir)
415-
elif extra_dir:
416-
logger.warning("%s: user rules directory %s does not exist", ANALYZER_ID, extra_dir)
417-
418-
rule_files = _collect_rule_files(*dirs)
419-
if not rule_files:
420-
logger.info("%s: no YARA rule files found", ANALYZER_ID)
421-
_rules_skipped_count = 0
422-
return None
423-
424-
raw_cache = _read_rule_bytes_cache(rule_files)
425-
current_hash = _content_hash(rule_files, raw_cache)
426-
if _compiled_rules is not None and _rules_hash == current_hash:
427-
return _compiled_rules
474+
with _RULES_LOCK:
475+
dirs = [_BUILTIN_RULES_DIR]
476+
if extra_dir and extra_dir.is_dir():
477+
dirs.append(extra_dir)
478+
elif extra_dir:
479+
logger.warning("%s: user rules directory %s does not exist", ANALYZER_ID, extra_dir)
428480

429-
sources, materialize_skipped = _build_namespace_map(rule_files, raw_cache=raw_cache)
430-
compiled, compile_skipped = _compile_rules(sources)
431-
skipped = materialize_skipped + compile_skipped
432-
_rules_skipped_count = skipped
481+
rule_files = _collect_rule_files(*dirs)
482+
if not rule_files:
483+
logger.info("%s: no YARA rule files found", ANALYZER_ID)
484+
_rules_skipped_count = 0
485+
return None
433486

434-
if compiled is None:
435-
logger.warning("%s: failed to compile any YARA rules", ANALYZER_ID)
436-
return None
437-
438-
_compiled_rules = compiled
439-
_rules_hash = current_hash
440-
loaded = len(sources) - compile_skipped
441-
logger.info("%s: compiled %d YARA rule file(s) (%d skipped)", ANALYZER_ID, loaded, skipped)
442-
return compiled
487+
raw_cache = _read_rule_bytes_cache(rule_files)
488+
current_hash = _content_hash(rule_files, raw_cache)
489+
if _compiled_rules is not None and _rules_hash == current_hash:
490+
# Cache hit: _rules_skipped_count already describes this exact file
491+
# set, because it is only ever written together with _rules_hash.
492+
return _compiled_rules
493+
494+
namespace_files: dict[str, str] = {}
495+
sources, materialize_skipped = _build_namespace_map(
496+
rule_files, raw_cache=raw_cache, namespace_files=namespace_files
497+
)
498+
compiled, compile_skipped = _compile_rules(sources, namespace_files=namespace_files)
499+
skipped = materialize_skipped + compile_skipped
500+
_rules_skipped_count = skipped
501+
502+
if compiled is None:
503+
logger.warning("%s: failed to compile any YARA rules", ANALYZER_ID)
504+
return None
505+
506+
_compiled_rules = compiled
507+
_rules_hash = current_hash
508+
loaded = len(sources) - compile_skipped
509+
logger.info("%s: compiled %d YARA rule file(s) (%d skipped)", ANALYZER_ID, loaded, skipped)
510+
return compiled
511+
512+
513+
def load_rules_with_skips(extra_dir: Path | None = None) -> tuple[yara.Rules | None, int]:
514+
"""Load rules and return them with their own skip count, as one value.
515+
516+
The two halves must be obtained in a single locked transaction. Reading the
517+
count separately after :func:`_load_rules` returns lets two concurrent
518+
MCP/graph scans interleave: scan A loads rule set A, scan B loads rule set B
519+
and overwrites the module-level count, then scan A reads B's count. Scan A
520+
would then run rules A while reporting B's skip total -- and if B skipped
521+
nothing, A reports ``completed`` even though one of A's own rules was
522+
dropped, which is exactly the false-clean result #554 is about.
523+
524+
:func:`_load_rules` is called through the module global so existing
525+
``monkeypatch.setattr(static_yara, "_load_rules", ...)`` doubles still apply.
526+
"""
527+
with _RULES_LOCK:
528+
rules = _load_rules(extra_dir)
529+
return rules, _rules_skipped_count
443530

444531

445532
def rules_skipped_count() -> int:
@@ -448,8 +535,13 @@ def rules_skipped_count() -> int:
448535
Zero both when nothing was skipped and when a cache hit meant no reload
449536
ran; a cache hit implies the same file set was already validated by the
450537
load that populated the cache, so nothing new could have been skipped.
538+
539+
Retained for callers that already hold :data:`_RULES_LOCK` or run
540+
single-threaded. Anything reading this straight after :func:`_load_rules`
541+
should use :func:`load_rules_with_skips` instead.
451542
"""
452-
return _rules_skipped_count
543+
with _RULES_LOCK:
544+
return _rules_skipped_count
453545

454546

455547
def _bounded_match_instances(
@@ -940,12 +1032,13 @@ def _rule_limit_response(
9401032
)
9411033
deadline_token = _RULE_LOAD_DEADLINE.set(load_budget)
9421034
try:
943-
rules = _load_rules(extra_dir)
1035+
# One transaction: the skip count must describe *these* rules, not
1036+
# whatever a concurrent scan loaded in between.
1037+
rules, rules_skipped = load_rules_with_skips(extra_dir)
9441038
except _YaraRuleResourceLimitError as exc:
9451039
return _rule_limit_response(exc.reason, dict(exc.metrics))
9461040
finally:
9471041
_RULE_LOAD_DEADLINE.reset(deadline_token)
948-
rules_skipped = rules_skipped_count()
9491042
remaining_after_load = transitive_remaining_seconds(state)
9501043
if remaining_after_load is not None and remaining_after_load < 1.0:
9511044
return _rule_limit_response(
@@ -1106,7 +1199,19 @@ def _rule_limit_response(
11061199
# absorbed into a clean-looking events list (#554).
11071200
events.append(
11081201
ledger_event(
1109-
analyzer_id=ANALYZER_ID,
1202+
# analyzer_id is deliberately omitted. ledger_event derives the
1203+
# work identity as ``analyzer_id or f"{record_type}:{phase}"``,
1204+
# so passing it would identify this event as
1205+
# ``static_yara`` + path -- identical to the planned work item
1206+
# for a *scanned component of the same name*. A skill file
1207+
# literally named ``yara_rules`` then collides with this event,
1208+
# both planned targets resolve to two matching events, and
1209+
# reconciliation raises a fatal ``unaccounted_work`` instead of
1210+
# the nonfatal partial scan this is meant to record. Falling
1211+
# back to ``system:static`` makes the identity disjoint from
1212+
# every analyzer work item by construction, so no choice of
1213+
# filename can collide -- renaming the synthetic path alone
1214+
# would only move the collision to the next unlucky name.
11101215
outcome=LedgerOutcome.PARTIAL,
11111216
record_type=LedgerRecordType.SYSTEM,
11121217
phase="static",

0 commit comments

Comments
 (0)