@clear-capabilities/agentic-security-scanner 0.143.0 → 0.144.0

package/src/egress/policy.js

@@ -0,0 +1,313 @@
+// Central egress policy (assurance-hardening PRD FR-601).
+//
+// Every outbound call this codebase makes to an LLM provider must be
+// evaluated HERE before its prompt is constructed and before any network
+// client touches the endpoint. A denied call must produce no network
+// request and a machine-readable decision object — never a silent no-op
+// and never a request that fires anyway with the decision merely logged
+// after the fact.
+//
+// SCOPE (this is FR-601 only, not the fuller FR-602-607 cluster):
+//   - A real allow/deny decision, evaluated before prompt construction.
+//   - `mode: deny` / `mode: local-only` / provider allow-deny lists as the
+//     concrete denial conditions this cycle implements, because FR-601's
+//     acceptance criterion ("a denied call results in no network request")
+//     requires at least one genuine, testable deny path to exist.
+//   - Deliberately NOT in scope here: redaction of the outbound payload
+//     (FR-603, already partially done by llm-validator/redact.js for its
+//     own path only), and persistent per-call audit records (FR-604). Each
+//     remains separate, tracked future work.
+//   - FR-602 (provider/model/role/region/repository/path/data-class/
+//     max-context constraints) IS in scope as of the FR-602 cycle — see the
+//     dimension loop and the path/token checks in evaluateEgress below.
+//     Each new dimension is evaluated ONLY when the caller supplies the
+//     corresponding ctx value AND the config restricts that dimension —
+//     a caller with no opinion on, say, region is never blocked by a
+//     region rule it has no way to satisfy or violate. This mirrors the
+//     provider dimension's own pre-existing shape (deniedX/allowedX list
+//     membership) for model/role/region/repository/data-class; path uses
+//     glob matching (util/glob.js's matchesAnyGlob, already used elsewhere
+//     in this codebase for ignore-pattern matching) since a single literal
+//     string is the wrong shape for a file path constraint; max-context
+//     is a numeric cap on an ESTIMATED token count the caller computes
+//     itself (evaluateEgress runs before prompt construction, so it has
+//     no prompt to measure — the caller must estimate from what it is
+//     about to build).
+//   - FR-605 (unambiguous local-only mode, anti-URL-smuggling) IS in scope
+//     as of the FR-605 cycle: `mode: local-only` here calls the same
+//     literal-only `isLoopbackUrl` check `local-endpoint.js` uses for its
+//     own preset, and every real HTTP-calling caller in the codebase
+//     (llm-validator, discovery/llm-invoke's single- AND consensus-endpoint
+//     paths, adversary-agent's own default path, flow-narration,
+//     sca/llm-function-extract) routes through this function before
+//     dialing out — verified by tracing every reference to
+//     AGENTIC_SECURITY_LLM_ENDPOINT in the codebase, not assumed. The one
+//     real gap found and closed in that pass: discovery/llm-invoke.js's
+//     multi-endpoint consensus mode used to construct its caller with NO
+//     egress check at all, so a `mode: local-only` policy was silently
+//     bypassable by setting AGENTIC_SECURITY_LLM_ENDPOINTS instead of the
+//     single-endpoint var. Fixed there, not here — see that file's own
+//     comment on `makeConsensusInvoke`.
+//   - FR-607 (approved-provider metadata for regulated profiles) IS in
+//     scope as of the FR-607 cycle: `regulatedProfile.requireApprovedProviders`
+//     is a no-op unless configured; once set, every provider must have a
+//     matching `approvedProviders[provider]` entry carrying a non-empty
+//     value for each required attribute (default: dpaStatus, baaStatus,
+//     retentionPolicy) or the call is denied. Organizational/contractual
+//     facts, never inferred — same discipline
+//     dataflow/privacy-governance.js's GOVERNANCE_FIELDS already
+//     established for RoPA/DPIA.
+//
+// DEFAULT BEHAVIOR. No config file and no env override => 'allow'. This
+// preserves the existing default-on UX for every LLM-backed feature in this
+// codebase (discovery, validation, adversary-agent, etc.) — FR-601 asks for
+// a policy DECISION on every call, not a policy that silently disables
+// functionality nobody configured it to disable.
+
+import * as fs from 'node:fs';
+import { load as loadYaml } from '../util/yaml.js';
+import { statePath } from '../posture/state-dir.js';
+import { isLoopbackUrl } from '../llm-validator/local-endpoint.js';
+import { matchesAnyGlob } from '../util/glob.js';
+
+// FR-602: the list-membership dimensions, keyed by ctx field name to the
+// config's allow/deny list PAIR name. `provider` (FR-601) already used
+// this exact shape as allowedProviders/deniedProviders; the rest are new.
+const LIST_DIMENSIONS = [
+  { ctxKey: 'model', allowKey: 'allowedModels', denyKey: 'deniedModels' },
+  { ctxKey: 'role', allowKey: 'allowedRoles', denyKey: 'deniedRoles' },
+  { ctxKey: 'region', allowKey: 'allowedRegions', denyKey: 'deniedRegions' },
+  { ctxKey: 'repository', allowKey: 'allowedRepositories', denyKey: 'deniedRepositories' },
+  { ctxKey: 'dataClass', allowKey: 'allowedDataClasses', denyKey: 'deniedDataClasses' },
+];
+
+const POLICY_FILE = 'egress-policy.yml';
+
+// FR-607: when a regulated profile requires approved-provider metadata, an
+// approvedProviders[provider] entry must carry a non-empty value for each
+// of these attributes unless the operator names a different set via
+// regulatedProfile.requiredAttributes. DPA (Data Processing Agreement) and
+// BAA (Business Associate Agreement, HIPAA) are organizational/contractual
+// facts — not derivable from code, same "state it, never infer it"
+// discipline dataflow/privacy-governance.js's GOVERNANCE_FIELDS already
+// established for RoPA/DPIA fields.
+const DEFAULT_REQUIRED_PROVIDER_ATTRIBUTES = ['dpaStatus', 'baaStatus', 'retentionPolicy'];
+
+// FR-603 (egress/redact.js) reads the same egress-policy.yml file for its
+// own keys (proprietaryPaths, customerDataPatterns, redactPii) — one
+// operator-facing config surface for the whole egress epic rather than a
+// second file. Exported (not `_`-prefixed like the rest of this module's
+// internals) for that reuse; still not part of the public evaluateEgress
+// API surface.
+export function loadPolicyConfig(scanRoot) {
+  let fp;
+  try { fp = statePath(scanRoot, POLICY_FILE); } catch { return null; }
+  // Read first, check second — an existsSync-then-readFileSync pair is a
+  // check-then-use race (the file can vanish between the two calls); this
+  // codebase's convention (apply-fix-service.js's readVerifiedScan) is to
+  // let the read fail and classify ENOENT rather than pre-check existence.
+  let raw;
+  try {
+    raw = fs.readFileSync(fp, 'utf8');
+  } catch (e) {
+    return null; // ENOENT (no config file) or any other read failure — same fallback either way
+  }
+  try {
+    const doc = loadYaml(raw);
+    return (doc && typeof doc === 'object' && !Array.isArray(doc)) ? doc : null;
+  } catch { return null; }
+}
+
+/** Best-effort, purely informational provider label from the endpoint host. */
+function _providerOf(endpoint) {
+  let u;
+  try { u = new URL(String(endpoint)); } catch { return 'unknown'; }
+  if (isLoopbackUrl(endpoint)) return 'local';
+  const h = u.hostname.toLowerCase();
+  if (h.includes('anthropic')) return 'anthropic';
+  if (h.includes('openai')) return 'openai';
+  if (h.includes('googleapis') || h.includes('generativelanguage')) return 'google';
+  return h || 'unknown';
+}
+
+/**
+ * Evaluate whether an outbound LLM call is permitted. Call sites MUST check
+ * `.allowed` before building the prompt for that call and before invoking
+ * any fetch/HTTP client against `ctx.endpoint`.
+ *
+ * @param {object} ctx
+ * @param {string} [ctx.scanRoot] - project root, for reading
+ *   `.agentic-security/egress-policy.yml`; a missing/unreadable root is
+ *   treated the same as no config file (falls back to 'allow').
+ * @param {string} ctx.purpose - short, stable id of the call site (e.g.
+ *   'discovery-hunter', 'llm-validator', 'adversary-agent') — never
+ *   free text, so a decision is comparable across runs and never carries
+ *   source content.
+ * @param {string} ctx.endpoint - the URL that would be called. Required —
+ *   a caller with no configured endpoint should never reach this function
+ *   at all (every call site already has its own pre-existing "is anything
+ *   configured" check upstream of prompt construction).
+ * @param {string} [ctx.model] - FR-602: the model id the caller intends to
+ *   use, if known. Evaluated against allowedModels/deniedModels only when
+ *   supplied.
+ * @param {string} [ctx.role] - FR-602: which ROLE this call serves (the
+ *   same closed vocabulary llm-validator/providers.js's ROLES uses, but
+ *   this function does not require membership in it — a caller in a
+ *   different subsystem may have its own role names). Evaluated against
+ *   allowedRoles/deniedRoles only when supplied.
+ * @param {string} [ctx.region] - FR-602: a data-residency/provider region
+ *   identifier, if the caller knows one. This codebase does not derive a
+ *   region for any provider today; it is purely caller-supplied and
+ *   evaluated against allowedRegions/deniedRegions only when supplied.
+ * @param {string} [ctx.repository] - FR-602: a repository identifier for
+ *   the current scan (e.g. a git remote or a stable project label), if the
+ *   caller knows one. Evaluated against allowedRepositories/
+ *   deniedRepositories only when supplied.
+ * @param {string} [ctx.path] - FR-602: a '/'-separated relative path
+ *   representative of the content in this call (e.g. the finding's source
+ *   file), if applicable. Evaluated by glob against allowedPaths/
+ *   deniedPaths only when supplied.
+ * @param {string} [ctx.dataClass] - FR-602: a regulated-data-class label
+ *   (e.g. from dataflow/privacy-taxonomy.js's taxonomy) present in the
+ *   content this call would send, if the caller has classified it.
+ *   Evaluated against allowedDataClasses/deniedDataClasses only when
+ *   supplied.
+ * @param {number} [ctx.contextTokens] - FR-602: the caller's OWN estimate
+ *   of the prompt's token size (this function runs before prompt
+ *   construction, so it cannot measure one itself). Compared against
+ *   `maxContextTokens` in config only when both are present.
+ * @returns {{allowed:boolean, decision:'allow'|'deny', reason:string|null,
+ *   provider:string, policySource:'default'|'env'|'config', purpose:string}}
+ *   Sanitized — carries no prompt/source content, only metadata, so it is
+ *   always safe to log or attach to a report as-is (PRD walkthrough
+ *   scenario 7: "records a sanitized decision without retaining source").
+ */
+export function evaluateEgress(ctx = {}) {
+  const {
+    scanRoot, purpose = 'unknown', endpoint,
+    model = null, role = null, region = null, repository = null,
+    path: filePath = null, dataClass = null, contextTokens = null,
+  } = ctx;
+
+  if (!endpoint || typeof endpoint !== 'string') {
+    return { allowed: false, decision: 'deny', reason: 'no endpoint provided to evaluateEgress', provider: 'unknown', policySource: 'default', purpose };
+  }
+
+  const provider = _providerOf(endpoint);
+
+  // Blunt, ops-friendly kill switch — same shape as the existing
+  // AGENTIC_SECURITY_LLM_VALIDATE=0 precedent in llm-validator/index.js.
+  if (process.env.AGENTIC_SECURITY_EGRESS_DENY === '1') {
+    return { allowed: false, decision: 'deny', reason: "AGENTIC_SECURITY_EGRESS_DENY=1 is set", provider, policySource: 'env', purpose };
+  }
+
+  const envMode = process.env.AGENTIC_SECURITY_EGRESS_MODE;
+  const cfg = loadPolicyConfig(scanRoot);
+  const mode = envMode || (cfg && cfg.mode) || 'allow';
+  const policySource = envMode ? 'env' : ((cfg && cfg.mode) ? 'config' : 'default');
+
+  if (mode === 'deny') {
+    return { allowed: false, decision: 'deny', reason: "egress mode is 'deny'", provider, policySource, purpose };
+  }
+
+  if (mode === 'local-only' && !isLoopbackUrl(endpoint)) {
+    return {
+      allowed: false, decision: 'deny',
+      reason: `egress mode is 'local-only' and the endpoint is not a loopback address`,
+      provider, policySource, purpose,
+    };
+  }
+
+  const deniedProviders = (cfg && Array.isArray(cfg.deniedProviders)) ? cfg.deniedProviders : [];
+  if (deniedProviders.includes(provider)) {
+    return { allowed: false, decision: 'deny', reason: `provider '${provider}' is in deniedProviders`, provider, policySource: 'config', purpose };
+  }
+
+  const allowedProviders = (cfg && Array.isArray(cfg.allowedProviders)) ? cfg.allowedProviders : null;
+  if (allowedProviders && !allowedProviders.includes(provider)) {
+    return { allowed: false, decision: 'deny', reason: `provider '${provider}' is not in allowedProviders`, provider, policySource: 'config', purpose };
+  }
+
+  // FR-602: the remaining list-membership dimensions (model/role/region/
+  // repository/dataClass), each a no-op unless BOTH the caller supplied a
+  // value AND the config restricts that specific dimension.
+  const ctxValues = { model, role, region, repository, dataClass };
+  for (const { ctxKey, allowKey, denyKey } of LIST_DIMENSIONS) {
+    const value = ctxValues[ctxKey];
+    if (value == null) continue;
+    const deniedList = (cfg && Array.isArray(cfg[denyKey])) ? cfg[denyKey] : [];
+    if (deniedList.includes(value)) {
+      return { allowed: false, decision: 'deny', reason: `${ctxKey} '${value}' is in ${denyKey}`, provider, policySource: 'config', purpose };
+    }
+    const allowedList = (cfg && Array.isArray(cfg[allowKey])) ? cfg[allowKey] : null;
+    if (allowedList && !allowedList.includes(value)) {
+      return { allowed: false, decision: 'deny', reason: `${ctxKey} '${value}' is not in ${allowKey}`, provider, policySource: 'config', purpose };
+    }
+  }
+
+  // FR-602: path is glob-matched, not list-membership — a single literal
+  // string is the wrong shape for a file path constraint.
+  if (filePath != null) {
+    const deniedPaths = (cfg && Array.isArray(cfg.deniedPaths)) ? cfg.deniedPaths : [];
+    if (matchesAnyGlob(filePath, deniedPaths)) {
+      return { allowed: false, decision: 'deny', reason: `path '${filePath}' matches a deniedPaths pattern`, provider, policySource: 'config', purpose };
+    }
+    const allowedPaths = (cfg && Array.isArray(cfg.allowedPaths)) ? cfg.allowedPaths : null;
+    if (allowedPaths && !matchesAnyGlob(filePath, allowedPaths)) {
+      return { allowed: false, decision: 'deny', reason: `path '${filePath}' does not match any allowedPaths pattern`, provider, policySource: 'config', purpose };
+    }
+  }
+
+  // FR-602: max-context is a numeric cap, evaluated only when the caller
+  // supplied its own token estimate AND the config sets a cap.
+  if (typeof contextTokens === 'number' && cfg && typeof cfg.maxContextTokens === 'number') {
+    if (contextTokens > cfg.maxContextTokens) {
+      return {
+        allowed: false, decision: 'deny',
+        reason: `estimated context (${contextTokens} tokens) exceeds maxContextTokens (${cfg.maxContextTokens})`,
+        provider, policySource: 'config', purpose,
+      };
+    }
+  }
+
+  // FR-607: a regulated profile can require APPROVED-PROVIDER metadata
+  // (DPA/BAA status, retention policy) before a provider is usable at all —
+  // a no-op unless the operator opts in via regulatedProfile.requireApproved
+  // Providers, same "restricts nothing until configured" default every
+  // other dimension above follows.
+  const regulatedProfile = (cfg && typeof cfg.regulatedProfile === 'object' && cfg.regulatedProfile) ? cfg.regulatedProfile : null;
+  let approvedProviderMetadata = null;
+  if (regulatedProfile && regulatedProfile.requireApprovedProviders) {
+    const requiredAttributes = (Array.isArray(regulatedProfile.requiredAttributes) && regulatedProfile.requiredAttributes.length)
+      ? regulatedProfile.requiredAttributes
+      : DEFAULT_REQUIRED_PROVIDER_ATTRIBUTES;
+    const approvedProviders = (cfg && typeof cfg.approvedProviders === 'object' && cfg.approvedProviders) ? cfg.approvedProviders : {};
+    const entry = approvedProviders[provider];
+    if (!entry || typeof entry !== 'object') {
+      return {
+        allowed: false, decision: 'deny',
+        reason: `provider '${provider}' has no approved-provider metadata configured, and this profile requires one (regulatedProfile.requireApprovedProviders)`,
+        provider, policySource: 'config', purpose,
+      };
+    }
+    const missing = requiredAttributes.filter((attr) => {
+      const v = entry[attr];
+      return !(typeof v === 'string' && v.length > 0 && v !== 'none' && v !== 'not_signed');
+    });
+    if (missing.length) {
+      return {
+        allowed: false, decision: 'deny',
+        reason: `provider '${provider}' is missing required approved-provider attribute(s): ${missing.join(', ')}`,
+        provider, policySource: 'config', purpose,
+      };
+    }
+    approvedProviderMetadata = entry;
+  }
+
+  return {
+    allowed: true, decision: 'allow', reason: null, provider, policySource, purpose,
+    ...(approvedProviderMetadata ? { approvedProviderMetadata } : {}),
+  };
+}
+
+export const _internals = { loadPolicyConfig, _providerOf, POLICY_FILE, DEFAULT_REQUIRED_PROVIDER_ATTRIBUTES };

