Skip to content

docs: add CVE release guidance #607

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions doc/source/how-to/releasing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,73 @@ control system.
git push -u origin release/X.Y
git push origin vX.Y.Z

Release for CVE related dependency update
-----------------------------------------

When a Common Vulnerabilities and Exposures (CVE) affects a dependency in your
Python project, and fixing it involves modifying the allowed version range,
a new release must be created. This ensures downstream users and tooling are
made aware of the fix and can adopt it reliably.

You should always create a new release when fixing a vulnerability requires
changing the allowed version range of a dependency. This is a critical step in
making the fix discoverable and usable by others, especially those relying on
automated tools, for example dependabot, to manage dependencies.

A typical scenario requiring a release is that a known CVE affects one of your
dependencies, for example `Pillow`, and the secure version is `>=10.0.0`. You
update the version range in your project to exclude the vulnerable version. This
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
update the version range in your project to exclude the vulnerable version. This
update the version range in your project to allow the fixed version. This

can be done by modifying the `pyproject.toml` or requirements file used to define
the dependencies of your project. Here is an example of such an update:

.. tab-set::

.. tab-item:: poetry

.. code-block:: toml

# Before the update
[tool.poetry.dependencies]
Pillow = ">=9.0.0"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is, as far as I remember from our discussion, explicitely not the case we're considering here?

We'd discussed making a release when we had to change to allow a non-vulnerable version to be installed, for example:

# Before the update
[tool.poetry.dependencies]
Pillow = "<10.0.0"

# After the update
[tool.poetry.dependencies]
Pillow = "<11.0.0" # CVE-2023-44271 fix

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requiring library authors to exclude vulnerable versions of dependencies from our version ranges is not a sustainable policy imo

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When we discussed we also mentioned that project should avoid setting upper versions limits unless it is absolutely necessary, cf #586. That's why this draft mainly focused on restricting minimum version. However, I agree that excluding vulnerable versions of dependencies is not a sustainable policy.

If others agree with you, I can update the PR accordingly. Thanks for the suggestions !
Pinging @MaxJPRey @RobPasMue @jorgepiloto @greschd for visibility

Copy link
Member

@RobPasMue RobPasMue Jun 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Main message that we need to get through to our library maintainers is that our library's latest version should be installable free of CVEs (with a reasonable buffer time of course).

When one of our dependencies has a CVE, and our library only allows the usage of versions of that dependency affected by the CVE... that's when maintainers need to do some remediation (i.e. do a new release that allows the installation of CVE-free versions of our dependency)

But, actively excluding CVE-impacted versions of our dependencies is a no-go IMO (just like @da1910 pointed out).

Copy link
Member

@RobPasMue RobPasMue Jun 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now... if maintainers also want to prevent the consumption of CVE affected versions (i.e. blocking any CVE affected version), that's a decision they can consider on their side -- but it's up to them I'd say. Although it might become a nightmare for them.

Copy link
Member

@jorgepiloto jorgepiloto Jun 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is not possible securing our ecosystem without excluding vulnerable dependencies. If no other option because of the lack of alternatives, this must be documented within the library, see PyACP security considerations. This goes in the line of what @RobPasMue mentioned about maintainers.

Regarding the limits, I do not think we must limit major versions. A dependency can release a new major and your project may not be affected at all. If the major release affects the latest stable release, you just do a patch for limiting the version while fixing things in main. Then, you decide whether to patch things again or release a new version.

Overall, I see things this way:

[project]
dependencies = [
  # The conservative scenario
  "dependency>=lowest_vulnerability_free_version",
  # The flexible scenario 
  "dependency>=lowest_supported_version,!=not-valid-version,!=another-not-valid-version",
]

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would object as strongly as I possibly can to any requirement that we exclude vulnerable dependencies from our version ranges. It is not scalable, not practical, and entirely unnecessary for a security perspective in an open-source ecosystem.


# After the update
[tool.poetry.dependencies]
Pillow = ">=10.0.0" # CVE-2023-44271 fix

.. tab-item:: flit

.. code-block:: toml

# Before the update
[project]
dependencies = [
"Pillow>=9.0.0",
]


# After the update
[tool.poetry.dependencies]
dependencies = [
"Pillow>=10.0.0", # CVE-2023-44271 fix
]

.. tab-item:: requirements file

.. code-block:: text

# Before the update
Pillow>=9.0.0

# After the update
Pillow>=10.0.0 # CVE-2023-44271 fix

Once the change is committed to your main branch, you now need to create
a new release. This ensures that:

- your PyPI package no longer resolves to vulnerable combinations;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- your PyPI package no longer resolves to vulnerable combinations;
- Your PyPI package no longer requires a vulnerable combination of dependencies.

- automated tooling stop reporting your package as affected by the CVE;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- automated tooling stop reporting your package as affected by the CVE;
- Automated tooling stops reporting your package as affected by the CVE.

- users who pin your package can become aware of the fix and update accordingly.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- users who pin your package can become aware of the fix and update accordingly.
- Users of your package can be made aware of the fix and can update accordingly.


Artifact publication
--------------------

Expand Down