spidercob-dlp

DLP (Data Loss Prevention) scanner for files and text. Detects PII (SSNs, passport numbers, credit cards, emails, phone numbers), secrets (AWS keys, GitHub tokens, private keys, Slack tokens), and sensitive data. Powered by the Spidercob API.

Install

# Global
npm install -g spidercob-dlp

# Dev dependency (CI/CD)
npm install --save-dev spidercob-dlp

# One-off
npx spidercob-dlp --help

Auth

All scans require a Spidercob account. Set credentials via env vars (recommended for CI) or CLI flags.

# Option 1: API token (preferred)
export SPIDERCOB_TOKEN="eyJhbGciOi..."

# Option 2: Username + password (auto-exchanges for token)
export SPIDERCOB_USERNAME="[email protected]"
export SPIDERCOB_PASSWORD="secret"

# Self-hosted / on-prem
export SPIDERCOB_API_URL="https://dlp.your-company.com"

CLI

# Scan a file
spidercob-dlp report.pdf
spidercob-dlp data.csv

# Multiple files
spidercob-dlp src/**/*.py

# Scan staged files (git pre-commit)
git diff --cached --name-only | xargs spidercob-dlp --fail-on=HIGH

# Only fail on CRITICAL
spidercob-dlp dump.sql --fail-on=CRITICAL

# JSON output
spidercob-dlp data.csv --json
spidercob-dlp data.csv --json | jq '.findings[] | select(.severity=="CRITICAL")'

# Malware scan track instead of DLP
spidercob-dlp upload.zip --track=sentinel

# Quiet (only print if findings found — useful in CI logs)
spidercob-dlp report.pdf --quiet

Exit codes: 0 = clean, 1 = findings at threshold, 2 = error

Programmatic API

const { scanFile, scanText, scanFiles } = require('spidercob-dlp');

// Scan a file
const result = await scanFile({
  filePath: './reports/q4-financials.pdf',
  token: process.env.SPIDERCOB_TOKEN,
});

console.log(result.verdict);      // "BLOCK"
console.log(result.riskLevel);    // "CRITICAL"
console.log(result.threatScore);  // 95
console.log(result.hasFindings);  // true

for (const f of result.findings) {
  console.log(f.severity, f.type, f.description);
  // "CRITICAL"  "credit_card"  "Presidio: CREDIT_CARD"
}

// Scan raw text
const r = await scanText({
  text: 'Customer SSN: 123-45-6789',
  fileName: 'customer-data.txt',
  token: process.env.SPIDERCOB_TOKEN,
});

// Scan multiple files (parallel, 3 at a time)
const batch = await scanFiles({
  files: ['./src/config.py', './exports/users.csv', './docs/api-guide.pdf'],
  token: process.env.SPIDERCOB_TOKEN,
  concurrency: 3,
});

console.log(batch.filesScanned);   // 3
console.log(batch.hasFindings);    // true
console.log(batch.allFindings);    // aggregated findings from all files

CI/CD Integration

GitHub Actions

name: DLP Scan
on: [push, pull_request]

jobs:
  dlp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Scan changed files for sensitive data
        env:
          SPIDERCOB_TOKEN: ${{ secrets.SPIDERCOB_TOKEN }}
        run: |
          # Scan files changed in this PR
          git diff --name-only origin/${{ github.base_ref }}...HEAD \
            | grep -E '\.(py|js|ts|csv|json|txt|pdf|sql)$' \
            | xargs -r npx spidercob-dlp --fail-on=HIGH --quiet

GitLab CI

dlp-scan:
  image: node:20-alpine
  script:
    - git diff --name-only $CI_MERGE_REQUEST_DIFF_BASE_SHA...HEAD
        | xargs npx spidercob-dlp --fail-on=HIGH --json > dlp-report.json
  artifacts:
    paths: [dlp-report.json]
    when: always
  rules:
    - if: $CI_MERGE_REQUEST_ID

package.json scripts

{
  "scripts": {
    "dlp:scan": "spidercob-dlp src/ --fail-on=HIGH",
    "dlp:exports": "spidercob-dlp exports/**/*.csv --fail-on=MEDIUM"
  }
}

Git Hooks

Pre-commit (scans staged files)

cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
# Scan staged files for PII/secrets before committing
staged=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(py|js|ts|csv|json|txt|sql)$')
if [ -n "$staged" ]; then
  echo "$staged" | xargs npx spidercob-dlp --fail-on=HIGH --quiet
  if [ $? -ne 0 ]; then
    echo "[spidercob-dlp] Commit blocked: sensitive data detected. Review findings above."
    exit 1
  fi
fi
EOF
chmod +x .git/hooks/pre-commit

Pre-push (broader scan)

cat > .git/hooks/pre-push << 'EOF'
#!/bin/sh
npx spidercob-dlp src/ exports/ --fail-on=CRITICAL --quiet
EOF
chmod +x .git/hooks/pre-push

With Husky

npm install --save-dev husky
npx husky add .husky/pre-commit \
  "git diff --cached --name-only | grep -E '\\.(py|csv|sql)$' | xargs -r npx spidercob-dlp --fail-on=HIGH"

What Gets Detected

| Category | Examples | |---|---| | PII | SSN, passport, credit card, IBAN, email, phone, person names | | Secrets | AWS keys (AKIA/ASIA), GitHub tokens (ghp_), private keys (RSA/EC), Slack tokens (xoxb-) | | Google | API keys (AIza...) | | Financial | Credit cards, IBANs, bank account numbers | | Medical | Medical license numbers | | Network | IP addresses |

Scan Tracks

| Track | Use case | |---|---| | guardian | DLP — PII, secrets, sensitive text (default) | | sentinel | File Guard — malware, YARA rules, ClamAV |

Self-Hosted / On-Prem

Point the SDK at your own Spidercob instance:

export SPIDERCOB_API_URL="https://dlp.your-company.internal"
spidercob-dlp report.pdf

Or in code:

const result = await scanFile({
  filePath: './report.pdf',
  apiUrl: 'https://dlp.your-company.internal',
  token: 'eyJ...',
});