package/src/egress/redact.js

@@ -0,0 +1,180 @@
+// Outbound-payload content redaction (assurance-hardening PRD FR-603).
+//
+// policy.js decides WHETHER a call is allowed to leave the machine at all.
+// This module decides WHAT is allowed to be IN the payload once a call is
+// already permitted — the content-level companion to that call-level gate.
+// Both read the same operator config (egress-policy.yml) via
+// policy.js's exported loadPolicyConfig, so there is one config surface
+// for the whole egress epic rather than a second file for redaction.
+//
+// Four categories, applied in a fixed order so an earlier, more specific
+// pass never fights a later, more general one over the same span (mirrors
+// llm-validator/redact.js's own most-specific-first rationale):
+//
+//   1. Proprietary paths — an operator-listed glob (`proprietaryPaths`)
+//      whose CONTENT must never leave at all, matched via util/glob.js's
+//      matchesAnyGlob (reused, not reimplemented — the same matcher FR-602
+//      uses for egress-policy.yml's deniedPaths/allowedPaths). Whole-span
+//      replacement, not a substring redaction, and it short-circuits every
+//      other pass — there is nothing left to redact once the whole thing
+//      is gone.
+//   2. Secrets — reuses llm-validator/redact.js's redactSecrets VERBATIM
+//      (the proven, independently-tested implementation described there;
+//      not reimplemented here). That module's own header already noted
+//      this was "already partially done ... for its own path only" before
+//      this cycle — this module is what makes it reachable beyond that one
+//      caller as a named, general capability.
+//   3. PII/PHI/PCI/FIN — reuses dataflow/privacy-taxonomy.js's field-name
+//      vocabulary (FR-402) as the single source of truth for "what counts
+//      as PII" across the codebase, applied with the same
+//      `name(:|=)"value"` shape llm-validator/redact.js's KEY_VALUE_RE
+//      already proved works for secrets. The CREDENTIALS class is skipped
+//      here — pass 2 already owns that category via redactSecrets, and
+//      redacting it twice under two different placeholder names would be
+//      confusing without adding any actual protection.
+//   4. Customer data — organization-defined only. egress-policy.yml's
+//      `customerDataPatterns` (raw regex strings, operator-authored). No
+//      built-in default: unlike PII, "customer data" has no generic shape
+//      the harness could safely guess (an internal account-number format,
+//      a tenant-naming scheme, ...) — this category is a no-op until an
+//      operator configures it, by design.
+//
+// Returns { text, redactions, categories: {...} } so a caller can report
+// HOW MUCH was removed per category (FR-604's audit metadata wants exactly
+// this: counts, not content) without retaining what was actually removed.
+
+import { loadPolicyConfig } from './policy.js';
+import { redactSecrets } from '../llm-validator/redact.js';
+import { loadPrivacyTaxonomy } from '../dataflow/privacy-taxonomy.js';
+import { matchesAnyGlob } from '../util/glob.js';
+
+const PROPRIETARY_PLACEHOLDER = '[REDACTED-PROPRIETARY-CONTENT]';
+const PII_PLACEHOLDER = '[REDACTED-PII]';
+const CUSTOMER_DATA_PLACEHOLDER = '[REDACTED-CUSTOMER-DATA]';
+
+/**
+ * Build one `name(:|=)"value"` regex per taxonomy class (excluding
+ * CREDENTIALS — see module header). Mirrors llm-validator/redact.js's
+ * KEY_VALUE_RE shape exactly, generalized to an arbitrary field-name
+ * pattern list instead of a fixed word list.
+ */
+function _buildPiiKeyValueRegexes(taxonomy) {
+  const regexes = [];
+  for (const [cls, def] of Object.entries(taxonomy || {})) {
+    if (cls === 'CREDENTIALS') continue;
+    const patterns = Array.isArray(def?.patterns) ? def.patterns : [];
+    if (!patterns.length) continue;
+    let re;
+    try {
+      // Named groups, not positional (\1/\2/\3) — several taxonomy field
+      // patterns carry their OWN capturing group (e.g. PII's
+      // `email([_-]?address)?`), which would silently shift every
+      // positional backreference below it. \k<quote> sidesteps that
+      // entirely regardless of how many groups the alternation contains.
+      re = new RegExp(
+        '(?<keyName>' + patterns.join('|') + ')(?<opWs>\\s*[:=]\\s*)(?<quote>[\'"`])(?<value>[^\'"`]+)\\k<quote>',
+        'gi'
+      );
+    } catch {
+      continue; // an operator-supplied pattern (privacy-taxonomy.json) can be invalid regex
+    }
+    regexes.push(re);
+  }
+  return regexes;
+}
+
+/**
+ * Redact PII/PHI/PCI/FIN-shaped `key: "value"` / `key = "value"` spans.
+ * taxonomy defaults to the built-in DEFAULT_TAXONOMY when not supplied.
+ */
+export function redactPii(text, { taxonomy } = {}) {
+  if (typeof text !== 'string' || text.length === 0) {
+    return { text: typeof text === 'string' ? text : '', redactions: 0 };
+  }
+  const effectiveTaxonomy = taxonomy || loadPrivacyTaxonomy(null).taxonomy;
+  let out = text;
+  let redactions = 0;
+  for (const re of _buildPiiKeyValueRegexes(effectiveTaxonomy)) {
+    out = out.replace(re, (...args) => {
+      const groups = args[args.length - 1];
+      redactions++;
+      return `${groups.keyName}${groups.opWs}${groups.quote}${PII_PLACEHOLDER}${groups.quote}`;
+    });
+  }
+  return { text: out, redactions };
+}
+
+/** Redact organization-defined customer-data patterns. No-op with no patterns configured. */
+export function redactCustomerData(text, { patterns = [] } = {}) {
+  if (typeof text !== 'string' || text.length === 0 || !patterns.length) {
+    return { text: typeof text === 'string' ? text : '', redactions: 0 };
+  }
+  let out = text;
+  let redactions = 0;
+  for (const p of patterns) {
+    let re;
+    try { re = new RegExp(p, 'gi'); } catch { continue; } // invalid operator-supplied regex — skip, don't throw
+    out = out.replace(re, () => { redactions++; return CUSTOMER_DATA_PLACEHOLDER; });
+  }
+  return { text: out, redactions };
+}
+
+/** True when filePath matches an operator-configured proprietary-path glob. */
+export function isProprietaryPath(filePath, { proprietaryPaths = [] } = {}) {
+  if (!filePath || !proprietaryPaths.length) return false;
+  return matchesAnyGlob(filePath, proprietaryPaths);
+}
+
+/**
+ * Apply the full redaction pipeline to one span of outbound prompt text.
+ *
+ * @param {object} opts
+ * @param {string} opts.text - the text about to be sent to a model endpoint.
+ * @param {string} [opts.filePath] - the source file this text was drawn
+ *   from, if any — evaluated against `proprietaryPaths`.
+ * @param {string} [opts.scanRoot] - project root, for reading
+ *   egress-policy.yml when `policy` is not already supplied.
+ * @param {object} [opts.taxonomy] - a pre-loaded privacy taxonomy (avoids
+ *   re-reading privacy-taxonomy.json per call in a hot loop); defaults to
+ *   loadPrivacyTaxonomy(scanRoot).taxonomy.
+ * @param {object} [opts.policy] - a pre-loaded egress-policy.yml document
+ *   (avoids re-reading it per call); defaults to loadPolicyConfig(scanRoot).
+ * @returns {{text: string, redactions: number, categories: {proprietaryPath: number, secrets: number, pii: number, customerData: number}}}
+ */
+export function redactPayload({ text, filePath = null, scanRoot = null, taxonomy = null, policy = null } = {}) {
+  const categories = { proprietaryPath: 0, secrets: 0, pii: 0, customerData: 0 };
+  if (typeof text !== 'string' || text.length === 0) {
+    return { text: typeof text === 'string' ? text : '', redactions: 0, categories };
+  }
+
+  const cfg = policy || loadPolicyConfig(scanRoot) || {};
+  const proprietaryPaths = Array.isArray(cfg.proprietaryPaths) ? cfg.proprietaryPaths : [];
+  if (isProprietaryPath(filePath, { proprietaryPaths })) {
+    categories.proprietaryPath = 1;
+    return { text: PROPRIETARY_PLACEHOLDER, redactions: 1, categories };
+  }
+
+  let out = text;
+
+  const secretResult = redactSecrets(out);
+  out = secretResult.text;
+  categories.secrets = secretResult.redactions;
+
+  const piiEnabled = cfg.redactPii !== false; // default ON — this category has a safe built-in default, unlike customerDataPatterns
+  if (piiEnabled) {
+    const effectiveTaxonomy = taxonomy || loadPrivacyTaxonomy(scanRoot).taxonomy;
+    const piiResult = redactPii(out, { taxonomy: effectiveTaxonomy });
+    out = piiResult.text;
+    categories.pii = piiResult.redactions;
+  }
+
+  const customerDataPatterns = Array.isArray(cfg.customerDataPatterns) ? cfg.customerDataPatterns : [];
+  const customerResult = redactCustomerData(out, { patterns: customerDataPatterns });
+  out = customerResult.text;
+  categories.customerData = customerResult.redactions;
+
+  const redactions = categories.proprietaryPath + categories.secrets + categories.pii + categories.customerData;
+  return { text: out, redactions, categories };
+}
+
+export const _internals = { _buildPiiKeyValueRegexes, PROPRIETARY_PLACEHOLDER, PII_PLACEHOLDER, CUSTOMER_DATA_PLACEHOLDER };