Python Developer Tooling Handbook – Security

How to Enable Ruff Security Rules

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Ruff’s S rule group implements flake8-bandit security checks, catching hardcoded passwords, injection vulnerabilities, insecure hashing, and unsafe deserialization before they reach production.

Enable the Full Set

Add the S group to the project’s pyproject.toml:

[tool.ruff.lint]
extend-select = [
    "S",    # flake8-bandit security rules
]

This enables all flake8-bandit rules at once. Run the linter to see what it finds:

How to Host Your Own Python Package Index

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

A self-hosted Python package index can save a team from PyPI outages, vendor lock-in, or restricted networks, but it also gives that team another service to run. Three tools cover almost every use case: devpi for production multi-team setups, pypiserver for a small team that needs somewhere to put internal-greeter-0.1.0.whl, and bandersnatch for full PyPI mirrors on networks that cannot reach pypi.org.

Hosting an index is the server-side counterpart to How to use private package indexes with uv, which covers the client configuration for managed services like AWS CodeArtifact and JFrog Artifactory.

How to pin GitHub Actions by SHA for Python projects

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Tag-based pins like @v7 are mutable references that the action’s maintainer (or anyone who compromises their account) can repoint at malicious code, which then runs with access to your CI secrets. The March 2025 tj-actions/changed-files compromise leaked secrets from thousands of repositories precisely this way. Pinning every third-party action to a full 40-character commit SHA makes the pin immutable and cuts off that attack path. This is the same principle as pinning Python dependencies with hashes, applied one layer up to your CI.

How to Protect Against Python Supply Chain Attacks with uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Malicious packages uploaded to PyPI are usually caught and yanked within hours or days. A dependency cooldown tells uv to ignore packages published within a recent window, so compromised versions get removed before they ever reach your environment.

Set a dependency cooldown

The exclude-newer setting accepts durations and timestamps. For security hardening, durations are the right choice because they create a rolling window that moves forward with the current date.

How to Publish Python Packages with Digital Attestations

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Digital attestations let PyPI record who published each file, not just what the file contains. When consumers generate a pylock.toml lockfile, their tools can write your package’s publisher identity into the lockfile. Any change to that identity in a future update becomes visible in code review.

This guide shows how to configure a GitHub Actions workflow that publishes to PyPI with attestations enabled. The setup requires trusted publishing; attestations are cryptographically tied to the same OIDC identity that trusted publishing uses.

How to Publish to PyPI with Trusted Publishing

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Trusted publishing lets GitHub Actions upload packages to PyPI without storing any secrets. Instead of creating an API token and pasting it into your CI settings, you tell PyPI which GitHub repository and workflow are allowed to publish. GitHub Actions then proves its identity to PyPI using an OIDC token that lives only for the duration of the workflow run.

This guide covers GitHub Actions, the most common CI provider for Python projects. PyPI also supports trusted publishing from GitLab CI/CD, Google Cloud, and ActiveState.

How to Scan Python Dependencies for Vulnerabilities

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Every dependency in a Python project is a potential source of known security vulnerabilities. Scanning those dependencies against a vulnerability database catches problems before they reach production.

Using uv audit

uv 0.10.12 and later includes the uv audit command, which checks project dependencies against the OSV (Open Source Vulnerabilities) database.

Run it from the root of a uv project:

$ uv audit

uv audit reads the project’s lockfile and queries OSV for known vulnerabilities in each dependency. When vulnerabilities are found, it prints details with links to the relevant advisories and exits with a non-zero status code. When no vulnerabilities are found, it exits with status 0.

How to upgrade setup-uv from v7 to v8

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

If a GitHub Actions workflow uses astral-sh/setup-uv@v7, Dependabot will not bump it to v8 automatically, and @v8 no longer resolves. Here is the fix.

What changed in v8.0.0

Version 8.0.0 is the first immutable release of setup-uv, published in March 2026. Moving tags are gone: @v8 and @v8.0 do not exist, and no major or minor tag will ever be published again. Only full-version tags such as @v8.0.0 resolve, and each one is immutable once cut. The change follows GitHub’s supply-chain guidance for actions, limiting the blast radius if a maintainer account is compromised (see the v8.0.0 release notes).

