Python startup hook file written on Linux

Siemphony@siemphonylowT1546.018unverified

Matches the file-modification leg of AN0713: an auditd PATH record naming one of the files the Python interpreter processes on its own during startup. Two arms cover the two mechanisms MITRE describes. The first requires both a `.pth` suffix and a `site-packages` or `dist-packages` component in the same path, because a `.pth` file only executes its `import` lines when it sits in a site directory — matching `.pth` anywhere would fire on unrelated files and matching the directory alone would fire on every package file installed. The second arm needs no directory constraint: `sitecustomize.py` and `usercustomize.py` are imported from anywhere on `sys.path`, so the filename is the whole signal. Both are anchored on the filename with `endswith` rather than on an absolute path, because auditd records `name=` exactly as it was handed to the syscall, so a write performed from inside the directory logs a bare `sitecustomize.py` with no leading path at all. This is MITRE's `HookFilePathPatterns` knob, populated here with the Debian and RHEL site directory names and the two customize modules rather than taken from MITRE; a site that keeps virtual environments under a fixed root can tighten the first arm to that root and cut most of the noise below. Scope and limits. Only the write is a single event. The analytic's second half — a python3 execve shortly afterwards, with anomalous children or outbound connections, inside MITRE's `TimeWindow` knob — is a cross-event correlation lib/sigma has no way to express, and its `InterpreterWhitelist` knob applies to that execution rather than to this write. MITRE's `UserContext` knob cannot be applied inside this selection either: auditd emits PATH and SYSCALL as separate records for one event and the writing process's `exe`, `uid` and `auid` live only on the SYSCALL side. The technique is listed for Windows and macOS as well, but the brief carries one analytic and it is Linux-only, so neither platform is attempted here. Prerequisite: auditd watches none of these paths by default, so this rule returns zero rows until watches such as `-w /usr/lib/python3/dist-packages -p wa -k python_hooks` and one per additional interpreter or virtual-environment root are loaded — and zero rows reads as quiet when it actually means blind. Virtual environments created in user home directories are the practical gap: they hold their own site-packages and no fleet-wide watch list can enumerate them in advance. UNVERIFIED AS AUTHORED — derived from MITRE ATT&CK DET0258, not hand-written and not tested by its author. Any lab result is on this rule's own page.Full description

The 3 SIEM queries below are previews produced by Siemphony’s own translator, not pySigma, and none has been executed against a real backend — review before you deploy.

detection.yml

Splunk · SPL

Run this as a search.

index=* (((type="PATH" AND (name="*/site-packages/*" OR name="*/dist-packages/*")) AND (type="PATH" AND name="*.pth")) OR (type="PATH" AND (name="*sitecustomize.py" OR name="*usercustomize.py")))

Elastic · ES|QL

Run this as a search.

FROM logs-*| WHERE (((TO_LOWER(type) == "path" AND (TO_LOWER(name) LIKE "*/site-packages/*" OR TO_LOWER(name) LIKE "*/dist-packages/*")) AND (TO_LOWER(type) == "path" AND TO_LOWER(name) LIKE "*.pth")) OR (TO_LOWER(type) == "path" AND (TO_LOWER(name) LIKE "*sitecustomize.py" OR TO_LOWER(name) LIKE "*usercustomize.py")))

Wazuh · XML rule

Deploy to your manager — this is a rule, not a search.

<group name="sigma,linux,">  <!-- Rule ids must be unique on your manager; 100000+ is the user range. -->  <!-- 2 rules: the Sigma condition ORs across different fields,       which one rule cannot express. Any one matching is a hit. -->  <rule id="100000" level="5">    <!-- Set <if_sid> to the decoder/base rule for linux so this only evaluates relevant events. -->    <field name="type" type="pcre2">(?i)^PATH$</field>    <field name="name" type="pcre2">(?i)(/site-packages/|/dist-packages/)</field>    <field name="type" type="pcre2">(?i)^PATH$</field>    <field name="name" type="pcre2">(?i)\.pth$</field>    <description>Python startup hook file written on Linux (1/2)</description>    <mitre>      <id>T1546.018</id>    </mitre>  </rule>   <rule id="100001" level="5">    <!-- Set <if_sid> to the decoder/base rule for linux so this only evaluates relevant events. -->    <field name="type" type="pcre2">(?i)^PATH$</field>    <field name="name" type="pcre2">(?i)(sitecustomize\.py$|usercustomize\.py$)</field>    <description>Python startup hook file written on Linux (2/2)</description>    <mitre>      <id>T1546.018</id>    </mitre>  </rule></group>

