All guides

Did a hijacked PyPI package run on your machine? Audit Python startup hooks and pick a cooldown

On 17 November 2026 two releases of Microsoft's agent-framework package, 1.26.1 and 1.26.2, were on PyPI for less than an hour. JFrog, Aikido, Socket and SafeDep report that they ran a credential stealer on every Python start, through a .pth file in site-packages, even when no code imported the package. You own a CI job or a dev laptop and you want two answers. Did anything in your environment run at startup, and how do you look without running it? And which rule would have kept the bad release out? By the end of this guide you can:

  • Plant a harmless canary, watch a .pth line run on a Python start that imports nothing, and scan site-packages for startup hooks without running them.
  • Test what a hash pin blocks and what it lets through, and see the scan catch the file the pin passed.
  • Pick a release cooldown from the real 17 November timeline, and write the CI order that keeps the next bad release out.

You need Python 3.12 or newer. No GPU, no API key, no network and no packages to install.

The canary, the demo wheel and the fake key are made up. We copy no payload, address or indicator from the reports. This is a method with a harmless test file, not a way to find a real attack.

Before you start

You should know Python functions, f-strings and subprocess, and what pip and a virtual environment do. If not, open these chapters first. The first four open a roadmap for that topic, and you sign in to create it. The last one is a guide here.

  1. Python virtual environments and site-packages. A virtual environment is a folder with its own Python and its own site-packages folder. The scan reads one such folder.
  2. How a Python wheel installs. A wheel is a zip file. Installing it copies files into site-packages and runs none of them. A startup file runs later, the next time Python starts.
  3. Hash functions and file integrity. A SHA-256 hash is a fingerprint of a file's bytes. A different file gives a different hash.
  4. Dependency pinning and lockfiles in Python. A pin fixes a version. A hash pin also fixes the file. Step 5 tests both.
  5. Turn a failed agent run into an eval that blocks the release. How to run a rule in CI so that a failure blocks the release. The scan in step 3 is a second check of that kind.

The question

First, did a startup hook run in an environment you own, and how do you check without starting it? Second, what is the cheapest rule that keeps the next bad release out: a pin, a hash or a cooldown? We use a harmless canary for the first question and the incident's own times for the second.

Seven words we use

Startup hook
A line or file that Python runs on every start, before your own code. It runs even when no code imports the package that brought it.
.pth file
A file in site-packages that is meant to add folders to the import path. The Python docs say a line that starts with import followed by a space or tab is run with exec(), and that such lines run at startup unless Python is started with -S.
.start file
New in Python 3.15. A file named name.start in site-packages. Each line is an entry point in the form pkg.mod:callable, and Python calls it at startup. The docs say a .start file with the same base name as a .pth file makes Python ignore the import lines of that .pth file.
Canary
A harmless stand-in for a bad startup hook. Ours prints one line and reads one made-up variable. If it runs, a real hook could have run too.
Hash pin
A line in a requirements file that fixes a package file by its hash. With pip's --require-hashes, pip refuses a file whose hash is different.
Release cooldown
A rule that a new release is not picked until it has been on the index for a set time. The wait gives others time to find a problem.
Allow list
The hashes of startup lines you have reviewed. The scan fails on any line that is not on the list.

Worked example

Plant a canary, scan without running it, read the 3.15 .start files, test a hash pin, then pick a cooldown from the real times.

What happens when Python starts
  1. 1Python starts
  2. 2site reads the .pth and .start files in site-packages
  3. 3It runs their import lines and entry points
  4. 4Your code starts

Steps 2 and 3 are skipped with -S. Your code does not need to import anything for them to run.

How long each bad release could be picked on 17 November 2026

Earliest end: 1.26.1 until 21:06, 1.26.2 until 21:16 (JFrog)Latest end: about 21:20 (Aikido)

