0disoft/genai-telemetry-redactor

# GenAI 遥测脱敏器 状态：活跃 范围：后端 仓库类型：库 附加组件：SDK GenAI 遥测脱敏器是一个库和 SDK 接口，用于在敏感内容到达日志、span、事件或可观测性后端之前，将其从 LLM 遥测中脱敏。 该项目专注于 prompt、completion 和工具参数边界。它默认关闭内容捕获，将安全的元数据映射到 OpenTelemetry GenAI 约定，并报告脱敏计数和原因，而不保留原始用户内容。 ## 安装 ``` npm install genai-telemetry-redactor ``` ## 快速开始 ``` import { withRedactedTelemetry } from "genai-telemetry-redactor"; const result = await withRedactedTelemetry({ adapter: "openai-compatible", request: { model: "model_example", messages: [ { role: "user", content: "Contact user@example.invalid with token_example_value", }, ], }, telemetry: { operationName: "chat", providerName: "openai", requestModel: "model_example", }, }); if (!result.ok) { throw new Error(result.error.code); } console.log(result.value.redactedRequest); console.log(result.value.telemetry.attributes); ``` 该辅助函数返回脱敏后的请求和响应 payload 以及仅包含元数据的遥测属性。它不会调用模型提供商、拥有凭据、导出 span、存储 prompt，也不能保证完美的敏感数据检测。 ## 限制与报告说明 `maxDetectors` 限制了一次文本或对象键检查可以运行多少个检测器。`maxDetectorRuns` 限制了在类 JSON 遍历期间的累计检测器执行次数，包括对象键安全检查。`maxTotalDurationMs` 限制了整个脱敏操作，并在超出预算时以 `max_total_duration_exceeded` 执行失败关闭（fail closed）。 `createBufferedTextStreamRedactor` 是一个显式的最终刷新流处理辅助工具。它缓冲字符串块，在中间的 `push(chunk)` 结果中省略内容，并仅从 `close()` 返回脱敏后的内容。兼容 OpenAI 的流式适配器默认保持为仅元数据模式。 `createBuiltInRollingTextStreamRedactor` 是一个针对已审查内置检测器的低延迟、仅核心辅助工具。它仅通过安全的空格边界刷新脱敏文本，保留 bearer-scheme 上下文，并缓冲长无空格片段。它拒绝自定义检测器和配置文件；这些仍然需要使用最终刷新辅助工具。请等待每个 `push()` 和 `close()` 调用完成，因为重叠操作会导致失败关闭。 脱敏报告可能包含数值型 `timings`，例如操作持续时间、检测器持续时间和检测器运行计数。这些指标仅是安全的摘要：它们不包括匹配的值、原始内容、检测器 ID 或字段路径。 `onReport` 回调失败不会丢弃已经脱敏的结果。SDK 会返回一个 `report_callback_failed` 警告，以便调用者可以观察到回调失败，而无需导出部分或原始的 payload。 自定义 regex 检测器应遵循 `docs/security/custom-regex-redos-guidance.md`。长度限制和异步检测器超时是防护措施，但一旦运行了严重依赖回溯的模式，同步 JavaScript regex 评估就无法被抢占。 ## 可重用的脱敏配置 `createRedactionProfile(config)` 会验证并快照一个可重用的核心策略。成功的配置文件可以作为 `{ profile, signal? }` 传递给 `redactText`、`redactJsonLike`、`redactToolArguments` 和 `createBufferedTextStreamRedactor`。基于配置文件的操作会拒绝针对单次调用的检测器、限制或替换覆盖。 当有效的检测器集为空、检测器 ID 重复、限制无效，或者 `maxDetectors` 值小于配置的检测器数量时，配置文件的创建会安全地失败并返回 `invalid_redaction_profile`。配置文件保留了现有的失败关闭重叠策略；当存在自定义检测器时，它们不会添加检测器优先级或自动禁用内置功能。 ## 源代码文件 - AGENTS.md：agent 工作规则 - CHECKLIST.md：检查清单路由 - VALIDATION.md：验证名称和报告要求 - LICENSE：Apache-2.0 许可证 - SECURITY.md：安全报告和测试夹具（fixture）安全策略 - .agents/context-map.md：agent 路由映射 - docs/：设计、运营、架构和工程标准 - docs/product/02-spec.md：持久的产品契约 - docs/library/public-api.md：公共库 API 边界 - docs/sdk/public-api.md：SDK 集成边界 - docs/backend/06-logging-and-observability.md：遥测映射和内容捕获策略 - docs/engineering/04-security-baseline.md：安全和脱敏基准 - docs/non-goals/backend-placeholders/：搁置的 API 和数据库占位符，非活跃产品契约 - examples/：由契约运行器检查的可执行、仅模拟数据的 SDK 和适配器示例 - package.json, pnpm-workspace.yaml, tsconfig*.json, vitest.config.ts：包、构建和验证运行器设置 - packages/core/：初始的与提供商无关的脱敏核心 - packages/anthropic-messages/：针对 system、text、tool-use 和 tool-result 内容的结构化 Anthropic Messages 请求和响应适配器 - packages/openai-compatible/：结构化的兼容 OpenAI 的请求、响应和流式元数据适配器 - packages/otel/：仅包含元数据的 OpenTelemetry GenAI 映射辅助工具 - packages/sdk/：结合适配器脱敏和安全遥测元数据的调用者易用性辅助工具 - scripts/check-no-live-secrets.ts：针对类真实机密的仓库安全防护 - scripts/check-package-surface.ts：包导出和内部包表面防护 - scripts/check-package-artifact.ts：npm dry-run 包构建产物防护 - scripts/check-migration.ts：版本化公共契约和迁移指南防护 - scripts/check-performance.ts：有界合成热路径回归防护 - scripts/check-otel-genai-semconv-drift.ts：上游 semconv 新鲜度咨询检查 ## 仓库结构说明 - 库：此仓库类型负责公共 API 表面、包兼容性、语义化版本控制、迁移指南、分发构件以及面向使用者的弃用策略。 - SDK：此仓库类型负责公共 API、兼容性、示例、版本控制和使用者迁移。 ## MVP 边界 第一个有用的版本支持兼容 OpenAI 和 Anthropic Messages 的请求与响应结构、嵌套的工具参数与结果、小型检测器集、替换 token 策略以及安全的 OpenTelemetry GenAI 元数据映射。 当前的实现从 `packages/core` 开始：异步 `redactText`、`redactJsonLike`、`redactToolArguments`、`createBufferedTextStreamRedactor` 和 `createBuiltInRollingTextStreamRedactor`；针对电子邮件、bearer token、类 API-key 字符串和 URL 的内置检测器；仅类别的替换 token；脱敏报告；具有共享引用重用的保形类 JSON 遍历；以及失败关闭的检测器、遍历、缓冲流、循环引用、重叠和限制行为。 它还包括 `packages/openai-compatible`：无提供商 SDK 的请求和响应结构辅助工具，用于 `messages`、`prompt`、`input`、`choices`、completion 文本、消息内容和工具调用函数参数。不支持的结构会以 `unsupported_provider_shape` 失败关闭，格式错误的 JSON 工具参数会以 `malformed_tool_arguments` 失败关闭，流式事件返回仅元数据的 `streaming_content_omitted` 结果，而不是导出块内容。 `packages/anthropic-messages` 为 Anthropic Messages 网络传输结构添加了第二个无提供商 SDK 的适配器。它脱敏顶级 `system`、消息字符串、`text` 块、助手 `tool_use.input` 和用户 `tool_result.content`。未知或未经审查的内容块会失败关闭，而不是被直接复制。在专门的测试夹具证明其安全之前，图像、文档、搜索结果、思考和服务器工具块仍处于支持的适配器契约之外。 `packages/otel` 以 `mapRedactionReportToGenAIMetadata` 开启 OpenTelemetry 边界：这是一个纯粹的元数据映射器，它接收脱敏报告和安全的 GenAI 元数据候选项，保持禁用内容捕获，并导出官方的 GenAI 操作/提供商/模型/token 属性以及特定于库的 `genai_redactor.*` 脱敏元数据，而不接受原始提供商 payload 或 span 写入器对象。 `packages/sdk` 以 `withRedactedTelemetry` 开启 SDK 易用性边界：这是一个显式适配器辅助工具，用于脱敏兼容 OpenAI 或 Anthropic Messages 的请求和响应 payload，返回安全的遥测元数据，并在不拥有提供商凭据、重试、路由、传输、遥测导出器或 prompt 存储的情况下调用可选的报告回调。 `examples` 包含用于第一个安全集成路径的可执行 TypeScript 示例：兼容 OpenAI 的包装、Anthropic Messages 系统和文本脱敏、带报告回调的工具调用参数脱敏、自定义检测器注册、最终刷新和内置滚动脱敏，以及流式仅元数据处理。契约运行器针对构建的包导出导入这些示例，因此示例偏差被视为包契约失败。 MVP 不得成为遥测后端、模型网关、prompt 存储、法律合规产品或完整的 DLP 平台。 流式内容导出不属于第一个安全路径的一部分。在 ADR、滚动缓冲策略和块边界夹具证明脱敏行为之前，流式遥测必须保持仅元数据模式。 ## 仓库规范 生成 .editorconfig、.gitattributes 和 .gitignore 是为了控制行尾、二进制差异、本地文件、构建输出、缓存和机密文件。 ## 范围说明 运行时打包被确定为 Node.js `>=22.14.0`、仅限 ESM 的 TypeScript，以及一个 pnpm 工作区，其中包含一个名为 `genai-telemetry-redactor` 的初始 npm 包。 OpenTelemetry GenAI 语义约定源被固定为已审查的上游 Development 快照，因此官方的 `gen_ai.*` 映射是可重现的，并且自定义脱敏元数据保留在 `genai_redactor.*` 命名空间下。 包导出指向从 TypeScript 源发出的已编译 `dist` JavaScript 和声明文件。产品边界已经确定：在导出前进行脱敏，仅在显式选择加入时捕获内容，并且永远不要将脱敏视为完美的敏感数据发现。

标签：API集成, DLL 劫持, GET参数, GNU通用公共许可证, MITM代理, Node.js, OpenTelemetry, 可观测性, 大语言模型, 数据脱敏, 暗色界面, 用户代理, 自动化攻击