Sentinel · KQL

Run this as a search.

Sentinel cannot express this construct. No Sentinel table is modelled for this logsource ({"product":"linux","service":"auditd"}), so there is nothing honest to query. Pick a logsource this translator maps, or write the KQL by hand. The Sigma source is on the first tab, unchanged.

At a glance

Logsource: auditd / linux
Level: low
Category: registry_persistence
Sigma status: experimental
Backends: 3 of 4 rendered
Updated: 30 Aug 2026
Rule ID: 277bcf8c-7924-4a0c-971e-0f87e0e89978

ATT&CKT1546.018

T1546.018Python Startup Hooks

ATT&CK® is a registered trademark of The MITRE Corporation. These mappings are the rule author’s, and are neither reviewed nor endorsed by MITRE.

Lessonregistry persistence

registry persistenceAI draft — unreviewed

01 · What this rule detects

A write to one of the files the Python interpreter processes by itself at startup: a .pth file in a site directory, or sitecustomize.py / usercustomize.py anywhere on sys.path. Both give an adversary code that runs on every subsequent Python invocation with no change to any script the user sees. This is the file-modification leg of AN0713 only — the write, not the execution that follows.

02 · Telemetry you need

Linux auditd, product: linux / service: auditd, taken from the brief. The rule matches on type: PATH records and their name= field. Auditd watches none of these paths by default, so this rule returns zero rows out of the box — and zero rows reads as quiet when it actually means blind. You need watches such as -w /usr/lib/python3/dist-packages -p wa -k python_hooks, plus one per additional interpreter root. Virtual environments in user home directories are the practical gap: they carry their own site-packages and no fleet-wide watch list can enumerate them ahead of time.

03 · How the logic works

Three selection blocks, combined as (selection_site_dir and selection_pth_file) or selection_customize_module. selection_site_dir requires name|contains one of /site-packages/ or /dist-packages/. selection_pth_file requires name|endswith: '.pth'. They are ANDed because a .pth file only executes its import lines when it sits in a site directory — matching .pth alone would fire on unrelated files, and matching the directory alone would fire on every package file ever installed. selection_customize_module stands on its own, matching name|endswith on sitecustomize.py or usercustomize.py. It needs no directory gate because those two modules are imported from anywhere on sys.path, so the filename is the entire signal. Both arms anchor on the filename rather than an absolute path, because auditd logs name= exactly as it was handed to the syscall. That last point is also this rule's sharpest blind spot, and review caught it: because name= can be relative, cd /usr/lib/python3/dist-packages && cat > evil.pth logs a bare evil.pth, the directory component never appears, and the AND on the .pth arm fails. The working directory lives on the separate CWD record, which no Sigma selection on this logsource can reach. The .pth arm effectively sees absolute-path writes only. MITRE's HookFilePathPatterns knob is what the path list implements, populated here with Debian and RHEL site-directory names and the two customize modules rather than taken from MITRE. UserContext cannot be applied inside this selection at all: the writing process's exe, uid and auid live on the SYSCALL record, not on PATH. TimeWindow and InterpreterWhitelist belong to the analytic's second half — a python3 execve shortly afterwards with anomalous children — which is a cross-event correlation lib/sigma cannot model.

04 · Common false positives

