> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 敏感数据过滤器

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

## 默认配置

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

```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]`。过滤器能够安全处理嵌套对象、数组和循环引用。

## 自定义配置

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

```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：

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

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

### 部分脱敏

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

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

```json
// 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`

## 嵌套对象处理

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

```json
// 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 的设计轻量而高效：

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

## 禁用过滤器

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

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

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

## 常见用例

### 医疗保健应用

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

### 金融服务

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

## 错误处理

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

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

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

## 相关内容

- [SensitiveDataFilter API](https://mastra.zisheng.pro/reference/observability/tracing/processors/sensitive-data-filter)