A 1 hour cooldown counts from the upload. It would have opened 1.26.1 at 21:35 and 1.26.2 at 22:08, after both were gone.

  1. Start from a clean environment

    The demo builds a throwaway virtual environment with no packages. The scanner finds 0 startup lines in it, and python -c pass prints nothing. That is the baseline. The scanner is scan_startup.py. It reads text files and runs nothing in them.

  2. Plant a canary and start Python

    The canary is two files in site-packages. canary_hook.py prints one line and reads FAKE_API_KEY, a made-up variable that the demo sets to fake-123. canary_hook.pth holds one line: import canary_hook. Now python -c pass, a command that does nothing, prints the canary line. No code imported canary_hook. Python's site module read the .pth file at startup and ran the import line.

    With -S, which turns site off, python -c pass prints nothing. The Python docs say these lines run at startup unless -S is given, whether or not your code uses the package. A real hook runs inside the same process as your code. The reports say the real one read environment variables and credential files. We do not copy it.

  3. Look without waking it up

    The usual first step is to ask the environment's own Python for its folder, with python -c "import site; print(site.getsitepackages())". In our test that command ran the canary: the demo prints True. Asking for the folder started Python, and starting Python ran the hook. Red Hound makes the same point about pip list, and JFrog warns against a bare pip uninstall in an affected environment.

    So the scan reads the folder as text. Start it with a Python that is not the suspect one, as python -I -S scan_startup.py FOLDER, and pass the folder. The demo finds the folder with sysconfig and the venv layout, so it never starts the new environment's Python. -S skips the site module, so no startup line runs. -I also ignores PYTHON variables and the user site folder. We also tested the suspect environment's own Python. It did not run the hook under -S or under -I -S, and it did under -I alone, on 3.12.16 and 3.15.2. A different Python is still the safer choice.

    The scanner prints one row for each startup line: a status, the file and line number, the first 12 characters of the line's SHA-256 hash, and the line. It reads .pth lines that start with import followed by a space or tab, which is the rule in the Python docs. It reads every non-blank line of a .start file that does not start with #. It also lists sitecustomize.py and usercustomize.py, which Python imports at startup. The canary row is canary_hook.pth:1 with the hash 6e4e9b22ba87.

    An allow list turns the scan into a CI check. You keep the hashes of lines you have reviewed in a file. With an empty list the scan exits with 1. After we add the canary's hash, as if a person had reviewed that line, it exits with 0. A hit is a question and not a verdict, because legitimate packages use these lines too. safeguard.sh names editable installs and a few compatibility tricks.

  4. Read .start files, and the same-name pair

    Python 3.15 added .start files. Each line is an entry point in the form pkg.mod:callable, and Python calls it at startup. The docs also say that when a .start file has the same base name as a .pth file, the import lines in the .pth file are ignored.

    The demo adds canary_start.start, which names an entry point that prints start entry point ran. On Python 3.15.2, python -c pass then prints the canary line and the entry point line. The demo then renames the file to canary_hook.start, to match canary_hook.pth. On 3.15.2, python -c pass now prints only the entry point line, because the import line of the .pth file is ignored. On 3.12.16, .start files are ignored, so both runs print only the canary line.

    One folder acts differently by Python version, so the scan reads .pth and .start files on every version, and its rows list both. The docs say .pth import lines are deprecated in 3.15, will be silently ignored in 3.18 and 3.19, and will give a warning in 3.20. Until then they still run.

  5. Test a hash pin, then a pin made after the bad release

    The demo builds a tiny wheel by hand, demo_agent_lib 1.0.0, a made-up name. It writes the wheel's SHA-256 into a requirements file and installs offline with pip's --require-hashes. That exits with 0. Then it rebuilds the wheel under the same name and version with the canary files inside, as a re-upload of a bad file would be. Installing against the old lock exits with 1, and pip says the packages do not match the hashes. That is what a hash pin does. pip's docs say hash-checking mode protects against remote tampering and network issues.

    Now lock after the bad file exists. The demo writes the bad wheel's hash into a new lock and installs. That exits with 0, and python -c pass in that environment prints the canary line. A hash proves that a file is the file you locked. It does not prove the file is good. Red Hound notes that a lockfile regenerated while the bad release was on PyPI would pin it by hash, and the change would look like a routine bump.

    The scan catches what the pin let through. It flags canary_hook.pth:1 in that environment and exits with 1. And pip is Python, so pip --version in that environment ran the canary too: the demo prints True. This is why JFrog warns against a bare pip uninstall in an affected environment.

    A pin on a version has a gap as well. The reports advise a pin to agent-framework 1.26.0. SafeDep notes that 1.26.0 requires agent-framework-core[all]==1.26.0, and that this extra accepts any release below 2.0 of four sibling packages. Pinning one package did not pin the tree.

  6. Pick a cooldown from the real timeline

    A cooldown means a release is not picked until it has been on the index for a set time. The times here are UTC on 17 November 2026. JFrog reports that 1.26.1 landed at 20:35, PyPI quarantined it at 21:06, 1.26.2 landed at 21:08, and PyPI removed both by 21:16. Aikido says both were removed by 21:20. SafeDep says PyPI no longer served 1.26.1 when 1.26.2 went up. The reports do not agree to the minute, and we do not know when each release stopped being installable. So the demo uses two ends. The earliest end is JFrog's 21:06 for 1.26.1 and 21:16 for 1.26.2. The latest end is 21:20 for both.

    The first table shows the minutes each bad release could still be picked after a cooldown, as 1.26.1 / 1.26.2. With no cooldown that is 31 and 8 at the earliest end, and 45 and 12 at the latest. A 10 minute cooldown does not block both on either end. A 30 minute cooldown leaves 1 minute for 1.26.1 at the earliest end and 15 at the latest. A 1 hour cooldown blocks both on both ends. The shortest cooldown that blocks both is 31 minutes at the earliest end and 45 at the latest. JFrog reports that Renovate opened upgrade pull requests within six minutes of 1.26.1, so a bot with no cooldown was inside the window.

    One hour fits this incident. It is not a safe number in general. The second table uses one blog's list of 10 other attacks (Yossarian, 21 November 2025). A 2 hour cooldown outlasts 2 of them, 1 day outlasts 7, 7 days outlasts 8 and 14 days outlasts 9. The windows are approximate, and the two listed as less than 12 hours are counted as 12. One attack lasted about five weeks. A cooldown gives others time to find a problem. SafeDep flagged 1.26.1 22 minutes after it reached PyPI, which is the kind of find a cooldown waits for.

    pip added --uploaded-prior-to in 26.0 and whole days in 26.1, so pip's smallest step is 1 day, written P1D. In our test pip 26.2.2 accepted P1D and rejected PT1H. uv's --exclude-newer accepts durations such as 24 hours, and --exclude-newer-package sets the limit for one package, where PACKAGE=false turns it off. Both tools need an index that gives upload times, and PyPI does. The commands are in the next section. They need the network, so the demo does not run them. We only checked that pip 26.2.2 and uv 0.13.6 accept the options.

  7. Write the rule

    Our rule has four parts, in this order. First, CI installs from exact pins with hashes, and the install job holds no cloud or deploy secrets. Aikido says CI is where this hurts most. Second, put a cooldown on every tool that picks new versions: pip or uv, and your update bot. Renovate has minimumReleaseAge and Dependabot has cooldown options. Renovate recommends setting the age in both Renovate and the package manager, because a lockfile update can bring in a transitive dependency that Renovate does not check. Give a security fix a per-package skip so it is not stuck behind the wait. Third, after the install, run the scan with an allow list as a CI step, started with a Python that is not the environment's. Fourth, if a bad version was installed, the reports advise treating every secret that machine could reach as exposed, rotating them, and rebuilding images and caches (Aikido, Red Hound and JFrog). That advice is theirs and not a result of our code.

    Each part does one job. The hash pin says the file is the one you locked. The cooldown gives others time to find a problem. The scan says what runs at startup. None is complete. A clean scan means no startup line was found in the folders you scanned. It does not prove the environment is clean.

