sentry-security-basics

What this skill does

# Sentry Security Basics

## Overview

Configure Sentry's security posture: PII scrubbing with `beforeSend`, built-in data scrubbing, IP anonymization, browser SDK URL filtering, DSN vs auth token handling, CSP reporting, and GDPR data deletion. Covers both client-side (SDK) and server-side (dashboard) controls.

## Prerequisites

- Sentry project created with Owner or Admin role
- `@sentry/node` >= 8.x or `@sentry/browser` >= 8.x installed (or `sentry-sdk` >= 2.x for Python)
- Compliance requirements identified (GDPR, SOC 2, HIPAA, CCPA)
- List of sensitive data patterns for your domain (PII fields, API keys, tokens)

## Instructions

### Step 1 — Understand DSN vs Auth Token Security

The DSN (Data Source Name) is a **client-facing identifier** — it tells the SDK where to send events. It is NOT a secret.

```
https://<public-key>@o<org-id>.ingest.us.sentry.io/<project-id>
```

- The DSN **cannot** read data, delete events, or modify settings
- It is safe to ship in client-side JavaScript bundles
- Restrict abuse via **Allowed Domains** (Project Settings > Client Keys > Configure)

Auth tokens **ARE secrets** — they grant API access to read/write/delete data:

```bash
# NEVER commit auth tokens — store in CI secrets or vault
# GitHub Actions: Settings > Secrets > SENTRY_AUTH_TOKEN
# GitLab CI: Settings > CI/CD > Variables (protected + masked)

# Generate tokens with MINIMAL scopes:
#   CI releases:   project:releases, org:read
#   Issue triage:  project:read, event:read
#   NEVER:         org:admin, member:admin in CI

# Rotate tokens quarterly — revoke unused tokens immediately
# Create separate tokens per pipeline (staging vs production)
```

### Step 2 — Disable Default PII Collection

`sendDefaultPii` defaults to `false` — but always set it explicitly so intent is clear:

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  sendDefaultPii: false, // explicit: no IPs, no cookies, no user-agent
});
```

When `sendDefaultPii: false` (default):

- **No IP addresses** attached to events
- **No cookies** sent in request data
- **No user-agent** strings in request headers
- **No request body** data captured
- User context must be set manually via `Sentry.setUser()`

```python
# Python equivalent
import sentry_sdk

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    send_default_pii=False,  # default, but be explicit
)
```

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

`beforeSend` runs before every event leaves the client. Use it to strip PII that leaks into error messages, request data, or breadcrumbs:

```typescript
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  sendDefaultPii: false,

  beforeSend(event, hint) {
    // --- Scrub sensitive headers ---
    if (event.request?.headers) {
      delete event.request.headers['Authorization'];
      delete event.request.headers['Cookie'];
      delete event.request.headers['X-Api-Key'];
      delete event.request.headers['X-Auth-Token'];
    }

    // --- Scrub request body fields ---
    if (event.request?.data) {
      try {
        const data = typeof event.request.data === 'string'
          ? JSON.parse(event.request.data)
          : { ...event.request.data };

        const sensitiveKeys = [
          'password', 'passwd', 'secret', 'token',
          'ssn', 'credit_card', 'card_number', 'cvv',
          'api_key', 'apiKey', 'access_token', 'refresh_token',
        ];
        for (const key of Object.keys(data)) {
          if (sensitiveKeys.some(s => key.toLowerCase().includes(s))) {
            data[key] = '[REDACTED]';
          }
        }
        event.request.data = JSON.stringify(data);
      } catch {
        // non-JSON body — leave as-is
      }
    }

    // --- Scrub PII from exception messages ---
    if (event.exception?.values) {
      for (const exc of event.exception.values) {
        if (exc.value) {
          // Email addresses
          exc.value = exc.value.replace(
            /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
            '[EMAIL_REDACTED]'
          );
          // IPv4 addresses
          exc.value = exc.value.replace(
            /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/g,
            '[IP_REDACTED]'
          );
          // Credit card numbers (with optional separators)
          exc.value = exc.value.replace(
            /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g,
            '[CC_REDACTED]'
          );
          // Bearer tokens in messages
          exc.value = exc.value.replace(
            /Bearer\s+[A-Za-z0-9\-._~+/]+=*/g,
            'Bearer [TOKEN_REDACTED]'
          );
        }
      }
    }

    // --- Scrub user context ---
    if (event.user) {
      delete event.user.email;
      delete event.user.ip_address;
      // Keep event.user.id for issue grouping (non-PII identifier)
    }

    return event;
  },
});
```

Python equivalent using `before_send`:

```python
import re

def before_send(event, hint):
    # Scrub emails from exception messages
    if 'exception' in event:
        for exc in event['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_REDACTED]',
                    exc['value']
                )
                exc['value'] = re.sub(
                    r'\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b',
                    '[IP_REDACTED]',
                    exc['value']
                )

    # Strip user PII
    if 'user' in event:
        event['user'].pop('email', None)
        event['user'].pop('ip_address', None)

    # Scrub request headers
    request = event.get('request', {})
    headers = request.get('headers', {})
    for key in ['Authorization', 'Cookie', 'X-Api-Key']:
        headers.pop(key, None)

    return event

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

### Step 4 — Server-Side Data Scrubbing Rules

Configure in **Project Settings > Security & Privacy**:

| Setting | What it does |
|---------|-------------|
| **Data Scrubber** | Auto-scrubs fields matching common PII patterns (enabled by default) |
| **Sensitive Fields** | Custom field names to always scrub: `password`, `ssn`, `credit_card_number`, `api_key`, `secret`, `token`, `authorization` |
| **Safe Fields** | Fields excluded from scrubbing (e.g., `transaction_id`, `correlation_id`) |
| **Scrub IP Addresses** | Removes or zeroes IP addresses on all events |
| **Scrub Credit Cards** | Detects and removes card number patterns |

Organization-wide defaults: **Organization Settings > Security & Privacy** applies to all projects unless overridden at project level.

Advanced scrubbing rules (regex-based) can target specific event paths:

```
# Example server-side rules (configure in UI):
# Pattern: [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}
# Target:  $message, $error.value, $extra.**
# Action:  Replace with [Filtered]

# Pattern: \b\d{3}-\d{2}-\d{4}\b
# Target:  $extra.**, $contexts.**
# Action:  Replace with [Filtered] (SSN pattern)
```

### Step 5 — Browser SDK URL Filtering

Use `denyUrls` and `allowUrls` to control which scripts generate captured errors:

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

  // Ignore errors from third-party scripts
  denyUrls: [
    /extensions\//i,           // Browser extensions
    /^chrome:\/\//i,           // Chrome internal
    /^chrome-extension:\/\//i, // Chrome extensions
    /^moz-extension:\/\//i,    // Firefox extensions
    /graph\.facebook\.com/i,   // Facebook SDK
    /connect\.facebook\.net/i, // Facebook SDK
    /cdn\.jsdelivr\.net/i,     // CDN-hosted third-party
  ],

  // Only capture errors from your own code
  allowUrls: [
    /https?:\/\/(www\.)?example\.com/i,
    /https?:\/\/staging\.example\.com/i,
  ],
});
```

Also configure **Allowed Domains** in **Project Settings > Client Keys (DSN) > Configure** to