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

# 敏感資料篩選器

Sensitive Data Filter 是一個 span 處理器，會在匯出前的處理管線中，遮蔽 Trace 內的敏感資料。這可確保密碼、API 金鑰、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 的 metadata 和屬性
- **Metadata** - 附加至 span 的自訂 metadata
- **輸入** - 傳送至 Agent、Tool 和 LLM 的資料
- **輸出** - 回應和結果
- **錯誤資料** - 堆疊追蹤和錯誤詳情

偵測到敏感欄位時，其值預設會替換為 `[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/zh-HK/reference/observability/tracing/processors/sensitive-data-filter)