Run it yourself

Put the two files in one folder: scan_startup.py, the scanner you can keep, and startup_demo.py, which runs the steps. The scripts were run on 19 November 2026 on Windows with Python 3.12.16 and 3.15.2. On both, the output was the same except for the version line and step 4, where the difference is the point. The code uses only the standard library and nothing uses the network. The demo builds throwaway virtual environments in a temporary folder and deletes them. Step 5 also runs pip, which comes with Python's venv module. The run takes about 15 seconds.

The commands use uv, which can download Python 3.12 if you do not have it. Without uv, run python startup_demo.py in Python 3.12 or newer. The canary only prints one line and reads one made-up variable.

startup_demo.py prints one block for each worked step. Step 7 is the rule, so it has no code. To use the scanner on your own project, run python -I -S scan_startup.py FOLDER ALLOW_FILE for each site-packages folder, with a Python that is not the one in that environment. Start with an empty allow list, review each row, then add the hashes you accept.

scan_startup.py
"""List the lines Python runs at startup in one site-packages folder, without running them.
Run it as: python -I -S scan_startup.py FOLDER [ALLOW_FILE]
-S skips the site module, so no startup line on this machine runs. -I also ignores PYTHON* variables and the user site folder."""
import hashlib
import sys
from pathlib import Path