How to Verify Dependencies with Hashes in uv

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Dependency hashes let uv verify that every downloaded artifact matches what was resolved, catching tampering before anything gets installed.

Hashes in uv.lock

uv.lock includes SHA-256 hashes for every distribution by default. After running uv lock or uv add, each entry in the lockfile contains hashes for both sdists and wheels:

[[package]]
name = "certifi"
version = "2026.2.25"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "...", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7" }
wheels = [
    { url = "...", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa" },
]

When uv sync or uv run installs packages, it checks each downloaded artifact against these hashes. If a hash does not match, installation fails.

How to Vet a Python Package Before Installing It

Tim Hopper — Fri, 15 May 2026 21:28:17 -0400

litellm 1.82.7 and 1.82.8, and Lightning AI 2.6.2 and 2.6.3, hit PyPI before matching source releases appeared on GitHub. A 30-second tag check would have caught either one. Use this five-minute pre-install routine to catch that kind of Python supply chain attack before adding a package to pyproject.toml.

Read the PyPI signals

Open the package page on PyPI and check four things.

Download trend. Run uvx with pypistats to see recent download counts:

What Is a Python Supply Chain Attack?

Tim Hopper — Mon, 11 May 2026 07:22:13 -0400

A Python supply chain attack is a class of compromise where the attacker reaches your project not by breaking your code, but by tampering with something your project trusts. The trusted thing might be a package on PyPI, a maintainer account, a build pipeline, a transitive dependency, or the registry itself. By the time uv sync or pip install runs, the malicious code is already inside the dependency graph and the install treats it like any other package.

What is PEP 829?

Tim Hopper — Thu, 07 May 2026 13:56:14 -0400

PEP 829: Package Startup Configuration Files splits the two jobs that .pth files do today into two separate files. .pth keeps the sys.path extension job. A new <name>.start file takes over package initialization, replacing the import line that turns every .pth file into an exec() surface at interpreter startup. Authored by Barry Warsaw and accepted on 24 April 2026 for Python 3.15. Python 3.15 reached beta 1 on 7 May 2026, the first build to ship the .start mechanism for package authors to test against.

What is PyPI (Python Package Index)?

Tim Hopper — Fri, 15 May 2026 07:00:57 -0400

PyPI (Python Package Index) is the official package repository for Python. When a developer runs uv add requests or pip install requests, the package is downloaded from PyPI by default. It hosts over 600,000 projects and serves billions of downloads per month.

PyPI is maintained by the Python Packaging Authority (PyPA) and powered by an open-source application called Warehouse.

What PyPI hosts

PyPI stores two types of distribution packages:

Why Installing a Python Package Can Run Code

Tim Hopper — Fri, 01 May 2026 14:28:04 -0400

pip install has never meant “copy some files into site-packages.” A Python package gets four separate chances to run code on your machine: once when it installs, once whenever it gets imported, and twice more every time you start Python afterward.

In March 2026, a malicious release of litellm exploited one of them. The payload was a .pth file that ran on every Python invocation and quietly sent cloud credentials and Kubernetes secrets to an attacker-controlled server. Six weeks later, the lightning compromise used a different surface: a daemon thread spawned from the package’s __init__.py on import. The other surfaces are just as available, and the handbook’s supply-chain defenses only make sense once you can see all four.

Why pylock.toml Includes Digital Attestations

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

A lockfile pins exact versions. Hashes verify that the files you download match the files the resolver saw. But neither tells you who published those files. That gap is what digital attestations in pylock.toml close.

The gap between hashes and provenance

Hashes prove integrity: the file has not been altered. They do not prove origin. If an attacker gains upload access to PyPI and publishes a new release of a package you depend on, the new release will have valid hashes. Your lockfile will accept them during the next update because the file matches itself. Nothing looks wrong.

Why Use Trusted Publishing for PyPI?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

Most Python packages reach PyPI through a CI pipeline. A GitHub Actions workflow builds the package, then uploads it using an API token stored as a repository secret. That token is the weak link: it never expires, it works from any machine, and anyone who obtains it can upload whatever they want to PyPI.

Trusted publishing replaces that stored token with short-lived, CI-scoped credentials. Instead of “does this request have a valid secret?”, PyPI asks “does this request come from an authorized CI workflow?” The result: there is no long-lived secret to steal.