@clear-capabilities/agentic-security-scanner 0.78.0 → 0.80.0

package/src/dataflow/ifds-precise.js

@@ -0,0 +1,222 @@
+// IFDS-precise extensions — Recommendation #2 of the world-class roadmap.
+//
+// The existing scanner/src/dataflow/ifds.js implements the core IFDS
+// worklist algorithm with k=1 summarized return-taint. This module adds
+// the three world-class pieces still missing:
+//
+//   1. Per-call-site summary REFINEMENT — instead of "this function
+//      returns tainted unconditionally," cache "returns tainted under
+//      entry state X" so the same callee at different sites uses
+//      different summaries.
+//   2. On-demand BACKWARD SLICING for high-confidence findings —
+//      starting from a critical sink, walk backwards through the
+//      use-def chain and emit a minimal trace that explains exactly
+//      which lines contribute taint.
+//   3. PERSISTENT cross-scan summary cache — write the summary table
+//      to .agentic-security/ifds-summaries.json after each scan and
+//      reload on the next scan. Skip re-analysis of unchanged
+//      functions (incremental analysis).
+//
+// Opt-in via AGENTIC_SECURITY_IFDS_PRECISE=1 alongside the existing
+// AGENTIC_SECURITY_DEEP=1.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+
+// ── Per-call-site refined summaries ────────────────────────────────────────
+
+/**
+ * RefinedSummaryCache — extends the base summary cache with per-entry-state
+ * refinement. Whereas the base cache stores ONE summary per function under
+ * empty entry state, this layer caches a MAP of (entryStateHash → summary)
+ * per function.
+ *
+ * The intent: at call site A→B(x), the entry state captures which of B's
+ * formal parameters are tainted by A's actual argument expressions. If x
+ * is tainted at site 1 but not at site 2, we cache TWO summaries for B,
+ * and the caller's worklist consults the right one.
+ *
+ * Capped at MAX_REFINEMENTS_PER_FN to keep cache size bounded.
+ */
+const MAX_REFINEMENTS_PER_FN = 4;
+
+export class RefinedSummaryCache {
+  constructor(baseCache, opts = {}) {
+    this._base = baseCache;
+    this._refinements = new Map();              // qid → Map<stateHash, summary>
+    this._lru = new Map();                      // qid → array (recency)
+    this.maxPerFn = opts.maxPerFn || MAX_REFINEMENTS_PER_FN;
+    this.metrics = { refinementHits: 0, refinementMisses: 0, refinementEvictions: 0 };
+  }
+
+  _hash(entryState) {
+    if (!entryState) return '∅';
+    if (entryState instanceof Set) {
+      if (entryState.size === 0) return '∅';
+      return [...entryState].sort().join('|');
+    }
+    if (Array.isArray(entryState)) {
+      if (entryState.length === 0) return '∅';
+      return entryState.slice().sort().join('|');
+    }
+    if (typeof entryState === 'object') {
+      // Object keyed by parameter index → tainted bool.
+      const keys = Object.keys(entryState).sort();
+      return keys.map(k => `${k}=${entryState[k] ? 1 : 0}`).join(',') || '∅';
+    }
+    return String(entryState);
+  }
+
+  get(qid, entryState) {
+    const h = this._hash(entryState);
+    const m = this._refinements.get(qid);
+    if (m && m.has(h)) {
+      this._touch(qid, h);
+      this.metrics.refinementHits++;
+      return m.get(h);
+    }
+    // Fallback to base for empty entry state (matches k=1 behavior).
+    if (this._base && typeof this._base.get === 'function') {
+      const v = this._base.get(qid, entryState);
+      if (v) return v;
+    }
+    this.metrics.refinementMisses++;
+    return undefined;
+  }
+
+  store(qid, entryState, summary) {
+    const h = this._hash(entryState);
+    let m = this._refinements.get(qid);
+    let order = this._lru.get(qid);
+    if (!m) { m = new Map(); this._refinements.set(qid, m); }
+    if (!order) { order = []; this._lru.set(qid, order); }
+    if (!m.has(h)) {
+      while (order.length >= this.maxPerFn) {
+        const evict = order.shift();
+        m.delete(evict);
+        this.metrics.refinementEvictions++;
+      }
+      order.push(h);
+    }
+    m.set(h, summary);
+    // Also seed base for the empty-entry path.
+    if ((entryState instanceof Set && entryState.size === 0) && this._base && typeof this._base.set === 'function') {
+      try { this._base.set(qid, new Set(), summary); } catch {}
+    }
+  }
+
+  _touch(qid, h) {
+    const order = this._lru.get(qid);
+    if (!order) return;
+    const idx = order.indexOf(h);
+    if (idx >= 0) { order.splice(idx, 1); order.push(h); }
+  }
+
+  size() {
+    let n = 0;
+    for (const m of this._refinements.values()) n += m.size;
+    return n;
+  }
+}
+
+// ── On-demand backward slicing ─────────────────────────────────────────────
+
+/**
+ * backwardSlice(callGraph, finding) — given a finding at a sink, walk
+ * backwards through use-def edges to produce a minimal trace explaining
+ * each step from source to sink. Returns an array of { line, file,
+ * snippet, reason } entries ordered source-first.
+ *
+ * The traversal is intentionally bounded (depth ≤ MAX_SLICE_DEPTH) and
+ * cycle-aware. For very deep flows we emit a `...` elision rather than
+ * unbounded growth.
+ */
+const MAX_SLICE_DEPTH = 16;
+
+export function backwardSlice(callGraph, finding, opts = {}) {
+  const seen = new Set();
+  const out = [];
+  if (!finding) return out;
+  let cur = finding.sink || finding;
+  let depth = 0;
+  while (cur && depth < MAX_SLICE_DEPTH) {
+    const key = `${cur.file || finding.file}:${cur.line}`;
+    if (seen.has(key)) { out.push({ ...cur, reason: 'cycle-detected' }); break; }
+    seen.add(key);
+    out.push({
+      file: cur.file || finding.file,
+      line: cur.line,
+      snippet: cur.snippet || cur.expr || null,
+      reason: cur.reason || 'use-def-pred',
+    });
+    cur = cur.predecessor || (callGraph && callGraph.getPred && callGraph.getPred(cur)) || null;
+    depth++;
+  }
+  if (depth >= MAX_SLICE_DEPTH) out.push({ reason: 'slice-depth-cap' });
+  return out.reverse(); // source-first
+}
+
+// ── Persistent cross-scan summary cache ────────────────────────────────────
+
+function _cachePath(scanRoot) {
+  return path.join(scanRoot, '.agentic-security', 'ifds-summaries.json');
+}
+
+function _fileHash(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+/**
+ * Load a previously-persisted IFDS summary cache. Returns:
+ *   { summaries: Map<qid, summary>, fileHashes: Map<filePath, sha>, scanTs }
+ * or null if no persisted cache exists / is unreadable.
+ */
+export function loadPersistedCache(scanRoot) {
+  const fp = _cachePath(scanRoot);
+  if (!fs.existsSync(fp)) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(fp, 'utf8'));
+    return {
+      summaries: new Map(Object.entries(raw.summaries || {})),
+      fileHashes: new Map(Object.entries(raw.fileHashes || {})),
+      scanTs: raw.scanTs || null,
+    };
+  } catch { return null; }
+}
+
+/**
+ * Persist the current scan's summaries to disk. Subsequent scans can
+ * skip re-analysis of functions whose file hash hasn't changed.
+ */
+export function persistCache(scanRoot, cache, perFileIR) {
+  const dir = path.join(scanRoot, '.agentic-security');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  const fileHashes = {};
+  for (const [filePath, ir] of (perFileIR || new Map())) {
+    if (ir && typeof ir._content === 'string') fileHashes[filePath] = _fileHash(ir._content);
+  }
+  const summaries = {};
+  for (const [qid, sum] of (cache._refinements || new Map())) {
+    // Serialize only the empty-entry-state summary — the refinements are
+    // ephemeral per scan; the empty-entry summary is the stable contract.
+    if (sum.has('∅')) summaries[qid] = sum.get('∅');
+  }
+  const out = { scanTs: new Date().toISOString(), summaries, fileHashes };
+  try { fs.writeFileSync(_cachePath(scanRoot), JSON.stringify(out, null, 2)); }
+  catch { /* best-effort */ }
+}
+
+/**
+ * Skip analysis of an unchanged function — when the file containing the
+ * function hasn't changed since the last persisted cache, reuse the prior
+ * summary.
+ */
+export function shouldSkipReanalysis(prevCache, filePath, currentContent) {
+  if (!prevCache || !prevCache.fileHashes) return false;
+  const prevHash = prevCache.fileHashes.get(filePath);
+  if (!prevHash) return false;
+  return prevHash === _fileHash(currentContent);
+}
+
+export const _internals = { _cachePath, _fileHash, MAX_REFINEMENTS_PER_FN, MAX_SLICE_DEPTH };