def digest(text):
    return hashlib.sha256(text.encode()).hexdigest()[:12]


def read_lines(path):
    return path.read_text(encoding="utf-8-sig", errors="replace").splitlines()


def startup_rows(folder):
    for path in sorted(folder.glob("*.pth")):
        for number, line in enumerate(read_lines(path), 1):
            if line.startswith(("import ", "import\t")):  # the rule in the Python docs
                yield path.name, number, line, digest(line)
    for path in sorted(folder.glob("*.start")):  # new in Python 3.15
        for number, line in enumerate(read_lines(path), 1):
            if line.strip() and not line.startswith("#"):
                yield path.name, number, line.strip(), digest(line.strip())
    for name in ("sitecustomize.py", "usercustomize.py"):
        path = folder / name
        if path.is_file():
            yield name, 0, "(the whole file runs at startup)", digest("\n".join(read_lines(path)))


def main(folder, allow_file=None):
    allowed = set()
    if allow_file:
        allowed = {line.split()[0] for line in read_lines(Path(allow_file)) if line.strip() and not line.startswith("#")}
    rows = list(startup_rows(Path(folder)))
    unknown = 0
    for file, number, text, line_hash in rows:
        status = "allowed" if line_hash in allowed else "UNKNOWN"
        unknown += status == "UNKNOWN"
        print(f"{status:8} {file}:{number}  {line_hash}  {text}")
    print(f"startup lines: {len(rows)}, not on the allow list: {unknown}")
    return 1 if unknown else 0


if __name__ == "__main__":
    sys.exit(main(*sys.argv[1:3]))
startup_demo.py
"""Startup hooks, hash pins and release cooldowns. Standard library only; needs Python 3.12 or newer, and scan_startup.py beside it.
Everything here is made up: the canary, the demo wheel, the key and the folder names. Nothing uses the network."""
import base64
import hashlib
import os
import subprocess
import sys
import sysconfig
import tempfile
import venv
import zipfile
from datetime import datetime, timezone
from pathlib import Path

SCAN = Path(__file__).with_name("scan_startup.py")
ENV = {**os.environ, "FAKE_API_KEY": "fake-123"}  # a made-up secret for the canary to find
CANARY_PY = "import os\nprint('canary ran; could read FAKE_API_KEY =', os.environ.get('FAKE_API_KEY'))\n"
CANARY_PTH = "import canary_hook\n"


def run(*cmd):
    done = subprocess.run([str(part) for part in cmd], capture_output=True, text=True, env=ENV)
    return done.returncode, (done.stdout + done.stderr).strip()


def show(text, indent=8):
    for line in (text or "(prints nothing)").splitlines():
        print(" " * indent + line)


def make_venv(root, with_pip=False):
    venv.EnvBuilder(with_pip=with_pip).create(root)
    where = {"base": str(root), "platbase": str(root)}  # find the folder without starting the new Python
    python = root / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
    return python, Path(sysconfig.get_path("purelib", scheme="venv", vars=where))


def scan(folder, *extra):  # this Python reads the files with -I -S, so nothing in the folder runs
    return run(sys.executable, "-I", "-S", SCAN, folder, *extra)


