敏感資料篩選器

Sensitive Data Filter 是一個 span Processor，會在匯出前的處理管線中，遮蔽 Trace 內的敏感資料。這可確保密碼、API 金鑰、token 及其他機密資料絕不會離開你的應用程式，也不會儲存至 Observability 平台。

預設設定

建議的 Observability 設定已包括 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 的 metadata 和屬性
• Metadata - 附加至 span 的自訂 metadata
• 輸入 - 傳送至 Agent、Tool 和 LLM 的資料
• 輸出 - 回應和結果
• 錯誤資料 - 堆疊追蹤和錯誤詳情

偵測到敏感欄位時，其值預設會替換為 [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