package/src/dataflow/k2-summary-cache.js

@@ -0,0 +1,153 @@
+// k=2 monovariant summary cache — Recommendation #9 of the SCA/SAST plan.
+//
+// The existing scanner/src/dataflow/summaries.js (referenced by engine.js)
+// implements k=1: per-function ONE summary computed under empty entry state.
+// That misses the common Juliet pattern of "function is pure when called
+// with clean args but vulnerable when called with tainted args" because
+// only the empty-state summary is cached.
+//
+// This module wraps SummaryCache with a per-(qid, entry-state-class) lookup,
+// up to 2 distinct entry-state classes per function. The "class" is computed
+// from a stable hash of which parameter positions are tainted — at k=2 we
+// cache the all-clean state and one tainted state per function. Three or
+// more distinct states evict to LRU.
+//
+// Usage:
+//   const k2 = new K2SummaryCache(opts.baseCache);
+//   k2.get(qid, entryState)         → summary | undefined
+//   k2.compute(qid, entryState, fn) → summary
+//   k2.applyAtCallSite(qid, entryState, callerCtx) → mutations
+//
+// Falls back to k=1 behaviour transparently when summaries.js's
+// SummaryCache.get returns a summary that doesn't carry entry-state info,
+// so the rest of the engine continues to work unchanged.
+
+const _MAX_STATES_PER_FN = 2;
+
+function _hashEntryState(entryState) {
+  // Stable string from a Set of "tainted parameter positions" / variable
+  // names. For k=2 we only care about taint cardinality + which positions
+  // — the actual values are not modelled (premortem: no value sensitivity
+  // until field-sensitive cache lifts in v3).
+  if (!entryState) return '∅';
+  if (entryState instanceof Set) {
+    if (entryState.size === 0) return '∅';
+    return [...entryState].sort().join(',');
+  }
+  if (Array.isArray(entryState)) {
+    if (entryState.length === 0) return '∅';
+    return entryState.slice().sort().join(',');
+  }
+  // Fallback for opaque entry states — single bucket.
+  return '*';
+}
+
+export class K2SummaryCache {
+  constructor(baseCache) {
+    this._base = baseCache;                  // existing k=1 cache (SummaryCache)
+    this._states = new Map();                // qid → Map<stateHash, summary>
+    this._stateOrder = new Map();            // qid → array (LRU order)
+    this.metrics = { hits: 0, misses: 0, evictions: 0, computes: 0 };
+  }
+
+  /**
+   * Read a summary for (qid, entry). Returns undefined if uncached.
+   * Falls back to the base cache when our k=2 table has no entry.
+   */
+  get(qid, entryState) {
+    const hash = _hashEntryState(entryState);
+    const states = this._states.get(qid);
+    if (states && states.has(hash)) {
+      this.metrics.hits++;
+      this._touch(qid, hash);
+      return states.get(hash);
+    }
+    // k=1 fallback — accept whatever the base cache stored.
+    if (this._base && typeof this._base.get === 'function') {
+      const v = this._base.get(qid, entryState);
+      if (v) { this.metrics.hits++; return v; }
+    }
+    this.metrics.misses++;
+    return undefined;
+  }
+
+  /**
+   * Compute (or retrieve) a summary for (qid, entry). Uses the supplied
+   * `compute` function only on miss. Caches per-state at k=2.
+   */
+  compute(qid, entryState, computeFn) {
+    const existing = this.get(qid, entryState);
+    if (existing) return existing;
+    this.metrics.computes++;
+    const summary = computeFn();
+    this._store(qid, entryState, summary);
+    // Also seed the base cache under empty-entry-state so the k=1 engine
+    // paths that don't know about k=2 still see the cleanest summary.
+    if (this._base && typeof this._base.set === 'function' && (!entryState || (entryState instanceof Set && entryState.size === 0))) {
+      try { this._base.set(qid, new Set(), summary); } catch {}
+    }
+    return summary;
+  }
+
+  /**
+   * Apply the cached summary at a call site, propagating return-taint and
+   * mutated-parameter taint into the caller's mutation set. Mirrors the
+   * base cache's applyAtCallSite signature.
+   */
+  applyAtCallSite(qid, entryState, callerCtx) {
+    const summary = this.get(qid, entryState);
+    if (!summary) return null;
+    // Defer to the base implementation when present — we don't reimplement
+    // the mutation algebra here.
+    if (this._base && typeof this._base.applyAtCallSite === 'function') {
+      try { return this._base.applyAtCallSite(qid, entryState, callerCtx, summary); }
+      catch { return null; }
+    }
+    return summary;
+  }
+
+  _store(qid, entryState, summary) {
+    const hash = _hashEntryState(entryState);
+    let states = this._states.get(qid);
+    let order = this._stateOrder.get(qid);
+    if (!states) { states = new Map(); this._states.set(qid, states); }
+    if (!order)  { order = []; this._stateOrder.set(qid, order); }
+    if (!states.has(hash)) {
+      // LRU eviction at k=2.
+      while (order.length >= _MAX_STATES_PER_FN) {
+        const evict = order.shift();
+        states.delete(evict);
+        this.metrics.evictions++;
+      }
+      order.push(hash);
+    }
+    states.set(hash, summary);
+  }
+  _touch(qid, hash) {
+    const order = this._stateOrder.get(qid);
+    if (!order) return;
+    const idx = order.indexOf(hash);
+    if (idx >= 0) { order.splice(idx, 1); order.push(hash); }
+  }
+
+  /**
+   * Size of the cache — for diagnostics / metrics dashboards.
+   */
+  size() {
+    let n = 0;
+    for (const states of this._states.values()) n += states.size;
+    return n;
+  }
+}
+
+/**
+ * Wrap an existing k=1 SummaryCache with k=2 behavior. The engine can opt
+ * into this via AGENTIC_SECURITY_K2_TAINT=1.
+ */
+export function wrapAsK2(baseCache) {
+  if (!baseCache) return new K2SummaryCache(null);
+  if (baseCache instanceof K2SummaryCache) return baseCache;
+  return new K2SummaryCache(baseCache);
+}
+
+export const _internals = { _hashEntryState, _MAX_STATES_PER_FN };

