Filtre de données sensibles

Sensitive Data Filter est un processeur de spans qui masque les informations sensibles de vos traces dans le pipeline de traitement, avant leur exportation. Ainsi, les mots de passe, clés d'API, jetons et autres données confidentielles ne quittent jamais votre application et ne sont pas stockés sur les plateformes d'observabilité.

Configuration par défaut

Sensitive Data Filter est inclus dans la configuration d'observabilité recommandée :

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',
  }),
})

Avec la configuration par défaut, le filtre masque les noms de champs sensibles courants suivants :

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

remarque

La correspondance des champs ne tient pas compte de la casse et normalise les séparateurs. Par exemple, api-key, api_key et Api Key sont tous traités comme apikey.

Fonctionnement

Sensitive Data Filter traite les spans avant leur envoi aux exporters et analyse les éléments suivants :

• Attributs — métadonnées et propriétés du span
• Métadonnées — métadonnées personnalisées associées aux spans
• Entrées — données envoyées aux Agents, aux outils et aux LLM
• Sorties — réponses et résultats
• Informations d'erreur — traces de pile et détails des erreurs

Lorsqu'un champ sensible est détecté, sa valeur est remplacée par [REDACTED] par défaut. Le filtre traite en toute sécurité les objets imbriqués, les tableaux et les références circulaires.

Configuration personnalisée

Vous pouvez personnaliser les champs masqués ainsi que l'affichage du masquage :

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'
          }),
        ],
      },
    },
  }),
})

Styles de masquage

Le filtre prend en charge deux styles de masquage :

Masquage complet (par défaut)

Remplace la valeur entière par un jeton fixe :

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

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

Masquage partiel

Affiche les trois premiers et les trois derniers caractères, ce qui facilite le débogage sans exposer les valeurs complètes :

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

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

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

Les valeurs de moins de sept caractères sont entièrement masquées afin d'éviter toute fuite d'informations.

Règles de correspondance des champs

Le filtre utilise une correspondance intelligente des champs :

1. Insensible à la casse : APIKey, apikey et ApiKey correspondent tous
2. Indépendante des séparateurs : api-key, api_key et apiKey sont traités de manière identique
3. Correspondance exacte : après normalisation, les champs doivent correspondre exactement
   • token correspond à token, Token et TOKEN
   • token ne correspond ni à promptTokens ni à tokenCount

Traitement des objets imbriqués

Le filtre traite récursivement les structures imbriquées :

// 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]"
    }
  }
}

Considérations relatives aux performances

Sensitive Data Filter est conçu pour être léger et efficace :

• Traitement synchrone : aucune opération asynchrone et un impact minimal sur la latence
• Gestion des références circulaires : traitement sûr des graphes d'objets complexes
• Récupération après erreur : en cas d'échec du filtrage, le champ est remplacé par un marqueur d'erreur au lieu de provoquer un arrêt brutal

Désactiver le filtre

Si vous devez désactiver le filtrage des données sensibles, ce qui est déconseillé en production :

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()],
      },
    },
  }),
})

attention

Désactivez le filtrage des données sensibles uniquement dans des environnements contrôlés. Ne le désactivez jamais lorsque vous envoyez des traces à des services externes ou à un stockage partagé.

Cas d'utilisation courants

Applications de santé

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

Services financiers

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

Gestion des erreurs

Si le filtre rencontre une erreur lors du traitement d'un champ, il remplace ce champ par un marqueur d'erreur sûr :

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

Les erreurs de traitement n'empêchent ainsi pas l'exportation des traces et ne provoquent pas l'arrêt brutal de l'application.

Voir aussi

• API SensitiveDataFilter