Add runbook for code signing certificate reports to PSRT (python#1651)

sethmlarson · zooba · ezio-melotti · web-flow · commit f3cf8fa68cc7 · 2025-09-30T15:38:44.000+03:00
Co-authored-by: Steve Dower &lt;steve.dower@microsoft.com&gt;
Co-authored-by: Ezio Melotti &lt;ezio.melotti@gmail.com&gt;
Co-authored-by: Hugo van Kemenade &lt;1324225+hugovk@users.noreply.github.com&gt;
Co-authored-by: Adam Turner &lt;9087854+AA-Turner@users.noreply.github.com&gt;
diff --git a/developer-workflow/psrt.rst b/developer-workflow/psrt.rst
@@ -93,6 +93,40 @@ severity, advisory text, and fixes.
   to ``security-announce@python.org`` using the below template. Backport labels must be added as appropriate.
   After the advisory is published a CVE record can be created.
 
+Handling code signing certificate reports
+-----------------------------------------
+
+Python signs binaries using Azure Trusted Signing and Apple Developer ID
+certificates. If a code signing certificate is reported as "compromised" or
+"malware signed with certificate", the Python Security Response Team must
+request the following information from the reporter:
+
+* Checksum(s) of binaries signed by certificate.
+* Signature(s) of binaries signed by certificate.
+
+To avoid unnecessary user confusion and churn around revoking code signing
+certificates, any reports **must be verifiable independently by the PSRT before
+taking destructive actions**, such as revoking certificates. With this
+information the PSRT can take investigative steps to verify the report, such as:
+
+* Downloading and checking artifacts from the associated Azure Pipelines
+  executions against the reported list of checksums.
+* Verifying the validity of the signatures. `Past reports
+  <https://discuss.python.org/t/103356/2>`__ have contained signatures that
+  purported to be from Python code signing certificates, but were not valid.
+* Checking the Azure Pipelines and Azure Trusted Signing audit logs for signs of
+  compromise.
+
+If any signs of compromise or incorrectly signed binaries are discovered by the
+PSRT, only then will certificates be revoked and an advisory published.
+If compromise is reported, the following non-destructive actions can be taken by
+the PSRT without verifying the reported information as a precaution, if
+relevant:
+
+* Rotating secrets associated with code signing (``TrustedSigningSecret`` for
+  Azure Trusted Publishing).
+* Resetting passwords for accounts with access to signing certificates.
+
 Template responses
 ------------------
 