package/src/dataflow/lib-taint-summaries.js

@@ -0,0 +1,198 @@
+// Library taint summaries — Recommendation #5 of the SCA/SAST plan.
+//
+// Hand-curated knowledge that "this library method returns tainted data" or
+// "this method propagates taint from arg N to its return." Used by the
+// existing dataflow engine + per-language detectors when classifying the
+// taint state of a declaration's rhs.
+//
+// The summaries are intentionally per-language because the same concept
+// (a user-input source) has different idioms in each ecosystem. Each entry:
+//
+//   { pattern: RegExp, kind: 'source' | 'sanitizer' | 'passthrough',
+//     framework: 'spring' | 'aspnet' | 'glibc' | … }
+//
+// Kinds:
+//   source       — return value is unconditionally tainted
+//   sanitizer    — return value is unconditionally clean, even if any arg
+//                  was tainted (e.g. HtmlEncode, parameterized prepare)
+//   passthrough  — return value is tainted iff arg N is tainted (taint
+//                  flows through). Not modelled in v1; reserved for future
+//                  inter-procedural extensions (Recommendation #9).
+//
+// Usage: detectors call `isLibrarySource(text, lang)` and `isLibrarySanitizer
+// (text, lang)` to refine their per-call decisions.
+
+const JAVA_SUMMARIES = {
+  sources: [
+    // Servlet API — every request-scoped getter is a user-input source.
+    /\bHttpServletRequest\b[\s\S]{0,2000}?\.\s*(?:getParameter(?:Values|Map)?|getQueryString|getHeader(?:Names)?|getInputStream|getReader|getCookies?|getRequestURI|getRequestURL|getQueryString|getPathInfo)\s*\(/,
+    /\bjavax\.servlet\.http\.HttpServletRequest\b/,
+    // Spring MVC — controller method annotations bind to request data.
+    /@RequestParam\b/,
+    /@RequestBody\b/,
+    /@PathVariable\b/,
+    /@RequestHeader\b/,
+    /@CookieValue\b/,
+    /@ModelAttribute\b/,
+    // Spring Security — the principal is user-controlled in the trust sense
+    // (it identifies WHO the request is from; not auto-sanitized).
+    /\bSecurityContextHolder\s*\.\s*getContext\s*\(\s*\)\s*\.\s*getAuthentication\s*\(\s*\)/,
+    // Java Files API — file content is untrusted when source is unknown.
+    /\bFiles\s*\.\s*(?:readString|readAllBytes|readAllLines|lines|newBufferedReader|newInputStream)\b/,
+    /\bPaths\s*\.\s*get\s*\([^)]*(?:System\.getProperty|args)\b/,
+    // BufferedReader / Scanner reading user input.
+    /\bBufferedReader\b[\s\S]{0,500}?\.\s*readLine\s*\(/,
+    /\bScanner\b[\s\S]{0,500}?\.\s*(?:next(?:Line)?|nextInt|nextLong)\s*\(/,
+    // System.getenv / System.getProperty — environment is configurable.
+    /\bSystem\s*\.\s*(?:getenv|getProperty)\s*\(/,
+    // Jackson — deserialization input is untrusted.
+    /\bObjectMapper\b[\s\S]{0,500}?\.\s*readValue\s*\(/,
+    /\bJsonParser\b[\s\S]{0,500}?\.\s*getValueAsString\s*\(/,
+    // Apache Commons IO.
+    /\bIOUtils\s*\.\s*toString\s*\(/,
+    /\bFileUtils\s*\.\s*readFileToString\s*\(/,
+    // Spring WebFlux ServerWebExchange.
+    /\bServerWebExchange\b[\s\S]{0,500}?\.\s*getRequest\s*\(/,
+  ],
+  sanitizers: [
+    /\bOWASP\.Encoder\b/,
+    /\bESAPI\b[\s\S]{0,200}?\.\s*encoder\s*\(\s*\)/,
+    /\bStringEscapeUtils\s*\.\s*escape(?:Html\d?|Xml|Sql|Java|JavaScript)\b/,
+    /\bHtmlUtils\s*\.\s*htmlEscape\b/,
+    /\bUriUtils\s*\.\s*encode\b/,
+    // JDBC PreparedStatement parameter setters — taint is cleaned at bind.
+    /\bPreparedStatement\b[\s\S]{0,500}?\.\s*set(?:String|Int|Long|Object|BigDecimal|Date|Timestamp)\s*\(/,
+    /\bNamedParameterJdbcTemplate\b[\s\S]{0,500}?\.\s*(?:query|update|queryForObject)\s*\([^,]+,\s*new\s+MapSqlParameterSource\b/,
+    // Java validators.
+    /\bjakarta\.validation\b/,
+    /\bjavax\.validation\b/,
+    /\b@Valid\b/,
+  ],
+};
+
+const CSHARP_SUMMARIES = {
+  sources: [
+    // ASP.NET request surfaces.
+    /\bHttpRequest\b[\s\S]{0,500}?\.\s*(?:Query|Form|Headers|Cookies|RouteValues|Body|InputStream|QueryString|Params|Path|Url)\b/,
+    /\bHttpContext\s*\.\s*Request\b/,
+    /\bIFormCollection\b/,
+    /\bIFormFile\b/,
+    /\bIFormFileCollection\b/,
+    // ASP.NET Core model binding.
+    /\[FromQuery\]/,
+    /\[FromBody\]/,
+    /\[FromForm\]/,
+    /\[FromRoute\]/,
+    /\[FromHeader\]/,
+    // Configuration may carry secrets but the VALUES are environment-supplied.
+    /\bIConfiguration\b[\s\S]{0,500}?\.\s*(?:GetSection|GetValue|GetConnectionString|GetChildren)\s*\(/,
+    // Newtonsoft.Json deserialization.
+    /\bJsonConvert\s*\.\s*Deserialize(?:Object|XmlNode)\s*</,
+    /\bJsonSerializer\s*\.\s*Deserialize\s*</,
+    // Files / streams.
+    /\bFile\s*\.\s*(?:ReadAllText|ReadAllLines|ReadAllBytes|OpenRead|OpenText)\s*\(/,
+    /\bStreamReader\b[\s\S]{0,500}?\.\s*(?:ReadLine|ReadToEnd|Read)\s*\(/,
+    /\bBinaryReader\b[\s\S]{0,500}?\.\s*Read(?:String|Bytes|Char|Int32|Int64|UInt32|UInt64)\s*\(/,
+    // Network reads.
+    /\bWebClient\b[\s\S]{0,500}?\.\s*Download(?:String|Data|File)\s*\(/,
+    /\bHttpClient\b[\s\S]{0,500}?\.\s*(?:GetAsync|GetStringAsync|PostAsync|SendAsync)\s*\(/,
+    // Environment + console.
+    /\bEnvironment\s*\.\s*GetEnvironmentVariable\s*\(/,
+    /\bConsole\s*\.\s*ReadLine\s*\(/,
+  ],
+  sanitizers: [
+    /\bHttpUtility\s*\.\s*HtmlEncode\b/,
+    /\bHtmlEncoder\s*\.\s*Default\s*\.\s*Encode\b/,
+    /\bAntiXssEncoder\b/,
+    /\bSqlParameter\b/,
+    /\bMySqlParameter\b/,
+    /\bNpgsqlParameter\b/,
+    // EF Core parameterized helpers.
+    /\bFromSqlInterpolated\s*\(/,
+    // Validation.
+    /\bint\s*\.\s*TryParse\s*\(/,
+    /\bGuid\s*\.\s*TryParse\s*\(/,
+    /\bDateTime\s*\.\s*TryParse\s*\(/,
+    /\bRegex\s*\.\s*Replace\s*\(/,
+  ],
+};
+
+const CPP_SUMMARIES = {
+  sources: [
+    // POSIX — environment + user input.
+    /\bgetenv\s*\(/,
+    /\bsecure_getenv\s*\(/,
+    /\bargv\s*\[/,
+    /\bgets\s*\(/,
+    /\bfgets\s*\(/,
+    /\bscanf\s*\(/,
+    /\bfscanf\s*\(/,
+    /\bgetc\s*\(/,
+    /\bfgetc\s*\(/,
+    /\bread\s*\(\s*\d+/,    // unistd read(fd, ...)
+    /\brecv\s*\(/,
+    /\brecvfrom\s*\(/,
+    // OpenSSL / network.
+    /\bBIO_read\s*\(/,
+    /\bSSL_read\s*\(/,
+    // Win32 input.
+    /\bGetCommandLine[AW]?\s*\(/,
+    /\bGetEnvironmentVariable[AW]?\s*\(/,
+    // Standard streams.
+    /\bstd\s*::\s*cin\s*>>/,
+    /\bstd\s*::\s*getline\s*\(\s*std\s*::\s*cin\b/,
+  ],
+  sanitizers: [
+    // Length-checked copies (best-effort).
+    /\bstrncpy\s*\(\s*[^,]+,\s*[^,]+,\s*sizeof\s*\(/,
+    /\bsnprintf\s*\(\s*[^,]+,\s*sizeof\s*\(/,
+    /\bisdigit\s*\(/,
+    /\bisalpha\s*\(/,
+    /\bisalnum\s*\(/,
+    /\bstrtol\s*\(/,
+    /\bstrtoul\s*\(/,
+  ],
+};
+
+const SUMMARIES_BY_LANG = {
+  java:   JAVA_SUMMARIES,
+  csharp: CSHARP_SUMMARIES,
+  cpp:    CPP_SUMMARIES,
+  c:      CPP_SUMMARIES,
+};
+
+// Resolve language from a file path or explicit hint.
+function _langOf(hint, file) {
+  if (hint) return hint;
+  if (!file) return null;
+  if (/\.java$/i.test(file)) return 'java';
+  if (/\.cs$/i.test(file)) return 'csharp';
+  if (/\.(?:c|cc|cpp|cxx|h|hh|hpp)$/i.test(file)) return 'cpp';
+  return null;
+}
+
+/**
+ * Returns true if `text` contains a library-source pattern for the language.
+ */
+export function isLibrarySource(text, langOrFile) {
+  if (!text) return false;
+  const lang = _langOf(typeof langOrFile === 'string' && langOrFile.includes('.') ? null : langOrFile, langOrFile);
+  const s = SUMMARIES_BY_LANG[lang];
+  if (!s) return false;
+  for (const re of s.sources) if (re.test(text)) return true;
+  return false;
+}
+
+/**
+ * Returns true if `text` contains a library-sanitizer pattern for the language.
+ */
+export function isLibrarySanitizer(text, langOrFile) {
+  if (!text) return false;
+  const lang = _langOf(typeof langOrFile === 'string' && langOrFile.includes('.') ? null : langOrFile, langOrFile);
+  const s = SUMMARIES_BY_LANG[lang];
+  if (!s) return false;
+  for (const re of s.sanitizers) if (re.test(text)) return true;
+  return false;
+}
+
+export const _internals = { JAVA_SUMMARIES, CSHARP_SUMMARIES, CPP_SUMMARIES, SUMMARIES_BY_LANG };