sentry-data-handling

What this skill does

# Sentry Data Handling

Configure PII scrubbing, GDPR compliance, data retention, and audit controls for Sentry. This skill covers client-side filtering with `beforeSend`, server-side scrubbing rules, data subject erasure via API, and SOC 2 compliance patterns.

## Overview

Sentry captures error context that often contains personally identifiable information (PII) — emails in stack traces, credit card numbers in request bodies, IP addresses in headers. Production deployments must scrub this data at two layers: client-side via `beforeSend` hooks (before data leaves the application) and server-side via Sentry's built-in Data Scrubber (defense in depth). GDPR requires additional controls: consent-based initialization, data subject deletion endpoints, and a signed Data Processing Agreement. This skill implements all three layers with TypeScript and Python examples, plus verification tests to prove scrubbing works end-to-end.

## Prerequisites

- Sentry SDK v8 installed and initialized (`@sentry/node` or `sentry-sdk`)
- Sentry project with **Admin** or **Owner** role (required for Security & Privacy settings)
- Compliance requirements documented (GDPR, HIPAA, PCI-DSS, or SOC 2)
- Auth token with `project:write` and `org:admin` scopes for API operations
- Data Processing Agreement signed at https://sentry.io/legal/dpa/ (GDPR requirement)

## Instructions

### Step 1 — Client-Side PII Scrubbing with beforeSend

The first defense layer prevents PII from leaving your application. Configure `beforeSend`, `beforeSendTransaction`, and `beforeBreadcrumb` hooks during SDK initialization:

```typescript
import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,

  // CRITICAL: disable automatic PII collection
  // When false, Sentry will NOT capture IP addresses, cookies, or user-agent
  sendDefaultPii: false,

  beforeSend(event) {
    return scrubEvent(event);
  },

  beforeSendTransaction(event) {
    return scrubEvent(event);
  },

  beforeBreadcrumb(breadcrumb) {
    if (breadcrumb.data) {
      const sensitiveKeys = ['password', 'token', 'secret', 'api_key', 'authorization'];
      for (const key of sensitiveKeys) {
        if (breadcrumb.data[key]) {
          breadcrumb.data[key] = '[REDACTED]';
        }
      }
    }
    return breadcrumb;
  },
});
```

Implement the `scrubEvent` function to strip PII from headers, request bodies, error messages, and user context:

```typescript
function scrubEvent(event: Sentry.Event): Sentry.Event | null {
  // Strip sensitive headers
  if (event.request?.headers) {
    const redactHeaders = ['Authorization', 'Cookie', 'X-Api-Key', 'X-Auth-Token'];
    for (const header of redactHeaders) {
      delete event.request.headers[header];
    }
  }

  // Scrub request body fields
  if (event.request?.data) {
    const data = typeof event.request.data === 'string'
      ? safeJsonParse(event.request.data)
      : event.request.data;

    if (data && typeof data === 'object') {
      scrubObject(data as Record<string, unknown>);
      event.request.data = JSON.stringify(data);
    }
  }

  // Scrub PII patterns from error messages
  if (event.exception?.values) {
    for (const exc of event.exception.values) {
      if (exc.value) {
        exc.value = scrubPiiPatterns(exc.value);
      }
    }
  }

  // Reduce user context to anonymous ID only
  if (event.user) {
    event.user = { id: event.user.id };
  }

  return event;
}

function scrubObject(obj: Record<string, unknown>): void {
  const sensitiveKeys = [
    'password', 'passwd', 'secret', 'token', 'api_key', 'apiKey',
    'ssn', 'social_security', 'credit_card', 'cc_number', 'cvv',
    'email', 'phone', 'address', 'dob', 'date_of_birth',
  ];

  for (const key of Object.keys(obj)) {
    if (sensitiveKeys.some(sk => key.toLowerCase().includes(sk))) {
      obj[key] = '[REDACTED]';
    } else if (typeof obj[key] === 'string') {
      obj[key] = scrubPiiPatterns(obj[key] as string);
    } else if (typeof obj[key] === 'object' && obj[key] !== null) {
      scrubObject(obj[key] as Record<string, unknown>);
    }
  }
}

function scrubPiiPatterns(str: string): string {
  return str
    .replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[EMAIL]')
    .replace(/\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{1,7}\b/g, '[CC_NUMBER]')
    .replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[SSN]')
    .replace(/\b(\+1)?[\s-]?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}\b/g, '[PHONE]');
}

function safeJsonParse(str: string): unknown {
  try { return JSON.parse(str); } catch { return null; }
}
```

