Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/brightdata-security-basics/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill brightdata-security-basics. Copyright stays with the author (MIT).

Bright Data Security Basics

Overview

Security best practices for Bright Data zone credentials, API tokens, and webhook delivery. Bright Data credentials include Customer ID, zone passwords, and API tokens — all must be protected.

Prerequisites

• Bright Data zones configured
• Understanding of environment variables
• Access to Bright Data control panel

Instructions

Step 1: Credential Inventory

Step 2: Environment Variable Security

# .env (NEVER commit)
BRIGHTDATA_CUSTOMER_ID=c_abc123
BRIGHTDATA_ZONE=web_unlocker1
BRIGHTDATA_ZONE_PASSWORD=z_pass_xyz
BRIGHTDATA_API_TOKEN=abc123def456

# .gitignore
.env
.env.local
.env.*.local

# .env.example (safe to commit — no real values)
BRIGHTDATA_CUSTOMER_ID=
BRIGHTDATA_ZONE=
BRIGHTDATA_ZONE_PASSWORD=
BRIGHTDATA_API_TOKEN=

Step 3: Zone Isolation by Environment

Create separate zones per environment so staging credentials cannot access production proxy bandwidth:

// config/brightdata.ts
const ZONE_MAP = {
  development: 'web_unlocker_dev',
  staging: 'web_unlocker_staging',
  production: 'web_unlocker_prod',
} as const;

export function getZone(): string {
  const env = process.env.NODE_ENV || 'development';
  return process.env.BRIGHTDATA_ZONE || ZONE_MAP[env] || ZONE_MAP.development;
}

Step 4: Credential Rotation

# 1. Create new API token in Bright Data CP > Settings > API tokens
# 2. Update secrets in your deployment platform
# Vercel
vercel env rm BRIGHTDATA_API_TOKEN production
vercel env add BRIGHTDATA_API_TOKEN production

# AWS
aws secretsmanager update-secret --secret-id brightdata/api-token --secret-string "new_token"

# 3. Test new credentials
curl -H "Authorization: Bearer ${NEW_TOKEN}" \
  https://api.brightdata.com/zone/get_active_zones

# 4. Revoke old token in Bright Data CP

Step 5: Git Secret Scanning

# Pre-commit hook to catch leaked credentials
# .git/hooks/pre-commit
#!/bin/bash
if git diff --cached | grep -iE '(BRIGHTDATA_ZONE_PASSWORD|BRIGHTDATA_API_TOKEN)=.{5,}'; then
  echo "ERROR: Bright Data credentials detected in staged changes"
  exit 1
fi

Step 6: Webhook Delivery Security

When using webhook delivery for Web Scraper API results:

// Validate webhook came from Bright Data
function validateWebhookSource(req: Request): boolean {
  // Bright Data sends from known IPs — check docs for current list
  // Also validate the Authorization header you configured
  const authHeader = req.headers.get('Authorization');
  return authHeader === `Bearer ${process.env.BRIGHTDATA_WEBHOOK_SECRET}`;
}

Security Checklist

• Zone passwords in environment variables, never hardcoded
• .env files in .gitignore
• Separate zones per environment (dev/staging/prod)
• API tokens rotated quarterly
• Pre-commit hook blocks credential leaks
• Webhook endpoints validate Authorization header
• HTTPS-only for all proxy connections
• brd-ca.crt downloaded (public cert, safe in repo)

Output

The security review records zone ownership, credential storage decision, allowed targets/data classes, retention, and revocation owner. It must not include proxy usernames/passwords, full collection URLs, or response data.

Examples

Create a dedicated zone for one approved workload, store its credential in the secret manager, enforce egress and target allowlists in the application, and rotate immediately through the owner-controlled process if exposure is suspected. Verify that audit logs retain only an opaque request identifier and policy decision.

Error Handling

Resources

• Bright Data Security
• API Token Management
• Zone Management

Next Steps

For production deployment, see brightdata-prod-checklist.