指南OneMux

诊断 OpenAI API 故障,同时避免凭据泄露

实用指南:如何利用有效信号排查 OpenAI API 故障,同时保护 API 密钥、限制权限,并制定凭据轮换计划。

AI

摘要 · TL;DR

OpenAI API 请求失败时,应保留足够的证据来识别故障,同时避免记录机密或敏感内容。按用途分开凭据,限制凭据的使用范围,并在事件发生前演练轮换流程。

核心要点

  • 记录请求结果和安全标识符,不要记录 API 密钥、授权标头或完整的提示词和响应。
  • 不同职责使用不同凭据,并且只授予工作负载所需的权限。
  • 将状态、错误类别、耗时和请求标识符作为诊断信号,而不是暴露请求内容的理由。
  • 可执行的轮换计划应包括更换、部署、验证和撤销旧凭据。
文章目录 (5)

如果日志保留了运行证据,同时不包含凭据或不必要的客户数据,OpenAI API 事件就更容易诊断。先从故障信号入手,例如非成功状态、超时或应用异常,再将其与请求标识符和受影响的部署关联起来。不要让不受信任的代码或智能体生成的代码能够读取 API 密钥。

构建安全的诊断记录

对于每次 API 调用,只记录回答以下四个问题所需的信息:事件何时发生、哪个工作负载发起了请求、发生了哪类故障,以及能否将该事件与提供商侧证据关联起来?

有用的记录可以包含时间戳、自有的不透明操作 ID、端点类别、HTTP 状态、耗时、重试次数,以及提供商返回时给出的请求 ID。记录异常类或经过清理的错误类别,而不要直接转储异常对象:某些库会在异常文本中包含请求详情。除非经过审查的流程确认有明确需求并落实了适当保护措施,否则不要将提示词、响应、授权标头以及原始请求或响应正文写入常规日志。

以下 Python 代码是示意模式,并非经过测试的集成方案。机密获取函数和响应处理方式取决于你的应用和 SDK。此模式特意避免记录请求正文或凭据。

import logging
import time
import uuid

logger = logging.getLogger(__name__)


def send_request(client, payload):
    operation_id = str(uuid.uuid4())
    started = time.monotonic()

    try:
        result = client.responses.create(**payload)
        logger.info(
            "openai_request_succeeded",
            extra={
                "operation_id": operation_id,
                "elapsed_ms": round((time.monotonic() - started) * 1000),
                "provider_request_id": getattr(result, "_request_id", None),
            },
        )
        return result
    except Exception as exc:
        # Do not log str(exc), request headers, or payload here.
        logger.error(
            "openai_request_failed",
            extra={
                "operation_id": operation_id,
                "elapsed_ms": round((time.monotonic() - started) * 1000),
                "exception_type": type(exc).__name__,
            },
        )
        raise

采用此模式前,请确认客户端如何提供请求 ID,以及异常消息是否可能包含敏感数据。在链路追踪、错误报告、代理日志和支持包中也应用相同的脱敏规则;仅清理应用日志并不足够。

利用故障信号缩小排查范围

状态码或异常只是线索,并不能给出完整诊断。部署后认证失败突然增多,可能意味着凭据缺失、无效或传递方式不正确。速率限制响应增加,可能说明请求量或并发发生了变化。超时可能与网络访问、上游延迟或客户端超时时间过短有关。如果提供商已成功响应,但用户请求仍然失败,问题可能出在应用侧解析或下游环节。

比较部署前后的故障率和延迟,并按工作负载或环境拆分结果。不要按机密值分组,也不要为了“确认”两个系统是否共用密钥而记录密钥。如果需要核实服务使用的是哪个凭据,请通过经过授权的方式检查其密钥管理器引用和部署配置。

分离并限制凭据

OpenAI 的沙箱安全指南建议使用隔离的计算环境;对于不得共享数据的工作负载,应使用相互隔离的环境;并为应用或工作负载设置专用的 OpenAI 项目。指南还区分了应用 API 密钥和执行器环境密钥:后者用于连接环境,不授权其他 API 操作。指南列出了 Agents API 会话、推理和保管库管理所需的具体权限;应只为工作负载分配必要权限。请参阅 OpenAI 的沙箱安全指南。

将应用密钥保存在智能体生成的代码无法读取的环境之外。不要将密钥嵌入源代码、容器镜像或日志中。对于第三方凭据,指南建议将机密保存在环境之外,并在适用情况下通过受信任的机制提供,例如代理或基于保管库的方案。注入环境的机密仍可被其中运行的代码访问,因此仅靠注入并不能保证机密无法被读取。

制定凭据轮换流程

请在事件发生前写下并演练以下步骤:

  1. **准备:**确认凭据的所有者、权限、使用该凭据的服务,以及它在密钥管理器中的存放位置。明确由谁负责创建、部署和撤销凭据。
  2. **更换:**创建一个仅具备所需权限的替代凭据。将其存储在获准的密钥管理器中,不要放在工单、聊天记录或源代码库里。
  3. **部署:**通过常规发布流程更新相关工作负载。如果允许新旧凭据短暂并存,只在最低限度的验证窗口内保留旧凭据。
  4. **验证:**发送低风险请求,并检查请求是否成功、故障率和日志。确认没有服务仍依赖旧凭据。
  5. **撤销并复核:**撤销旧凭据。如果怀疑凭据已泄露,应优先撤销,并调查受影响的工作负载和日志,而不是等到常规轮换日期。

如果轮换后请求立即失败,请检查服务是否确实收到了新机密、是否已经重启或刷新机密访问,以及替代凭据是否具备正确权限。不要在尚未确认所需操作的情况下,通过授予广泛访问权限来解决权限错误。

简明事件检查清单

  • 故障是否仅影响某个工作负载、环境或发布版本?
  • 状态、延迟、重试次数和安全的请求标识符是否呈现出某种规律?
  • 日志是否未包含授权标头、密钥以及不必要的提示词或响应内容?
  • 凭据是否通过获准的密钥管理路径存储和提供?
  • 能否在不更改无关服务的情况下更换并撤销凭据?

目标不是记录所有信息,而是保留足够的安全证据,以区分凭据、流量、网络和应用故障;如果怀疑凭据已泄露,也能迅速轮换。

常见问题

OpenAI API 请求失败时应记录哪些信息?

记录时间戳、自有的不透明操作 ID、端点类别、HTTP 状态或经过清理的错误类别、耗时、重试次数,以及提供商提供的请求 ID(如果有)。默认情况下,不要记录 API 密钥、授权标头或完整的请求和响应正文。

是否应让智能体生成的代码访问 API 密钥?

不要向不需要应用 API 密钥的代码暴露该密钥。OpenAI 的沙箱安全指南建议将应用密钥保存在环境之外,并说明智能体生成的代码可以访问其运行环境中的文件和凭据。

何时应轮换或撤销 OpenAI API 密钥?

按照明确的运维计划轮换凭据;如果怀疑凭据已泄露,应立即撤销。完整的流程应涵盖更换、部署、验证和撤销旧凭据。

为什么凭据轮换后请求可能失败?

工作负载可能仍在使用缓存的密钥或旧机密,可能尚未刷新配置,也可能是新凭据缺少必要权限。请核实已部署的机密引用和所需权限,但不要记录凭据本身。

相关文章