Bulkhead Core

Cascading content protection engine -- detects and redacts PII, secrets, prompt injection, and system prompt leakage in text before it reaches LLMs.

Part of the Bulkhead project.

Install

npm install @bulkhead-ai/core

Also available as @floatingsidewal/bulkhead-core via GitHub Packages.

Quick Start

import { createEngine } from "@bulkhead-ai/core";

const engine = createEngine();

// Fast regex-only scan (sub-millisecond)
const result = await engine.analyze("My SSN is 123-45-6789 and key is AKIAIOSFODNN7EXAMPLE");

console.log(result.passed);      // false
console.log(result.detections);   // [{ entityType: "US_SSN", ... }, { entityType: "AWS_ACCESS_KEY", ... }]

// Scan and redact
const redacted = await engine.scan("Call me at 555-867-5309");
console.log(redacted.redactedText); // "Call me at [REDACTED-US_PHONE]"

Sanitize JSON-Compatible Documents

sanitizeDocument() is the recommended API for objects and arrays. It scans keys and string values before mutation, resolves overlapping detections once, uses one consistency map and temporal anchor for the document, and reports pre-treatment detections separately from post-treatment safety.

import { sanitizeDocument } from "@bulkhead-ai/core";

const result = await sanitizeDocument(
  {
    contact: "[email protected]",
    opened: "2026-07-10",
    events: [{ occurred: "07/12/2026" }],
  },
  "eval",
  { localizedDateOrder: "mdy" },
);

if (!result.metadata.postTreatment.safe ||
    !result.metadata.postTreatment.structurallyValid) {
  throw new Error("Sanitization boundary rejected output");
}

console.log(result.value);
console.log(result.metadata.detectedRisk);

Localized dates require an explicit mdy, dmy, or reject-ambiguous choice. Detected dates that are ambiguous, invalid, or unsupported are replaced with [REDACTED-DATE_TIME] by default rather than passing through unchanged.

What It Detects

All structured patterns include checksum validation where applicable (Luhn, IBAN mod-97, Verhoeff).

Policy Scanning

import { createEngine, getPolicy } from "@bulkhead-ai/core";

const engine = createEngine({
  enabled: true,
  debounceMs: 500,
  guards: {
    pii: { enabled: true },
    secret: { enabled: true },
    injection: { enabled: true },
    contentSafety: { enabled: false },
  },
  cascade: {
    modelEnabled: false,
    escalationThreshold: 0.75,
    contextSentences: 3,
    modelId: "Xenova/bert-base-NER",
  },
  policy: "strict",
});

const policy = getPolicy("strict");
const { risk } = await engine.policyScan(inputText, policy);
console.log(risk.level);        // "critical" | "high" | "medium" | "low" | "none"
console.log(risk.issues);       // classified issues by category and severity
console.log(risk.testDataFlags); // synthetic/eval data detected

BERT Layer (Optional)

For contextual entities like names, locations, and organizations:

npm install @huggingface/transformers

const engine = createEngine({
  // ...
  cascade: { modelEnabled: true, /* ... */ },
});

const result = await engine.deepScan("Send the report to John Smith at Acme Corp");

The BERT model (~29 MB) downloads on first inference and runs in a worker thread. No GPU required.

Documentation

See the How-To Guide for comprehensive examples and the full documentation for architecture, deployment, and API reference.

License

MIT