def build_wheel(path, bad=False):
    name, version = "demo_agent_lib", "1.0.0"
    dist = f"{name}-{version}.dist-info"
    files = {
        f"{name}/__init__.py": "__version__ = '1.0.0'\n",
        f"{dist}/METADATA": f"Metadata-Version: 2.1\nName: demo-agent-lib\nVersion: {version}\n",
        f"{dist}/WHEEL": "Wheel-Version: 1.0\nGenerator: hand\nRoot-Is-Purelib: true\nTag: py3-none-any\n",
    }
    if bad:
        files.update({"canary_hook.py": CANARY_PY, "canary_hook.pth": CANARY_PTH})
    record = []
    for arc, text in files.items():
        digest = base64.urlsafe_b64encode(hashlib.sha256(text.encode()).digest()).rstrip(b"=").decode()
        record.append(f"{arc},sha256={digest},{len(text.encode())}")
    files[f"{dist}/RECORD"] = "\n".join(record + [f"{dist}/RECORD,,"]) + "\n"
    with zipfile.ZipFile(path, "w") as wheel:
        for arc, text in files.items():
            wheel.writestr(zipfile.ZipInfo(arc, date_time=(2026, 11, 17, 0, 0, 0)), text)


def pip_install(python, wheelhouse, requirements):
    return run(python, "-m", "pip", "install", "--no-index", "--find-links", wheelhouse, "--require-hashes",
               "--disable-pip-version-check", "-r", requirements)


def at(hour, minute):
    return datetime(2026, 11, 17, hour, minute, tzinfo=timezone.utc)


# (uploaded, gone from PyPI) in UTC. Earliest end: JFrog. Latest end: Aikido, "by 21:20".
EARLIEST = {"1.26.1": (at(20, 35), at(21, 6)), "1.26.2": (at(21, 8), at(21, 16))}
LATEST = {"1.26.1": (at(20, 35), at(21, 20)), "1.26.2": (at(21, 8), at(21, 20))}
# Windows of opportunity in hours, as one blog lists them (approximate; "less than 12 hours" counted as 12).
OTHER_ATTACKS = {"xz-utils": 840, "Ultralytics 1": 12, "Ultralytics 2": 1, "tj-actions": 72, "chalk": 12,
                 "Nx": 4, "rspack": 1, "num2words": 12, "Kong": 240, "web3.js": 5}


