diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 06213bdf40..9c2d9d9e4a 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -5,4 +5,4 @@ # https://git-scm.com/docs/gitignore#_pattern_format # PSRT member list owned by PSRT admins. -developer-workflow/psrt*.csv @warsaw @ewdurbin @ned-deily @sethmlarson +security/psrt*.csv @warsaw @ewdurbin @ned-deily @sethmlarson diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 23f03616cf..1c0343afa3 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -10,6 +10,11 @@ updates: actions: patterns: - "*" + cooldown: + # https://blog.yossarian.net/2025/11/21/We-should-all-be-using-dependency-cooldowns + # Cooldowns protect against supply chain attacks by avoiding the + # highest-risk window immediately after new releases. + default-days: 14 - package-ecosystem: pip directory: "/" @@ -21,3 +26,5 @@ updates: pip: patterns: - "*" + cooldown: + default-days: 14 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b85a45c1bb..e60db2ddca 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,6 +5,8 @@ on: [pull_request, push, workflow_dispatch] env: FORCE_COLOR: 1 +permissions: {} + jobs: test: name: Check build, markup, and links @@ -12,12 +14,14 @@ jobs: timeout-minutes: 10 steps: - - uses: actions/checkout@v6 - - uses: actions/setup-python@v6 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 with: python-version: "3" - name: Install uv - uses: hynek/setup-cached-uv@v2 + uses: hynek/setup-cached-uv@4300ec2180bc77d705e626a34e381b81a4772c51 # v2.5.0 - name: Build docs run: make html - name: Link check diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 4622f995aa..a3972b812a 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -2,14 +2,22 @@ name: Lint on: [push, pull_request, workflow_dispatch] +permissions: {} + +env: + FORCE_COLOR: 1 + RUFF_OUTPUT_FORMAT: github + jobs: lint: runs-on: ubuntu-latest timeout-minutes: 10 steps: - - uses: actions/checkout@v6 - - uses: actions/setup-python@v6 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 with: python-version: "3.x" - - uses: pre-commit/action@v3.0.1 + - uses: j178/prek-action@bdca6f102f98e2b4c7029491a53dfd366469e33d # v2.0.4 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c5beee4a37..07fdda903c 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,6 @@ repos: - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.5.7 + rev: v0.15.14 hooks: - id: ruff name: Run Ruff (lint) @@ -9,7 +9,7 @@ repos: name: Run Ruff (format) - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 + rev: v6.0.0 hooks: - id: check-case-conflict - id: check-merge-conflict @@ -18,8 +18,13 @@ repos: - id: end-of-file-fixer - id: trailing-whitespace + - repo: https://github.com/zizmorcore/zizmor-pre-commit + rev: v1.25.2 + hooks: + - id: zizmor + - repo: https://github.com/sphinx-contrib/sphinx-lint - rev: v0.9.1 + rev: v1.0.2 hooks: - id: sphinx-lint args: [--enable=default-role] diff --git a/.readthedocs.yml b/.readthedocs.yml index 26e5be9672..3e13033540 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -13,9 +13,14 @@ build: tools: python: "3" - commands: - - asdf plugin add uv - - asdf install uv latest - - asdf global uv latest - - make dirhtml BUILDDIR=_readthedocs - - mv _readthedocs/dirhtml _readthedocs/html + jobs: + post_checkout: + - git fetch --unshallow || true + build: + html: + - asdf plugin add uv + - asdf install uv latest + - asdf global uv latest + - make dirhtml BUILDDIR=_readthedocs + - mkdir -p $READTHEDOCS_OUTPUT + - mv _readthedocs/dirhtml $READTHEDOCS_OUTPUT/html diff --git a/conf.py b/conf.py index 1d88937227..fb032b895c 100644 --- a/conf.py +++ b/conf.py @@ -10,10 +10,13 @@ 'sphinx.ext.todo', 'sphinx_copybutton', 'sphinx_inline_tabs', + 'sphinx_last_updated_by_git', 'sphinxext.opengraph', 'sphinxext.rediraffe', ] +html_last_updated_fmt = '%b %d, %Y' + # The master toctree document. master_doc = 'index' @@ -147,6 +150,9 @@ "langchanges.rst": "developer-workflow/lang-changes.rst", "porting.rst": "developer-workflow/porting.rst", "stdlibchanges.rst": "developer-workflow/stdlib.rst", + # Security + "developer-workflow/psrt.rst": "security/psrt.rst", + "developer-workflow/sbom.rst": "security/sbom.rst", # Documentation "docquality.rst": "documentation/help-documenting.rst", "documenting.rst": "documentation/start-documenting.rst", @@ -160,6 +166,7 @@ "gitbootcamp.rst": "getting-started/git-boot-camp.rst", "pullrequest.rst": "getting-started/pull-request-lifecycle.rst", "setup.rst": "getting-started/setup-building.rst", + "getting-started/generative-ai.rst": "getting-started/ai-tools.rst", # CPython Internals "compiler.rst": "internals.rst", "exploring.rst": "internals.rst", @@ -202,7 +209,7 @@ "contrib/project/github.rst": "index.rst", "contrib/project/governance.rst": "index.rst", "contrib/project/roles.rst": "index.rst", - "contrib/project/generative-ai.rst": "getting-started/generative-ai.rst", + "contrib/project/generative-ai": "getting-started/ai-tools.rst", "contrib/project/outreach.rst": "index.rst", "contrib/project/directory-structure.rst": "getting-started/setup-building.rst", "contrib/project/index.rst": "index.rst", diff --git a/core-team/committing.rst b/core-team/committing.rst index c606df3839..1209d6ae1e 100644 --- a/core-team/committing.rst +++ b/core-team/committing.rst @@ -35,7 +35,7 @@ to enter the public source tree. Ask yourself the following questions: Check :ref:`pull-request-lifecycle` and :ref:`helptriage` to review what is expected of a pull request. -* **Does the change break backwards-compatibility without a strong reason?** +* **Does the change break backwards compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything still passes. If there is a change to the semantics, then there needs to be a strong reason, because it will cause some peoples' code to break. @@ -79,6 +79,31 @@ to enter the public source tree. Ask yourself the following questions: :ref:`what-s-new-and-news-entries` +Merging the pull request +------------------------ + +Once the pull request is ready, you (the core team member) can merge it. +If other people have been substantially involved in the review, it can be good +to wait for their approval even if a core team member has already approved the +pull request. + +The CPython repo is configured to only accept squashes. You will squash the +pull request. + +Commit message +^^^^^^^^^^^^^^ + +GitHub defaults the squashed commit message to a combined list of all of the +individual commit messages in the pull request. Do not leave those. They often +are too noisy and provide little context, especially since devs know their +work will be eventually squashed, so intermediate commit messages while +working on the pull request are not interesting. + +If you think it is important, you can summarize the collaborative work that +went into the pull request, but it is not necessary. The pull request and/or +original issue are still available for detailed investigations of history. + + Working with Git_ ----------------- diff --git a/core-team/core-team.csv b/core-team/core-team.csv index 46dfd81530..b7f25e1618 100644 --- a/core-team/core-team.csv +++ b/core-team/core-team.csv @@ -1,3 +1,4 @@ +Chris Eibl,chris-eibl,2026-05-10,, Stan Ulbrych,StanFromIreland,2026-03-26,, Itamar Oren,itamaro,2026-02-16,, Emma Smith,emmatyping,2025-07-31,, diff --git a/core-team/motivations.rst b/core-team/motivations.rst index d0e5a0cc18..7babb5f7da 100644 --- a/core-team/motivations.rst +++ b/core-team/motivations.rst @@ -115,7 +115,7 @@ participating in the CPython core development process: As a core team member, she is primarily interested in helping to ensure Python's continued suitability for educational, testing and data analysis use cases, as well as in encouraging good architectural practices when assembling Python - applications and test harnesses from open source components. + applications and test harnesses from open-source components. Note: prior to August 2023, Alyssa used her birth name (Nick Coghlan). Some records (for example, mailing list archives, version control history) will still reference that name. @@ -175,14 +175,14 @@ participating in the CPython core development process: available, working on the infrastructure that supports CPython development, specifically the Roundup-based bug tracker and the buildbot system. - David currently does both proprietary and open source development work, + David currently does both proprietary and open-source development work, primarily in Python, through the company in which he is a partner, `Murray & Walker, Inc `__. He has done contract work focused specifically on CPython development both through the PSF (the kickstart of the email Unicode API development) and directly funded by interested corporations (additional development work on email funded by QNX, and work on CPython ICC support funded by Intel). He would like to - spend more of his (and his company's) time on open source work, and so is + spend more of his (and his company's) time on open-source work, and so is actively seeking additional such contract opportunities. .. topic:: Antoine Pitrou (France) @@ -202,7 +202,7 @@ participating in the CPython core development process: concurrent programming. As a professional, Antoine has been first specializing in network - programming, and more lately in open source data science infrastructure. + programming, and more lately in open-source data science infrastructure. He has made numerous contributions to Numba, Dask and is currently working full time on Apache Arrow as a technical leader at QuantStack. @@ -269,7 +269,7 @@ participating in the CPython core development process: Carol is focused on Python's usage in education and scientific research. She is interested in distributed computing, organizational development, - operational workflows, and sustainability of open source projects. + operational workflows, and sustainability of open-source projects. .. _goals-of-the-motivations-page: @@ -282,7 +282,7 @@ strongly suggest that the current core development process is bottlenecked on core team time. This is most clearly indicated in the first metrics graph, which shows both the number of open issues and the number of pull requests awaiting review growing steadily over time, despite CPython being one of the most -active open source projects in the world. This bottleneck then impacts not only +active open-source projects in the world. This bottleneck then impacts not only resolving open issues and accepting submitted pull requests, but also the process of identifying, nominating and mentoring new core team members. diff --git a/core-team/responsibilities.rst b/core-team/responsibilities.rst index 9f5c62b728..130e763d56 100644 --- a/core-team/responsibilities.rst +++ b/core-team/responsibilities.rst @@ -123,7 +123,7 @@ to better assess the sustainability of current contributions to CPython core development, and also serves as a referral list for organisations seeking commercial Python support from the core development community. -And finally, enjoy yourself! Contributing to open source software should be fun +And finally, enjoy yourself! Contributing to open-source software should be fun (overall). If you find yourself no longer enjoying the work then either take a break or figure out what you need to do to make it enjoyable again. diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index a45003c783..101bb06122 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -270,7 +270,7 @@ that way. You can find their blogs (and various other developers who use Python) at `Planet Python `__. -Setting expectations for open source participation +Setting expectations for open-source participation ================================================== Burn-out is common in open source due to a misunderstanding of what users, contributors, diff --git a/developer-workflow/extension-modules.rst b/developer-workflow/extension-modules.rst index 4d8c0ffca1..cab46c834b 100644 --- a/developer-workflow/extension-modules.rst +++ b/developer-workflow/extension-modules.rst @@ -547,7 +547,7 @@ Now that the configuration is in place, it remains to compile the project: .. tip:: - Use ``make -jN`` to speed-up compilation by utilizing as many CPU cores + Use ``make -jN`` to speed up compilation by utilizing as many CPU cores as possible, where *N* is as many CPU cores you want to spare (and have memory for). Be careful using ``make -j`` with no argument, as this puts no limit on the number of jobs, and compilation can sometimes use up a diff --git a/developer-workflow/index.rst b/developer-workflow/index.rst index 9919398e62..e04fc8a8b3 100644 --- a/developer-workflow/index.rst +++ b/developer-workflow/index.rst @@ -15,5 +15,3 @@ Development workflow c-api grammar porting - sbom - psrt diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index b683e55e96..ec10977221 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -126,7 +126,7 @@ If the module you want to propose adding to the stdlib meets the requirements, you may propose its inclusion by following the :abbr:`PEP (Python Enhancement Proposal)` process. See :pep:`1` for details, -and the :pep:`PEP index <0>` for previously-accepted PEPs +and the :pep:`PEP index <0>` for previously accepted PEPs that have proposed a module for inclusion. If the PEP is accepted, then the module will be added to the stdlib diff --git a/development-tools/warnings.rst b/development-tools/warnings.rst index b30d811311..1026082528 100644 --- a/development-tools/warnings.rst +++ b/development-tools/warnings.rst @@ -29,7 +29,7 @@ What to do if a warning check fails GitHub CI --------------------------------------------- The :cpy-file:`Tools/build/check_warnings.py` tool will fail if the compiler generates -more or less warnings than expected for a given source file as defined in the +more or fewer warnings than expected for a given source file as defined in the platform-specific warning ignore file. The warning ignore file is either :cpy-file:`Tools/build/.warningignore_ubuntu` or :cpy-file:`Tools/build/.warningignore_macos` depending on the platform. @@ -44,7 +44,7 @@ If a warning check fails with: warning ignore file. If the file exists in the warning ignore file increment the count by the number of newly introduced warnings. -* Unexpected improvements (less warnings) +* Unexpected improvements (fewer warnings) * Document in the PR that the change reduces the number of compiler warnings. Decrement the count in the platform-specific warning diff --git a/documentation/markup.rst b/documentation/markup.rst index 5ba8e4c7af..282b80f911 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -225,7 +225,7 @@ Explicit markup --------------- "Explicit markup" is used in reST for most constructs that need special -handling, such as footnotes, specially-highlighted paragraphs, comments, and +handling, such as footnotes, specially highlighted paragraphs, comments, and generic directives. An explicit markup block begins with a line starting with ``..`` followed by diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 28e4f21682..73618f9aec 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -84,6 +84,11 @@ free-threaded lock (GIL) optional (per :pep:`703`). Avoid using "No-GIL" to avoid double negatives (for example, "non-no-GIL"). +open source + Follow the usual English rules for compound words. When used as an + adjective, hyphenate: "open-source software". When used as a noun, don't use + a hypen: "open source is a collaboration model.." + POSIX The name assigned to a particular group of standards. This is always uppercase. @@ -92,7 +97,7 @@ Python The name of our favorite programming language is always capitalized. reST - For "reStructuredText," an easy to read, plaintext markup syntax + For "reStructuredText," an easy to read, plain-text markup syntax used to produce Python documentation. When spelled out, it is always one word and both forms start with a lowercase 'r'. diff --git a/getting-started/ai-tools.rst b/getting-started/ai-tools.rst new file mode 100644 index 0000000000..e7d94d3517 --- /dev/null +++ b/getting-started/ai-tools.rst @@ -0,0 +1,64 @@ +.. _ai-tools: +.. _generative-ai: + +============================= +Guidelines for using AI tools +============================= + +The person submitting an issue or PR is responsible for its content, +regardless of whether AI tools were used in its creation. Generative AI +tools can produce output quickly, but discretion, good judgment, and +critical thinking are the foundation of all good contributions. We value +good code, concise accurate documentation, and well scoped PRs without +unneeded code churn. + +Considerations for success +========================== + +Authors must review the work done by AI tooling in detail to ensure it +actually makes sense before proposing it as a PR or filing it as an issue. + +We expect PR authors and those filing issues to be able to explain their +proposed changes in their own words. + +Disclosure of the use of AI tools in the PR description is appreciated, +while not required. Be prepared to explain how the tool was used and what +changes it made. + +Whether you are using AI tools or not, keep the following principles in +mind for the quality of your contribution: + +- Consider whether the change is necessary +- Make minimal, focused changes +- Follow existing coding style and patterns +- Write tests that exercise the change +- Keep backwards compatibility with prior releases in mind. Existing + tests may be ensuring specific API behaviors are maintained. + +Pay close attention to AI generated recommendations for testing changes. +Provide input about Python's testing principles when guiding an AI model. +Always review the output before opening a pull request or issue, +including proposed PR or issue titles and descriptions. + +Acceptable uses +=============== + +Some of the acceptable uses of generative AI include: + +- Assistance with writing comments, especially in a non-native language +- Gaining understanding of existing code +- Supplementing contributor knowledge for code, tests, and documentation + +Unacceptable uses +================= + +Maintainers may close issues and PRs that are not useful or productive, +regardless of whether AI tools were used or not. + +If a contributor repeatedly opens unproductive issues or PRs, they may be +blocked from contributing to the project because it is disruptive and +disrespectful of the maintainers time. + +It is not acceptable to alter or bypass existing tests, or remove desired +functionality, in order to make a failing test pass. Such changes are not +a real fix. diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst deleted file mode 100644 index e4aa3e7586..0000000000 --- a/getting-started/generative-ai.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _generative-ai: - -============= -Generative AI -============= - -Generative AI tools have evolved rapidly, and their suggested results can be helpful. As with using any tool, the resulting contribution is -the responsibility of the contributor. We value good code, concise accurate documentation, and avoiding unneeded code -churn. Discretion, good judgment, and critical thinking are the foundation of all good contributions, regardless of the -tools used in their creation. - -Acceptable uses -=============== - -Some of the acceptable uses of generative AI include: - -- Assistance with writing comments, especially in a non-native language -- Gaining understanding of existing code -- Supplementing contributor knowledge for code, tests, and documentation - -Unacceptable uses -================= - -Maintainers may close issues and PRs that are not useful or productive, including -those that are fully generated by AI. If a contributor repeatedly opens unproductive -issues or PRs, they may be blocked. - -Considerations for success -========================== -- While AI assisted tools such as autocompletion can enhance productivity, they sometimes rewrite entire code blocks instead of making small, focused edits. - This can make it more difficult to review changes and to fully understand both the original intent of the code and the rationale behind the new modifications. - Maintaining consistency with the original code helps preserve clarity, traceability, and meaningful reviews and also helps us avoid unnecessary code churn. -- Sometimes AI assisted tools make failing unit tests pass by altering or bypassing the tests rather than addressing the underlying problem in the code. - Such changes do not represent a real fix. Authors must review the work done by AI tooling in detail to ensure it actually makes sense before proposing it as a PR. -- Keep the following principles for the quality of your contributions in mind whether you use generative AI or not: - - - Consider whether the change is necessary - - Make minimal, focused changes - - Follow existing coding style and patterns - - Write tests that exercise the change diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 6376a190ca..47f49f3d69 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -462,12 +462,19 @@ Or set up a Git alias: git config --global alias.pr '!sh -c "git fetch upstream pull/${1}/head:pr_${1} && git switch pr_${1}" -' -.. tab:: Windows +.. tab:: Windows cmd .. code-block:: dosbatch git config --global alias.pr "!sh -c 'git fetch upstream pull/${1}/head:pr_${1} && git switch pr_${1}' -" +.. tab:: Windows Powershell + + .. code-block:: shell + + git config --global alias.pr '!f() { git fetch upstream pull/$1/head:pr_$1 && git checkout pr_$1; }; f' + + The alias only needs to be done once. After the alias is set up, you can get a local copy of a pull request as follows:: diff --git a/getting-started/index.rst b/getting-started/index.rst index 05ee67a3bc..48037ad38d 100644 --- a/getting-started/index.rst +++ b/getting-started/index.rst @@ -12,4 +12,4 @@ Getting started git-boot-camp pull-request-lifecycle getting-help - generative-ai + ai-tools diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 11915e3e58..3590e09c3f 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -83,7 +83,7 @@ You will only need to execute these steps once per machine: (You can use both SSH-based or HTTPS-based URLs.) -.. Step 6 and 7 are are duplicated in bootcamp as well. +.. Step 6 and 7 are duplicated in bootcamp as well. Please update these steps in both places. 6. Add an ``upstream`` remote, then configure ``git`` @@ -857,7 +857,7 @@ some of CPython's modules (for example, ``zlib``). For **Homebrew**, install dependencies using ``brew``:: - $ brew install pkg-config openssl@3 xz gdbm tcl-tk mpdecimal zstd + $ brew bundle --file=Misc/Brewfile .. tab:: Python 3.11+ diff --git a/index.rst b/index.rst index 4a478e7cc1..23ed08e151 100644 --- a/index.rst +++ b/index.rst @@ -40,6 +40,7 @@ Guide for contributing to Python: * :ref:`rst-primer` * :ref:`translating` * :ref:`devguide` + * :ref:`ai-tools` - * :ref:`setup` * :ref:`help` @@ -49,6 +50,7 @@ Guide for contributing to Python: * :ref:`communication` * :ref:`gitbootcamp` * :ref:`devcycle` + * :ref:`ai-tools` - * :ref:`tracker` * :ref:`triaging` @@ -288,6 +290,7 @@ Full table of contents testing/index development-tools/index core-team/index + security/index internals versions diff --git a/requirements.txt b/requirements.txt index 09d13a3fec..5dfb12f146 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,6 +3,7 @@ jinja2 linklint sphinx-autobuild>=2025.8.25 sphinx-inline-tabs>=2025.12.21.14 +sphinx-last-updated-by-git>=0.3.8 sphinx-lint==1.0.2 sphinx-notfound-page>=1.1.0 sphinx_copybutton>=0.5.2 diff --git a/security/index.rst b/security/index.rst new file mode 100644 index 0000000000..dd084b9eb0 --- /dev/null +++ b/security/index.rst @@ -0,0 +1,12 @@ +.. _security: + +======== +Security +======== + +.. toctree:: + :maxdepth: 5 + + policy + psrt + sbom diff --git a/security/policy.rst b/security/policy.rst new file mode 100644 index 0000000000..e9b145220b --- /dev/null +++ b/security/policy.rst @@ -0,0 +1,168 @@ +=============== +Security policy +=============== + +.. important:: + + :ref:`Python Security Response Team ` (PSRT) members balance this work + against many other responsibilities. Please be thoughtful about the time and + attention your report requires. Repeated failure to respect the security policy + will result in future reports being rejected, or the reporter being banned + from the ``python`` GitHub organization, regardless of technical merit. + +What types of bugs are vulnerabilities? +--------------------------------------- + +**Not all bugs are vulnerabilities.** + +To avoid causing duplicate work for PSRT members, **all potential** reports +must be evaluated against the relevant threat models +prior to being submitted to the PSRT. +Where possible, cite the relevant threat model to show that +the latter has been considered while determining whether +to report a bug as a vulnerability. + +Vulnerabilities must be exploitable from code, configurations, +pre-conditions, or deployments that may exist in the real world. +A vulnerability that only affecting code +unlikely to be used in a production program +will not be accepted. + +Documented functionality is not considered a vulnerability. +For example, :mod:`pickle`, :mod:`marshal`, :mod:`shelve`, :func:`eval`, +and :func:`exec` are documented to execute arbitrary Python code that is +supplied as data. The :mod:`ctypes` module is documented to enable modifying +arbitrary locations in memory. + +Vulnerabilities must not depend on malicious control of Python's launch +conditions, including (but not limited to) command line arguments, environment variables, or +modifications to files on the target system. We assume that, at the time Python +is executed, the environment is as intended by the legitimate user, and any +malicious variation from this cannot be mitigated by Python itself. + +Vulnerabilities that affect availability (such as DoS, ReDoS, crashes, +dead-locks, and resource exhaustion) must be +triggerable with data inputs that are reasonably sized for the use case. +Availability vulnerabilities must also demonstrate an "upward" change in posture +for the attacker, rather than a "lateral" one. +This is to avoid handling performance improvements as security vulnerabilities. + +Vulnerabilities in dependencies of Python (such as zlib, Tcl/Tk, or OpenSSL) +are not vulnerabilities in Python unless Python's use of the dependency +interferes with secure use of the dependency. +For example, a vulnerability in the bundled copy of zlib in Python is a +vulnerability in zlib, not Python. + +What versions of Python accept reports? +--------------------------------------- + +Python accepts vulnerability reports and will +assign CVE IDs for :ref:`supported Python versions ` that have a +status of :ref:`"bugfix" or "security" `. Versions that are +not yet stable (status of :ref:`"feature" or "prerelease" `) +are not eligible for CVE IDs. If the vulnerability only exists in prerelease +versions (alphas, betas, release candidates), then the issue should be reported +as a regular bug. +Prior to submitting a report, check whether the issue has already been +resolved on the ``main`` branch and only requires backporting. + +Sometimes features may be marked as +"experimental" in Python, even in a stable Python version. +These features are not eligible for security vulnerabilities. +Instead, open a public GitHub issue. + +If a vulnerability is platform-dependent, check if the platform is +supported per :pep:`11`. +Vulnerabilities that exclusively affect unsupported platforms +are not treated as vulnerabilities in Python. + +As per the :pep:`Unsupported Platforms section of PEP 11 <11#unsupported-platforms>`, +porting Python to an unsupported platform is treated as a third-party project. +If you choose to report such a vulnerability to Python, please follow the +requirements of this guide. Note that these reports may be shared with +parties who expressed interested in the relevant platforms and will +generally be handled according to the relevant maintainers' security +policies. These reports may closed if the maintainers are unknown or +unresponsive. + +What to include and how to structure a vulnerability report? +------------------------------------------------------------ + +For your vulnerability report to be handled efficiently by +the PSRT, the report must include certain information and +be formatted correctly: + +* For the initial report and follow-up communications, avoid + overly long, verbose, or excessive structure (such as headers or tables). + Reports should be a few sentences describing the vulnerability. Ideally include + a proof-of-concept script that reproduces the issue and provides a clear + indication of whether the vulnerability is still present (such as exiting with + ``1`` if vulnerable and ``0`` if not vulnerable). +* When reporting large numbers or "batches" of vulnerabilities or + searching for potential vulnerabilities using an LLM, you as a reporter must + verify the factual validity (such as whether APIs have been hallucinated) + of the content in all reports prior to submission to the PSRT. +* Do not include severity or CVSS information in your initial report, + this information will be determined by the PSRT. +* Ideally, include a minimal patch with the mitigation for the report. +* Always include the versions of Python that were tested, + and indicate which were found to be vulnerable. +* Submit reports as plain-text only, including attachments. + No PDFs, binaries, notebooks, or other files that cannot be safely reviewed. + If your proof-of-concept depends on a specially constructed binary file, + please include a script to construct it rather than the file itself. +* Proof-of-concept scripts longer than a few lines should be wrapped with a + `collapsed section`_ using ``
`` for better readability. +* Reports that do not contain a potential security vulnerability (such as spam + or requesting compliance or due-diligence work) + will be discarded without a reply. + +.. _collapsed section: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections + +How to submit a vulnerability report? +------------------------------------- + +Submit all potential security vulnerability reports for CPython +by `opening a new ticket `__. +Do not open a public GitHub issue to report a security vulnerability. +For all other projects (such as pip, python.org and tools) or if you're +not sure where to send your report, send an email to +`security@python.org `__. + +Here's what to expect for how a vulnerability report will be handled: + +* Reporter reports the vulnerability privately to the PSRT. +* If the PSRT determines the report isn't a vulnerability, the reporter + may open a public issue. +* If the PSRT determines the report is a vulnerability, the PSRT will + accept the report and a CVE ID will be assigned by the PSF CNA. +* Once a public pull request containing a fix is merged to CPython, + the advisory and CVE record will be published with attribution. + +For more information about how the PSRT handles vulnerabilities, +see :ref:`psrt-vulnerability-process`. + +Code of conduct +--------------- + +Well-being and safety of the Python Security Response Team members is +prioritized over the technical merit of vulnerability reports. +Despite communications being private, vulnerability reporting is subject +to the `PSF Code of Conduct`_. Violations will be reported to the Code of +Conduct team with undisclosed vulnerability information removed, if applicable. + +.. _GHSA: https://github.com/python/cpython/security/advisories/new +.. _PSF Code of Conduct: https://policies.python.org/python.org/code-of-conduct/ + +CVE Numbering Authority (CNA) +----------------------------- + +The Python and pip projects are scoped under the +`Python Software Foundation CVE Numbering Authority `__ +(CNA). This means you must submit all security +vulnerability reports to the PSRT for a CVE ID +to be issued for Python or pip. To reach the PSF +CNA contact directly, send an email to +`cna@python.org `__. + +.. _CNA: https://www.python.org/cve-numbering-authority/ diff --git a/developer-workflow/psrt-emeritus.csv b/security/psrt-emeritus.csv similarity index 100% rename from developer-workflow/psrt-emeritus.csv rename to security/psrt-emeritus.csv diff --git a/developer-workflow/psrt.csv b/security/psrt.csv similarity index 93% rename from developer-workflow/psrt.csv rename to security/psrt.csv index da67432d9b..d794029825 100644 --- a/developer-workflow/psrt.csv +++ b/security/psrt.csv @@ -2,6 +2,7 @@ Adam Turner,AA-Turner, Barry Warsaw,warsaw,Admin Bénédikt Tran,picnixz, Benjamin Peterson,benjaminp, +Damian Shaw,notatallshaw, Donald Stufft,dstufft, Dustin Ingram,di, Ee Durbin,ewdurbin,Admin @@ -10,6 +11,7 @@ Glyph Lefkowitz,glyph, Gregory P. Smith,gpshead, Hugo van Kemenade,hugovk,Release Manager Jacob Coffee,JacobCoffee, +Kirill Podoprigora,eclips4, Larry Hastings,larryhastings, Łukasz Langa,ambv,Release Manager Ned Deily,ned-deily,"Admin, Release Manager" diff --git a/developer-workflow/psrt.rst b/security/psrt.rst similarity index 96% rename from developer-workflow/psrt.rst rename to security/psrt.rst index 6b53700d89..6a869de6ad 100644 --- a/developer-workflow/psrt.rst +++ b/security/psrt.rst @@ -1,3 +1,5 @@ +.. _psrt: + Python Security Response Team (PSRT) ==================================== @@ -84,6 +86,8 @@ following additional responsibilities: * Running nomination elections, including counting final votes and giving the Steering Council an opportunity to veto nominations via email. +.. _psrt-vulnerability-process: + Triaging a vulnerability report ------------------------------- @@ -232,13 +236,13 @@ This patch can then be applied and pushed to the public GitHub repository: git apply ./ghsa-abcd-efgh-ijkl.patch git push origin branch-name -.. warning:: **IMPORTANT:** CPython's backport infrastructure +.. important:: CPython's backport infrastructure is used for tracking backported patches. Use **one GitHub issue per CVE** to accurately track backports of vulnerability fixes. For new CVEs, even when related to a previous issue, **open a new GitHub issue** to accurately track fixed versions. -.. warning:: **IMPORTANT:** Don't select the green 'Merge pull request' +.. important:: Don't select the green 'Merge pull request' or 'Publish advisory' buttons within GHSA. Advisories are published to the mailing list, and the 'Merge pull request' button within GHSA bypasses all continuous integration and branch protection @@ -319,7 +323,11 @@ Submit using GitHub Security Advisories Thanks for submitting this report. We use GitHub Security Advisories for triaging vulnerability reports, - please submit your report here: + please review our security policy before submitting: + + https://devguide.python.org/security/policy/ + + Then submit your report here: https://github.com/python/cpython/security/advisories/new @@ -333,6 +341,15 @@ Rejecting a vulnerability report If you are interested in working on this further, you can optionally open a public issue on GitHub. +Rejecting a duplicate report +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Thanks for your report. We've determined that this submission is a duplicate + of an issue that is already being tracked internally. Please refrain from + public disclosure until the issue has been resolved. + Advisory email ~~~~~~~~~~~~~~ diff --git a/developer-workflow/sbom.rst b/security/sbom.rst similarity index 100% rename from developer-workflow/sbom.rst rename to security/sbom.rst diff --git a/testing/index.rst b/testing/index.rst index 55bdd3d08b..6e65c5fdf9 100644 --- a/testing/index.rst +++ b/testing/index.rst @@ -10,5 +10,6 @@ Testing and buildbots run-write-tests silence-warnings coverage + oss-fuzz buildbots new-buildbot-worker diff --git a/testing/oss-fuzz.rst b/testing/oss-fuzz.rst new file mode 100644 index 0000000000..ec2449a4fd --- /dev/null +++ b/testing/oss-fuzz.rst @@ -0,0 +1,55 @@ +OSS-Fuzz for CPython +==================== + +CPython uses `OSS-Fuzz `__, Google's +continuous fuzzing service for open-source projects, to find bugs and +security vulnerabilities by feeding semi-random data to various APIs. + +CPython has two OSS-Fuzz projects: + +* `cpython3 `__: + The fuzz targets, seed corpora, and dictionaries can be found in the + :cpy-file:`Modules/_xxtestfuzz/` directory of CPython. This project + is maintained for existing fuzz targets; add new targets to + ``python3-libraries``. + +* `python3-libraries `__: + The fuzz targets, seed corpora, and dictionaries can be found in the + :github:`python/library-fuzzers` repository. Access to the repository is + managed through the `@python/fuzzers + `__ team on GitHub. + +OSS-Fuzz bug reports are private when filed, so access to crash details and +reproducer test cases is limited to those listed in the ``auto_ccs`` fields of +the OSS-Fuzz project configuration files. Those listed can log into +https://oss-fuzz.com/ with their Google account to view crash details, +reproducer test cases, and project statistics. +If you need access, contact the ``@python/fuzzers`` team. +Completed issues, and issues that remain unresolved after 90 days, are publicly +visible in the `OSS-Fuzz issue tracker +`__. + +Coverage and target statistics are available in the OSS-Fuzz Introspector +project profiles for `cpython3 `__ and +`python3-libraries `__. + +In addition, `CIFuzz `__ +runs the fuzz targets on GitHub Actions for PRs to the ``main`` branch changing +relevant files. + +.. seealso:: + + The `libFuzzer `__ documentation for + details about the fuzzing engine used by OSS-Fuzz. + + +Adding new targets +------------------ + +Add new targets to the ``python3-libraries`` project. For more +information, see the documentation in the :github:`python/library-fuzzers` +repository. + +If the new target covers a standard library module, update the relevant CIFuzz +path configuration so pull requests touching that module trigger fuzzing. See +the ``LIBRARY_FUZZER_PATHS`` set in :cpy-file:`Tools/build/compute-changes.py`. diff --git a/versions.rst b/versions.rst index 58d56b3e0a..228b445d97 100644 --- a/versions.rst +++ b/versions.rst @@ -45,6 +45,7 @@ Full chart .. raw:: html :file: _static/release-cycle-all.svg +.. _version-status-key: Status key ==========