@privacyscrubber/sdk 2.4.1 → 2.4.3

package/sarif.cjs

@@ -0,0 +1,388 @@
+// ────────────────────────────────────────────────────────────────────────
+// cli/sarif.js
+//   SARIF 2.1.0 emitter for PrivacyScrubber CLI & CI/CD Pipelines
+//   • Zero Raw PII Egress — only normalized types, rules, and fingerprints
+//   • Fully compatible with GitHub Code Scanning, GitLab Code Quality, Azure DevOps
+//   • Zero external dependencies — pure Node.js built-ins (crypto, fs, path)
+//   • endLine / endColumn accurately calculated from match position & length
+//   • tool.driver.rules mapped from ZTDS compliance levels
+// ────────────────────────────────────────────────────────────────────────
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// ─── PII Entity Type → SARIF Level Mapping ──────────────────────────────
+const PII_LEVEL_MAP = {
+  passport:       'error',
+  ssn:            'error',
+  iban:           'error',
+  credit_card:    'error',
+  medical_id:     'error',
+  tax_id:         'error',
+  driver_license: 'error',
+  biometric:      'error',
+  secret:         'error',
+  api_key:        'error',
+  private_key:    'error',
+  id:             'error',
+  email:          'warning',
+  phone:          'warning',
+  address:        'warning',
+  date_of_birth:  'warning',
+  ip:             'warning',
+  ip_address:     'warning',
+  name:           'note',
+  city:           'note',
+  postal_code:    'note',
+  custom:         'warning'
+};
+
+const PII_PLACEHOLDER = {
+  passport:       '[REDACTED:PASSPORT]',
+  ssn:            '[REDACTED:SSN]',
+  iban:           '[REDACTED:IBAN]',
+  credit_card:    '[REDACTED:CARD]',
+  medical_id:     '[REDACTED:MEDICAL_ID]',
+  tax_id:         '[REDACTED:TAX_ID]',
+  driver_license: '[REDACTED:LICENSE]',
+  biometric:      '[REDACTED:BIOMETRIC]',
+  secret:         '[REDACTED:SECRET]',
+  api_key:        '[REDACTED:API_KEY]',
+  private_key:    '[REDACTED:PRIVATE_KEY]',
+  id:             '[REDACTED:ID]',
+  email:          '[REDACTED:EMAIL]',
+  phone:          '[REDACTED:PHONE]',
+  address:        '[REDACTED:ADDRESS]',
+  date_of_birth:  '[REDACTED:DOB]',
+  ip:             '[REDACTED:IP]',
+  ip_address:     '[REDACTED:IP]',
+  name:           '[REDACTED:NAME]',
+  city:           '[REDACTED:CITY]',
+  postal_code:    '[REDACTED:POSTAL]',
+  custom:         '[REDACTED:CUSTOM]'
+};
+
+// ─── Help Documentation URIs ───────────────────────────────────────────
+const RULE_HELP = {
+  passport:       'https://privacyscrubber.com/compliance/gdpr',
+  ssn:            'https://privacyscrubber.com/compliance/iso27001',
+  iban:           'https://privacyscrubber.com/compliance/pci',
+  credit_card:    'https://privacyscrubber.com/compliance/pci',
+  medical_id:     'https://privacyscrubber.com/compliance/hipaa',
+  tax_id:         'https://privacyscrubber.com/compliance/gdpr',
+  driver_license: 'https://privacyscrubber.com/compliance/gdpr',
+  biometric:      'https://privacyscrubber.com/compliance/eu-ai-act',
+  secret:         'https://privacyscrubber.com/solutions/dev',
+  api_key:        'https://privacyscrubber.com/solutions/dev',
+  private_key:    'https://privacyscrubber.com/solutions/dev',
+  id:             'https://privacyscrubber.com/compliance/gdpr',
+  email:          'https://privacyscrubber.com/compliance/gdpr',
+  phone:          'https://privacyscrubber.com/compliance/gdpr',
+  address:        'https://privacyscrubber.com/compliance/gdpr',
+  date_of_birth:  'https://privacyscrubber.com/compliance/gdpr',
+  ip:             'https://privacyscrubber.com/compliance/iso27001',
+  ip_address:     'https://privacyscrubber.com/compliance/iso27001',
+  name:           'https://privacyscrubber.com/compliance/gdpr',
+  city:           'https://privacyscrubber.com/compliance/gdpr',
+  postal_code:    'https://privacyscrubber.com/compliance/gdpr',
+  custom:         'https://privacyscrubber.com/sdk'
+};
+
+function normalizePiiType(type) {
+  if (!type) return 'custom';
+  const clean = String(type).trim().toLowerCase().replace(/[^a-z0-9_]/g, '_');
+  return clean;
+}
+
+// ─── Deterministic Fingerprint (GitHub Code Scanning deduplication) ────
+function generateFingerprint(piiType, uri, position, length) {
+  const normType = normalizePiiType(piiType);
+  const line = position?.line || 1;
+  const col = position?.column || 1;
+  const targetUri = uri || 'stdin';
+  const material = `${normType}|${targetUri}|${line}:${col}|${length}`;
+  const hash = crypto.createHash('sha256').update(material).digest('hex');
+  return {
+    primary: `${normType}-${hash.substring(0, 16)}`,
+    full: `sha256:${hash}`
+  };
+}
+
+// ─── Generate tool.driver.rules from PII_LEVEL_MAP ─────────────────────
+function generateRules() {
+  const rules = [];
+  for (const [piiType, level] of Object.entries(PII_LEVEL_MAP)) {
+    const ruleId = `PS-${piiType.toUpperCase()}`;
+    const securitySeverity = level === 'error' ? '9.0' :
+                             level === 'warning' ? '6.0' : '3.0';
+
+    rules.push({
+      id: ruleId,
+      name: `PrivacyScrubber_${piiType.toUpperCase()}_Rule`,
+      shortDescription: {
+        text: `Identifies ${piiType.toUpperCase()} patterns subject to ZTDS zero-egress sanitization`
+      },
+      fullDescription: {
+        text: `PrivacyScrubber rule detecting ${piiType.toUpperCase()} in source code, prompts, configs, ` +
+              `logs, or vector embeddings. Enforces ZTDS in-memory tokenization before network egress.`
+      },
+      helpUri: RULE_HELP[piiType] || 'https://privacyscrubber.com',
+      properties: {
+        tags: ['privacy', 'pii', 'compliance', 'ztds', piiType],
+        precision: 'very-high',
+        'problem.severity': level,
+        'security-severity': securitySeverity
+      }
+    });
+  }
+  return rules;
+}
+
+// ─── Transform Raw Engine Finding → SARIF 2.1.0 Result ─────────────────
+function findingToSarifResult(finding) {
+  const normType = normalizePiiType(finding.pii_type || finding.type);
+  const level = PII_LEVEL_MAP[normType] || 'note';
+  const placeholder = PII_PLACEHOLDER[normType] || `[REDACTED:${normType.toUpperCase()}]`;
+  const ruleId = `PS-${normType.toUpperCase()}`;
+
+  const pos = finding.position || {
+    line: finding.line || 1,
+    column: finding.column || 1
+  };
+  const length = Number(finding.match_length || finding.length || (finding.value ? finding.value.length : 0)) || 1;
+  const fileUri = finding.file_uri || finding.file || 'input.txt';
+
+  const endLine = finding.end_position?.line || finding.endLine || pos.line;
+  const endColumn = finding.end_position?.column || finding.endColumn || (pos.column + length);
+  const fingerprint = generateFingerprint(normType, fileUri, pos, length);
+
+  return {
+    ruleId,
+    level,
+    message: {
+      text: `PrivacyScrubber detected sensitive ${normType.toUpperCase()} token (${placeholder}) ` +
+            `at line ${pos.line}, column ${pos.column}. Sanitized locally in RAM (Zero Egress).`
+    },
+    locations: [{
+      physicalLocation: {
+        artifactLocation: {
+          uri: fileUri,
+          uriBaseId: '%SRCROOT%'
+        },
+        region: {
+          startLine: pos.line,
+          startColumn: pos.column,
+          endLine: endLine,
+          endColumn: endColumn,
+          snippet: {
+            text: finding.context_snippet || placeholder
+          }
+        }
+      }
+    }],
+    fingerprints: {
+      primaryFingerprint: fingerprint.primary,
+      sha256: fingerprint.full
+    },
+    properties: {
+      piiType: normType,
+      matchLength: length,
+      detector: finding.detector || 'ztds-pii-engine',
+      zeroEgress: true
+    }
+  };
+}
+
+// ─── Convert character offset in text to line and column ───────────────
+function offsetToLineColumn(text, offset) {
+  let line = 1;
+  let column = 1;
+  const max = Math.min(offset, text.length);
+  for (let i = 0; i < max; i++) {
+    if (text[i] === '\n') {
+      line++;
+      column = 1;
+    } else {
+      column++;
+    }
+  }
+  return { line, column };
+}
+
+// ─── Adapt sanitize() engine matches to SARIF findings ─────────────────
+function sanitizeResultToFindings(sanitizeResult, sourceText = '', fileUri = 'input.txt') {
+  const matches = sanitizeResult.matches || sanitizeResult.spans || [];
+  return matches.map(m => {
+    const pos = offsetToLineColumn(sourceText, m.start);
+    const length = (m.end - m.start) || (m.value ? m.value.length : 1);
+    const endPos = typeof m.end === 'number' ? offsetToLineColumn(sourceText, m.end) : null;
+    const normType = normalizePiiType(m.type);
+    const placeholder = PII_PLACEHOLDER[normType] || m.token || '[REDACTED]';
+
+    return {
+      pii_type: normType,
+      file_uri: fileUri,
+      position: pos,
+      end_position: endPos,
+      match_length: length,
+      context_snippet: placeholder,
+      detector: 'ztds-ram-engine'
+    };
+  });
+}
+
+// ─── Main SARIF 2.1.0 Emitter ──────────────────────────────────────────
+function emitSarif(findings, options = {}) {
+  const {
+    toolName = 'PrivacyScrubber',
+    toolVersion = '2.4.3',
+    sarifVersion = '2.1.0',
+    repositoryUri = '',
+    commitSha = '',
+    pretty = false
+  } = options;
+
+  const results = Array.isArray(findings) ? findings.map(findingToSarifResult) : [];
+
+  const sarifLog = {
+    $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Documents/Comprehensive%20SARIF%20JSON%20Schema/sarif-schema-2.1.0.json',
+    version: sarifVersion,
+    runs: [{
+      tool: {
+        driver: {
+          name: toolName,
+          version: toolVersion,
+          informationUri: 'https://privacyscrubber.com',
+          rules: generateRules()
+        }
+      },
+      results,
+      columnKind: 'utf16CodeUnits',
+      properties: {
+        scanTimestamp: new Date().toISOString(),
+        repositoryUri: repositoryUri || undefined,
+        commitSha: commitSha || undefined,
+        ztdsConformant: true,
+        zeroNetworkEgress: true
+      }
+    }]
+  };
+
+  return pretty ? JSON.stringify(sarifLog, null, 2) : JSON.stringify(sarifLog);
+}
+
+// ─── Zero-Dependency CLI Argument Parser ───────────────────────────────
+function parseArgs(argv) {
+  const args = {
+    input: '-',
+    output: '-',
+    pretty: false,
+    repo: '',
+    commit: '',
+    help: false
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '-h' || arg === '--help') {
+      args.help = true;
+    } else if (arg === '-i' || arg === '--input') {
+      args.input = argv[++i] || '-';
+    } else if (arg === '-o' || arg === '--output') {
+      args.output = argv[++i] || '-';
+    } else if (arg === '-p' || arg === '--pretty') {
+      args.pretty = true;
+    } else if (arg === '-r' || arg === '--repo') {
+      args.repo = argv[++i] || '';
+    } else if (arg === '-c' || arg === '--commit') {
+      args.commit = argv[++i] || '';
+    } else if (!arg.startsWith('-') && args.input === '-') {
+      args.input = arg;
+    }
+  }
+
+  return args;
+}
+
+// ─── CLI Entrypoint ────────────────────────────────────────────────────
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    console.log(`PrivacyScrubber SARIF 2.1.0 Emitter v2.4.3
+Usage: node cli/sarif.js [options] [inputFile]
+
+Options:
+  -i, --input <file>   Input JSON findings file or '-' for stdin (default: -)
+  -o, --output <file>  Output SARIF file or '-' for stdout (default: -)
+  -p, --pretty         Format output with indentation
+  -r, --repo <url>     Source repository URI
+  -c, --commit <sha>   Commit SHA
+  -h, --help           Show this help message`);
+    process.exit(0);
+  }
+
+  function processContent(raw) {
+    try {
+      let findings;
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) {
+        findings = parsed;
+      } else if (parsed && Array.isArray(parsed.findings)) {
+        findings = parsed.findings;
+      } else if (parsed && (parsed.matches || parsed.spans)) {
+        findings = sanitizeResultToFindings(parsed, parsed.sourceText || '', args.input === '-' ? 'stdin' : args.input);
+      } else {
+        findings = [];
+      }
+
+      const sarif = emitSarif(findings, {
+        pretty: args.pretty,
+        repositoryUri: args.repo,
+        commitSha: args.commit
+      });
+
+      if (args.output === '-') {
+        process.stdout.write(sarif + '\n');
+      } else {
+        fs.writeFileSync(args.output, sarif, 'utf8');
+      }
+    } catch (err) {
+      console.error(`Error processing findings for SARIF output: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  if (args.input === '-') {
+    const chunks = [];
+    process.stdin.on('data', c => chunks.push(c));
+    process.stdin.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8');
+      processContent(raw || '[]');
+    });
+  } else {
+    if (!fs.existsSync(args.input)) {
+      console.error(`Error: Input file does not exist: ${args.input}`);
+      process.exit(1);
+    }
+    const raw = fs.readFileSync(args.input, 'utf8');
+    processContent(raw);
+  }
+}
+
+module.exports = {
+  emitSarif,
+  generateRules,
+  findingToSarifResult,
+  offsetToLineColumn,
+  sanitizeResultToFindings,
+  PII_LEVEL_MAP,
+  PII_PLACEHOLDER
+};
+
+if (require.main === module) {
+  main();
+}

package/sarif.js

@@ -0,0 +1,37 @@
+// ────────────────────────────────────────────────────────────────────────
+// npm-sdk/sarif.js
+//   SARIF 2.1.0 module export for @privacyscrubber/sdk
+// ────────────────────────────────────────────────────────────────────────
+
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+
+const {
+  emitSarif,
+  generateRules,
+  findingToSarifResult,
+  offsetToLineColumn,
+  sanitizeResultToFindings,
+  PII_LEVEL_MAP,
+  PII_PLACEHOLDER
+} = require('./sarif.cjs');
+
+export {
+  emitSarif,
+  generateRules,
+  findingToSarifResult,
+  offsetToLineColumn,
+  sanitizeResultToFindings,
+  PII_LEVEL_MAP,
+  PII_PLACEHOLDER
+};
+
+export default {
+  emitSarif,
+  generateRules,
+  findingToSarifResult,
+  offsetToLineColumn,
+  sanitizeResultToFindings,
+  PII_LEVEL_MAP,
+  PII_PLACEHOLDER
+};