敏感数据过滤器

Sensitive Data Filter 是一个 span processor，会在导出前的处理管道中对 Trace 的敏感信息进行脱敏。这样可以确保密码、API key、token 和其他机密数据永远不会离开应用，也不会存入可观测性平台。

默认配置

推荐的可观测性配置中包含 Sensitive Data Filter：

src/mastra/index.ts

import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive fields before export
        ],
      },
    },
  }),
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})

使用默认配置时，过滤器会对以下常见敏感字段名称进行脱敏：

• password
• token
• secret
• key
• apikey
• auth
• authorization
• bearer
• bearertoken
• jwt
• credential
• clientsecret
• privatekey
• refresh
• ssn

备注

字段匹配不区分大小写，并会规范化分隔符。例如，api-key、api_key 和 Api Key 都会被视为 apikey。

工作原理

Sensitive Data Filter 会在 span 发送给 exporter 前对其进行处理，并扫描以下内容：

• 属性——span 元数据和属性
• 元数据——附加到 span 的自定义元数据
• 输入——发送给 Agent、Tool 和 LLM 的数据
• 输出——响应和结果
• 错误信息——堆栈 Trace 和错误详情

检测到敏感字段时，其值默认会替换为 [REDACTED]。过滤器能够安全处理嵌套对象、数组和循环引用。

自定义配置

你可以自定义要脱敏的字段以及脱敏的显示方式：

src/mastra/index.ts

import { SensitiveDataFilter, MastraStorageExporter, Observability } from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'my-service',
        exporters: [new MastraStorageExporter()],
        spanOutputProcessors: [
          new SensitiveDataFilter({
            // Add custom sensitive fields
            sensitiveFields: [
              // Default fields
              'password',
              'token',
              'secret',
              'key',
              'apikey',
              // Custom fields for your application
              'creditCard',
              'bankAccount',
              'routingNumber',
              'email',
              'phoneNumber',
              'dateOfBirth',
            ],
            // Custom redaction token
            redactionToken: '***SENSITIVE***',
            // Redaction style
            redactionStyle: 'full', // or 'partial'
          }),
        ],
      },
    },
  }),
})

脱敏样式

过滤器支持两种脱敏样式：

完全脱敏（默认）

将整个值替换为固定 token：

// Before
{
  "apiKey": "sk-abc123xyz789def456",
  "userId": "user_12345"
}

// After
{
  "apiKey": "[REDACTED]",
  "userId": "user_12345"
}

部分脱敏

显示开头和末尾各 3 个字符，便于在不暴露完整值的情况下调试：

new SensitiveDataFilter({
  redactionStyle: 'partial',
})

// Before
{
  "apiKey": "sk-abc123xyz789def456",
  "creditCard": "4111111111111111"
}

// After
{
  "apiKey": "sk-…456",
  "creditCard": "411…111"
}

少于 7 个字符的值会完全脱敏，以防止信息泄露。

字段匹配规则

过滤器使用智能字段匹配：

1. 不区分大小写：APIKey、apikey 和 ApiKey 都会匹配
2. 忽略分隔符：api-key、api_key 和 apiKey 会被视为相同字段
3. 精确匹配：规范化后，字段必须完全匹配
   • token 匹配 token、Token、TOKEN
   • token 不匹配 promptTokens 或 tokenCount

嵌套对象处理

过滤器会递归处理嵌套结构：

// Before
{
  "user": {
    "id": "12345",
    "credentials": {
      "password": "SuperSecret123!",
      "apiKey": "sk-production-key"
    }
  },
  "config": {
    "auth": {
      "jwt": "eyJhbGciOiJIUzI1NiIs..."
    }
  }
}

// After
{
  "user": {
    "id": "12345",
    "credentials": {
      "password": "[REDACTED]",
      "apiKey": "[REDACTED]"
    }
  },
  "config": {
    "auth": {
      "jwt": "[REDACTED]"
    }
  }
}

性能注意事项

Sensitive Data Filter 的设计轻量而高效：

• 同步处理：不执行异步操作，对延迟影响极小
• 循环引用处理：安全处理复杂对象图
• 错误恢复：如果过滤失败，会将字段替换为错误标记，而不会使应用崩溃

禁用过滤器

如需禁用敏感数据过滤（不建议在生产环境中这样做）：

src/mastra/index.ts

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      debug: {
        serviceName: 'debug-service',
        spanOutputProcessors: [], // No processors, including no SensitiveDataFilter
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})

注意

只能在受控环境中禁用敏感数据过滤。向外部服务或共享存储发送 Trace 时，绝不能禁用它。

常见用例

医疗保健应用

new SensitiveDataFilter({
  sensitiveFields: [
    // HIPAA-related fields
    'ssn',
    'socialSecurityNumber',
    'medicalRecordNumber',
    'mrn',
    'healthInsuranceNumber',
    'diagnosisCode',
    'icd10',
    'prescription',
    'medication',
  ],
})

金融服务

new SensitiveDataFilter({
  sensitiveFields: [
    // PCI compliance fields
    'creditCard',
    'ccNumber',
    'cardNumber',
    'cvv',
    'cvc',
    'securityCode',
    'expirationDate',
    'expiry',
    'bankAccount',
    'accountNumber',
    'routingNumber',
    'iban',
    'swift',
  ],
})

错误处理

如果过滤器在处理字段时遇到错误，会将该字段替换为安全错误标记：

{
  "problematicField": {
    "error": {
      "processor": "sensitive-data-filter"
    }
  }
}

因此，处理错误不会阻止 Trace 导出，也不会导致应用崩溃。

相关内容

• SensitiveDataFilter API