**Python equivalent** — use the same `before_send` pattern:

```python
import sentry_sdk
import re

def scrub_event(event, hint):
    """Remove PII from Sentry events before transmission."""
    # Strip sensitive headers
    request = event.get("request", {})
    headers = request.get("headers", {})
    for key in ["Authorization", "Cookie", "X-Api-Key"]:
        headers.pop(key, None)

    # Scrub user context to anonymous ID
    user = event.get("user")
    if user:
        event["user"] = {"id": user.get("id")}

    # Scrub PII patterns from exception messages
    for exc in event.get("exception", {}).get("values", []):
        if exc.get("value"):
            exc["value"] = re.sub(
                r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}",
                "[EMAIL]", exc["value"]
            )

    return event

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    send_default_pii=False,
    before_send=scrub_event,
    traces_sample_rate=0.1,
)
```

### Step 2 — Server-Side Data Scrubbing and IP Anonymization

Server-side scrubbing acts as defense in depth. Configure in **Project Settings > Security & Privacy**:

1. **Enable Data Scrubber** — automatically redacts values matching common PII field names (password, token, secret)
2. **Custom Sensitive Fields** — add project-specific fields:
   - `password`, `secret`, `token`, `api_key`, `ssn`, `credit_card`, `cvv`, `authorization`
3. **Safe Fields** — fields that must never be scrubbed:
   - `transaction_id`, `order_id`, `request_id`, `trace_id`
4. **Scrub IP Addresses** — enable to remove client IPs from all events
5. **Scrub Credit Cards** — detect and remove card number patterns

For advanced regex-based rules, navigate to **Project Settings > Security & Privacy > Advanced Data Scrubbing**:

```
# Remove credit card patterns from all string fields
[Remove] [Regex: \d{4}-\d{4}-\d{4}-\d{4}] from [$string]

# Remove email addresses everywhere
[Remove] [Regex: \b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b] from [$string]

# Remove SSN patterns
[Remove] [Regex: \b\d{3}-\d{2}-\d{4}\b] from [$string]

# Mask passwords in request bodies
[Mask] [Password] from [extra.request_body]

# Replace credit card data everywhere with placeholder
[Replace] [Credit card] with [REDACTED] from [**]
```

**Data forwarding** — if forwarding events to external systems (Splunk, BigQuery), apply the same scrubbing rules at the destination. Configure forwarding in **Project Settings > Data Forwarding**.

**Data retention** — configure in **Organization Settings > Subscription > Data Retention**:

| Plan | Default retention | Maximum retention |
|------|-------------------|-------------------|
| Developer | 30 days | 30 days |
| Team | 90 days | 90 days |
| Business | 90 days | 365 days |
| Enterprise | 90 days | Custom |

### Step 3 — GDPR Compliance and Data Subject Requests

**Right to be Informed** — document Sentry usage in your privacy policy. Disclose what data is collected (stack traces, device info, anonymized user IDs) and the legal basis (legitimate interest in application reliability).

**Consent-based initialization** — for strict GDPR compliance, gate Sentry on user consent:

```typescript
function initSentryWithConsent(hasConsent: boolean): void {
  if (!hasConsent) {
    // Do not initialize Sentry — no data sent
    return;
  }

  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    sendDefaultPii: false,
    beforeSend: scrubEvent,
  });