def left(timeline, cooldown_minutes):
    return [max(0, int((gone - up).total_seconds() // 60) - cooldown_minutes) for up, gone in timeline.values()]


def main():
    print("python", sys.version.split()[0])
    with tempfile.TemporaryDirectory() as tmp:
        tmp = Path(tmp)
        python, site_dir = make_venv(tmp / "env")

        print("Step 1  a clean environment")
        show(scan(site_dir)[1])
        show("python -c pass: " + (run(python, "-c", "pass")[1] or "(prints nothing)"))

        print("Step 2  plant a harmless canary, then start Python without importing anything")
        (site_dir / "canary_hook.py").write_text(CANARY_PY)
        (site_dir / "canary_hook.pth").write_text(CANARY_PTH)
        show("python -c pass:    " + run(python, "-c", "pass")[1])
        show("python -S -c pass: " + (run(python, "-S", "-c", "pass")[1] or "(prints nothing)"))

        print("Step 3  look without waking it up")
        show("asking that Python for its folder runs the canary: " + str("canary ran" in run(python, "-c", "import site; print(site.getsitepackages())")[1]))
        show(scan(site_dir)[1])
        allow = tmp / "allow.txt"
        allow.write_text("")
        show(f"exit code, empty allow list: {scan(site_dir, allow)[0]}")
        allow.write_text("6e4e9b22ba87  # canary_hook.pth, reviewed\n")
        show(f"exit code, line allowed:     {scan(site_dir, allow)[0]}")

        print("Step 4  a .start file, then one with the same name as the .pth file (a Python 3.15 feature)")
        (site_dir / "canary_start.py").write_text("def go():\n    print('start entry point ran')\n")
        (site_dir / "canary_start.start").write_text("canary_start:go\n")
        show("python -c pass, other name:")
        show(run(python, "-c", "pass")[1], 12)
        (site_dir / "canary_start.start").rename(site_dir / "canary_hook.start")
        show("python -c pass, same name:")
        show(run(python, "-c", "pass")[1], 12)
        show("scan:")
        show(scan(site_dir)[1], 12)

        print("Step 5  a hash pin, then a pin made after the bad release")
        wheelhouse = tmp / "wheelhouse"
        wheelhouse.mkdir()
        wheel = wheelhouse / "demo_agent_lib-1.0.0-py3-none-any.whl"
        requirements = tmp / "requirements.txt"
        build_wheel(wheel)
        requirements.write_text(f"demo-agent-lib==1.0.0 --hash=sha256:{hashlib.sha256(wheel.read_bytes()).hexdigest()}\n")
        python_a, _ = make_venv(tmp / "env_a", with_pip=True)
        show(f"lock the good file, install: exit {pip_install(python_a, wheelhouse, requirements)[0]}")
        build_wheel(wheel, bad=True)  # same name and version, new bytes
        python_b, site_b = make_venv(tmp / "env_b", with_pip=True)
        code, out = pip_install(python_b, wheelhouse, requirements)
        show(f"swap the file on the index, install: exit {code}")
        show("pip says: " + next(line for line in out.splitlines() if "DO NOT MATCH" in line).split(".")[0], 12)
        requirements.write_text(f"demo-agent-lib==1.0.0 --hash=sha256:{hashlib.sha256(wheel.read_bytes()).hexdigest()}\n")
        show(f"lock the swapped file, install: exit {pip_install(python_b, wheelhouse, requirements)[0]}")
        show("python -c pass in that environment: " + run(python_b, "-c", "pass")[1])
        show("scan of that environment:")
        show(scan(site_b)[1], 12)
        show("pip starts Python too, so pip there runs the canary: " + str("canary ran" in run(python_b, "-m", "pip", "--version")[1]))

        print("Step 6  how long a cooldown must be")
        print("        minutes each bad release could still be picked, 1.26.1 / 1.26.2")
        print(f"        {'cooldown':<12}{'earliest end':^16}{'latest end':^14}blocks both")
        for label, minutes in [("none", 0), ("10 minutes", 10), ("30 minutes", 30), ("1 hour", 60), ("1 day", 1440)]:
            early, late = left(EARLIEST, minutes), left(LATEST, minutes)
            blocks = "yes" if not any(early) and not any(late) else "no"
            print(f"        {label:<12}{f'{early[0]} / {early[1]}':^16}{f'{late[0]} / {late[1]}':^14}{blocks}")
        for name, timeline in (("earliest", EARLIEST), ("latest", LATEST)):
            print(f"        shortest cooldown that blocks both, {name} end: {max(left(timeline, 0))} minutes")
        print("        other attacks (one blog's list): how many a cooldown would have outlasted")
        for label, hours in [("2 hours", 2), ("1 day", 24), ("7 days", 168), ("14 days", 336)]:
            print(f"        {label:<8} {sum(window <= hours for window in OTHER_ATTACKS.values())} of {len(OTHER_ATTACKS)}")


if __name__ == "__main__":
    main()
Terminal
uv run --no-project --python 3.12 python startup_demo.py
Output on Python 3.12.16
python 3.12.16
Step 1  a clean environment
        startup lines: 0, not on the allow list: 0
        python -c pass: (prints nothing)
Step 2  plant a harmless canary, then start Python without importing anything
        python -c pass:    canary ran; could read FAKE_API_KEY = fake-123
        python -S -c pass: (prints nothing)
Step 3  look without waking it up
        asking that Python for its folder runs the canary: True
        UNKNOWN  canary_hook.pth:1  6e4e9b22ba87  import canary_hook
        startup lines: 1, not on the allow list: 1
        exit code, empty allow list: 1
        exit code, line allowed:     0
Step 4  a .start file, then one with the same name as the .pth file (a Python 3.15 feature)
        python -c pass, other name:
            canary ran; could read FAKE_API_KEY = fake-123
        python -c pass, same name:
            canary ran; could read FAKE_API_KEY = fake-123
        scan:
            UNKNOWN  canary_hook.pth:1  6e4e9b22ba87  import canary_hook
            UNKNOWN  canary_hook.start:1  8171de3e6504  canary_start:go
            startup lines: 2, not on the allow list: 2
Step 5  a hash pin, then a pin made after the bad release
        lock the good file, install: exit 0
        swap the file on the index, install: exit 1
            pip says: ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE
        lock the swapped file, install: exit 0
        python -c pass in that environment: canary ran; could read FAKE_API_KEY = fake-123
        scan of that environment:
            UNKNOWN  canary_hook.pth:1  6e4e9b22ba87  import canary_hook
            startup lines: 1, not on the allow list: 1
        pip starts Python too, so pip there runs the canary: True
Step 6  how long a cooldown must be
        minutes each bad release could still be picked, 1.26.1 / 1.26.2
        cooldown      earliest end    latest end  blocks both
        none             31 / 8        45 / 12    no
        10 minutes       21 / 0         35 / 2    no
        30 minutes       1 / 0          15 / 0    no
        1 hour           0 / 0          0 / 0     yes
        1 day            0 / 0          0 / 0     yes
        shortest cooldown that blocks both, earliest end: 31 minutes
        shortest cooldown that blocks both, latest end: 45 minutes
        other attacks (one blog's list): how many a cooldown would have outlasted
        2 hours  2 of 10
        1 day    7 of 10
        7 days   8 of 10
        14 days  9 of 10
Terminal, Python 3.15
uv run --no-project --python 3.15 python startup_demo.py
Output on Python 3.15.2, the lines that differ
python 3.15.2
Step 4  a .start file, then one with the same name as the .pth file (a Python 3.15 feature)
        python -c pass, other name:
            canary ran; could read FAKE_API_KEY = fake-123
            start entry point ran
        python -c pass, same name:
            start entry point ran

Cooldown options

These commands are not part of the demo, because they need the network. We checked only that pip 26.2.2 and uv 0.13.6 accept the options.

Terminal
pip install --uploaded-prior-to P1D -r requirements.txt
uv pip install --exclude-newer "24 hours" -r requirements.txt
uv pip install --exclude-newer "24 hours" --exclude-newer-package some-package=false -r requirements.txt

Where you will see this

The incident reports are by JFrog, Aikido, Socket and SafeDep. They explain this attack and list indicators, which we do not copy. Red Hound adds that the install window is the wrong boundary for triage, because images, caches, proxies and lockfiles keep the file. The safeguard.sh page on .pth files gives a grep for lines that start with import and the idea of an allow list in CI. Its first command, python -c "import site; print(site.getsitepackages())", starts the environment's own Python, and in our test that ran the canary, so start the scan with another Python. The Yossarian post makes the case for cooldowns with a table of attack windows.

This guide puts the canary, the scan, the .start difference, the hash pin test and the cooldown table from real times in one script you can run. Each piece exists elsewhere in some form, and we do not claim to be first.

What this does not do

  • The canary, the demo wheel, the key and the names are made up. We ran no real payload and downloaded no malicious package. We copied no payload, address or indicator. The reports linked below have those.
  • The scan does not find everything. It reads .pth import lines, .start files and the two customize files in one folder. It does not read code inside a package's own __init__.py, entry points or other places where tools run code. Scan every site folder: the virtual environment, the system one and the user one (site.USER_SITE in the docs). A hook baked into a Docker image or a wheel cache stays until you rebuild it (Red Hound).
  • A hash pin, a cooldown and a scan each cover part of the risk. None is complete, and no cooldown number is safe in general.
  • The times come from reports that differ by minutes. We do not know when PyPI stopped serving each release. We did not open the PyPI post on quarantine, so we do not claim that a quarantined release was hidden from installers at once.
  • We claim nothing about how many machines ran the payload, who the attacker is or how the publishing credential was taken. The reports differ on downloads or say it is not known.
  • The other attack windows are approximate and come from one blog. The cooldown tables assume the cooldown counts from upload.
  • We ran the scripts on Windows with Python 3.12.16 and 3.15.2, with pip 26.2.2 in the demo environments. On Linux and macOS the code finds the folder with sysconfig, which we did not run there. The .start file rules are from the 3.15 docs and can change.
  • The pip and uv cooldown commands are not run in the demo. They need the network. We only checked that the options are accepted.
  • Sources and prices change. We read every source on the date below.

To run the scan as a check that blocks the release, see the release gate guide. Even in a clean environment, a coding agent subprocess can read os.environ, .env, or home credentials unless you move API tokens behind a local ticket broker. More guides are on the guides page.

Explore this topic in the workspace

Topic Breakdown gives you a structured revision guide for this topic and lets you highlight any phrase to open side-by-side chats with worked examples. Sign in to open it.

Open breakdown

Or type Python packaging and supply chain security: virtual environments, wheels, hashes and startup hooks into the topic box on the home page. To see a lesson first, open the sample breakdown on Machine Learning.

Sources

All sources were checked on 19 November 2026. Read each page for the full context.