Very. Package installation is the loudest source by a wide margin: setuptools ships distutils-precedence.pth, namespace packages install -nspkg.pth, and pip install -e writes an __editable__ .pth per project, so any pip install on any host can match. Environment creation is next — venv, virtualenv, tox, poetry and conda each drop a .pth into the new site-packages. Then interpreter upgrades: Debian and RHEL both ship a sitecustomize.py, so an apt or dnf upgrade of python3 rewrites the exact name arm two anchors on. Configuration management and image builds replay all of it on every run. The rule is level: low for precisely this reason, and that calibration is honest.

05 · Detection maturity

tier_1: Lowest tier. Machine-derived from DET0258 and never run against a log line: no measured hit rate, no false-positive baseline, no confirmation that the name field carries what the logic assumes. It stays at the bottom until someone loads the watches, runs it on real auditd output and records what happened.

Tuning & false positivesexperimental · 5 declared

experimental (current stage)
test
stable

Written and reasoned about, but not yet run against real telemetry. Expect to tune it before trusting it.

Tuning tips

Do not deploy this fleet-wide as an alert. Tighten the first arm to a fixed virtual-environment root if your site has one; that removes most volume in a single move. Suppress writes whose parent is a package manager once you can join PATH to SYSCALL downstream of Sigma. Watch only the interpreter roots you actually care about rather than every one you can find. Treat a .pth written outside a package-install window, or a usercustomize.py where none existed, as the signal worth escalating.

Declared by the author

Package installation. pip and setuptools write .pth files into site-packages as a matter of course — distutils-precedence.pth ships with setuptools itself, namespace packages install a -nspkg.pth, and pip install -e writes an __editable__ .pth per editable project. Any pip install on any host can match, which makes this the loudest source by a wide margin and is why the level is low rather than medium.
Virtual environment creation. venv, virtualenv, tox, poetry and conda each write a _virtualenv.pth or an equivalent into the new environment's site-packages, so every developer workstation and every CI job that builds a fresh environment emits a burst of matches.
Distribution package upgrades of the interpreter itself. Debian and Ubuntu ship a sitecustomize.py under /usr/lib/python3.x and RHEL ships one alongside its site-packages, so an apt or dnf upgrade of python3 rewrites the exact filename this rule's second arm is anchored on.
Configuration management and image builds replaying the same environment on every convergence run or every image: an Ansible pip task, a Dockerfile RUN pip install layer, or a Puppet or Chef python resource, all of which reinstall the same packages and rewrite the same .pth files whether or not anything changed.
Editors and installers writing through a temporary file and renaming it into place, which emits several PATH records for a single logical modification of one hook file.

Noise check0 of 5 fired

Fires on none of the 5 ordinary behaviours the baseline holds for this log type. That is not a precision guarantee: it means only not caught by these 5 behaviours, and the next ordinary behaviour nobody wrote down may still match.

Run live against 65 hand-written events of ordinary corporate activity — backup agents, software distribution, patching, helpdesk scripts, EDR. It says nothing about how often the rule would fire in production, which is the number that actually exhausts an analyst.

Verification1 run

Not verified

Siemphony benign baseline
completed
Siemphony IR · 3 Sept 2026
No events matched, so this run proves nothing either way.

Test it yourselfin your browser

Runs here in your browser against public attack recordings. A preview — not the verification badge.

Recordings of T1546.018, evaluated against their — events.

Share this rule

/u/siemphony/277bcf8c-7924-4a0c-971e-0f87e0e89978

More from this repertoire

All compositions

Verdicts · reactions · comments

Community

Verdicts from engineers who actually deployed it, and the conversation around it.

Not yet reported on

Nobody has run this in a real environment and said what happened.

Verdicts from engineers who deployed it

0 cast

No verdicts reported yet. The first one is worth more than the tenth — say what you ran it against.

No comments yet. Someone who deploys this will have something to say about it.

Python startup hook file written on Linux

The detection

detection.yml

Splunk · SPL

Elastic · ES|QL

Wazuh · XML rule

Sentinel · KQL

Community

Verdicts from engineers who deployed it