进阶 docs.pypi.org 2026-10-20 06:39:13 · 28 阅读

第31章 密钥泄露报告 API

Secret reporting API

未公开发布

请注意,该 API 仅按个案开放。如需对接此 API,请联系 admin@pypi.org。

第三方通过该 API 与 PyPI 集成,以发现、识别并吊销意外公开的 API 令牌。目前以下合作伙伴向 PyPI 报告公开暴露的 API 令牌:

所有使用 API 令牌的 PyPI 用户默认已加入此服务,无需执行额外操作即可享受该权益。

该 API 供可能发现 PyPI API 令牌并希望向 PyPI 上报的第三方使用。

识别 PyPI 密钥格式

PyPI API 令牌是一个由前缀(pypi)、分隔符(-)以及表示用 PyMacaroon 序列化为 base64 的 Macaroon 的字符串组成的字符串:

pypi-[A-Za-z0-9-_]{85,}

该 base64 字符串长度不得少于 85 个字符。由于我们可能会向序列化的 Macaroon 添加任意附加条件(caveats),因此令牌长度可以任意长。

集成

PyPI 采用了 GitHub 密钥扫描上报模式。

公钥标识符与签名

PyPI 要求发往该 API 的每个请求包含两个请求头:

  • 包含公钥标识符的请求头
  • 使用对应密钥对原始消息体进行签名后生成的签名值所在的请求头

这些请求头的名称可以任意,应在集成时提供给 PyPI。它们将在每次请求中进行验证。

PyPI 假定签名为 ECDSA 签名,且摘要算法为 SHA-256。

公钥验证

PyPI 期望能够在一个集成时提供的 URL 处验证用于签署请求的公钥。该 URL 结构可以任意,但必须位于可信域名上。

集成方应准备提供 P-256/384/521 密钥,并仅使用 SHA-256(尽管 P-384 和 P-521 通常分别对应 SHA-384 和 SHA-512,但在此处不得使用)。

对该 URL 发起 GET 请求时,响应应返回一个 JSON 文档,其示例结构如下:

{ "public_keys": [ { "key_identifier": "90a421169f0a406205f1563a953312f0be898d3c7b6c06b681aa86a874555f4a", "key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9MJJHnMfn2+H4xL4YaPDA4RpJqUq\nkCmRCBnYERxZanmcpzQSXs1X/AljlKkbJ8qpVIW4clayyef9gWhFbNHWAA==\n-----END PUBLIC KEY-----\n", "is_current": false }, { "key_identifier": "bcb53661c06b4728e59d897fb6165d5c9cda0fd9cdf9d09ead458168deb7518c", "key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEYAGMWO8XgCamYKMJS6jc/qgvSlAd\nAjPuDPRcXU22YxgBrz+zoN19MzuRyW87qEt9/AmtoNP5GrobzUvQSyJFVw==\n-----END PUBLIC KEY-----\n", "is_current": true } ] }

注意,提供多个密钥并非必需。在披露时,PyPI 不会接受未标记为当前有效(is_current: true)的密钥的响应。

路由

上报密钥

路由:POST /_/secrets/disclose-token

接受一个或多个任意 API 令牌的上报,并包含发现位置详情。消息体为 JSON 数组,包含一个或多个对象,每个对象代表一次密钥匹配。

每个密钥匹配对象的键包括:

  • token:密钥匹配的值(必填)
  • type:找到的令牌类型(必填)
  • url:发现匹配的公开 URL(必填)

目前 type 的唯一有效值为 "pypi_api_token"。

可以附加其他字段,但会被忽略。

请求示例:

POST /_/secrets/disclose-token HTTP/1.1 Host: pypi.org Some-Public-Key-Identifier: ... Some-Public-Key-Signature: ... [ { "token": "pypi-NMIfyYncKcRALEXAMPLE...", "type": "pypi_api_token", "url": "https://github.com/octocat/Hello-World/blob/12345600b9cbe38a219f39a9941c9319b600c002/foo/bar.txt", } ]

状态码:

  • 204 No Content - 我们已确认收到请求,但不会评论处理结果。
  • 400 Bad Request - 请求格式存在某种错误,我们无法处理该上报。响应体将包含更详细的错误信息。该令牌未被上报,应重新提交。

评论 (0)