@node9/policy-engine 2.35.0 → 2.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -193,6 +193,10 @@ interface SsrfVerdict extends SsrfMatch {
193
193
  host: string;
194
194
  binary: string;
195
195
  reason: string;
196
+ /** 'review' for a default-reachable address written in a disguised form
197
+ * (`0x7f000001`, `127.1`, `[::ffff:127.0.0.1]`) while the strict tier is
198
+ * off; 'block' everywhere else, as before. */
199
+ decision: 'block' | 'review';
196
200
  }
197
201
  interface SsrfFloorOptions {
198
202
  /** Exempts OVERRIDABLE tiers only. A tier-1 entry here is ignored (and is
@@ -201,6 +205,10 @@ interface SsrfFloorOptions {
201
205
  /** Opt-in tier 3: loopback and RFC1918. Off by default: a developer talks to
202
206
  * those constantly (72 of 308 destinations on measured real history). */
203
207
  ssrfStrict?: boolean;
208
+ /** The egress policy's allowPrivate, when egress is enabled: an operator who
209
+ * let private destinations through on purpose is not asked about a
210
+ * disguised spelling of one (ssrf-pins V3). */
211
+ allowPrivate?: boolean;
204
212
  }
205
213
  /**
206
214
  * Does this exemption list release this address?
@@ -406,6 +414,8 @@ interface FileAccess {
406
414
  cwd?: string;
407
415
  /** A read whose content leaves the machine as a request body or an upload. */
408
416
  upload?: true;
417
+ /** A directory listing (`ls`, `tree`, find's start points): the entry names, not a file's content. */
418
+ listing?: true;
409
419
  /** Unquoted shell pattern. Quoted metacharacters are escaped in this value. */
410
420
  glob?: string;
411
421
  /** The pattern is find's, not the shell's: `*` also selects dotfiles. */
@@ -493,6 +503,13 @@ interface CopyShape {
493
503
  archive?: 'tar' | 'zip' | 'ar' | '7z';
494
504
  /** flagOperand: the flags (short letter or long name) whose operand is the source. */
495
505
  sourceFlags?: string[];
506
+ /**
507
+ * flagOperand: the file a flag's operand names, or null when it names none.
508
+ * `curl -d @FILE` sends FILE and `curl -d '{"k":1}'` sends text; the flag
509
+ * (`-T`, `--data-binary`, resolved from its bundle or abbreviation) and the
510
+ * operand as written are passed. Absent, the operand is the file.
511
+ */
512
+ sourceOperand?: (flag: string, value: string) => string | null;
496
513
  /** GNU `-t DIR` / `--target-directory`: the destination is in a flag. */
497
514
  targetDirFlag?: boolean;
498
515
  /** Flags whose operand is NEVER a source: a short LETTER ('i') or a long name ('--exclude'). */
@@ -574,6 +591,17 @@ interface PositionedArg {
574
591
  * exactly the pre-stage-3 filter, which jail-position.spec.ts pins.
575
592
  */
576
593
  declare function positionedArgs(words: (string | null)[], from?: number, to?: number): PositionedArg[];
594
+ /**
595
+ * The script files a command runs, as written: the first operand of a shell
596
+ * (`bash x.sh`, `sh -e ./x.sh`, `source env.sh`, `. ./lib.sh`) and a head that
597
+ * is itself a path (`./deploy.sh`, `/tmp/run.sh`, `scripts/build.sh`). `-c`
598
+ * payloads are inline code, not files, and are read by the payload walkers.
599
+ * Wrappers (`sudo`, `env`, `timeout`) are seen through. Paths under
600
+ * `node_modules` or a `.bin` directory are installed tools, not scripts the
601
+ * session wrote, and are left out. Pure: the caller resolves against its cwd
602
+ * and decides whether a path is one the session wrote (fw#372 A3).
603
+ */
604
+ declare function shellScriptOperands(command: string): string[];
577
605
  interface ShellDestination {
578
606
  /** Extracted hostname, lowercased (e.g. "evil.com", "10.0.0.5"). */
579
607
  host: string;
@@ -994,7 +1022,13 @@ declare const DLP_SCAN_LIMITS: {
994
1022
  readonly maxDepth: 5;
995
1023
  };
996
1024
  declare function scanArgs(args: unknown, depth?: number, fieldPath?: string): DlpMatch | null;
997
- /** Scan a plain text string (e.g. Claude response prose) for DLP patterns. */
1025
+ /**
1026
+ * Scan a plain text string (tool output, Claude response prose) for DLP
1027
+ * patterns. The text as written first; then its decoded views (base64, hex,
1028
+ * percent, the bounded set the argument gate reads), so a credential a tool
1029
+ * returns encoded is still a finding (fw#372 B7). The first-level decoding is
1030
+ * proportional to the text and nested layers are budgeted, as in the gate.
1031
+ */
998
1032
  declare function scanText(text: string): DlpMatch | null;
999
1033
  declare function redactText(text: string): {
1000
1034
  result: string;
@@ -1846,13 +1880,15 @@ declare const SENSITIVE_PATH_RE: RegExp;
1846
1880
  */
1847
1881
  declare const FILE_TOOLS: Set<string>;
1848
1882
 
1849
- type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card' | 'IBAN';
1883
+ type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card' | 'IBAN' | 'Bank Routing Number' | 'National ID';
1850
1884
  /**
1851
1885
  * Detect PII patterns in a string. Returns a deduplicated list — one entry
1852
1886
  * per distinct pattern type, never multiple "Email" findings from one input.
1853
1887
  */
1854
1888
  declare function detectPii(text: string): PiiPattern[];
1855
1889
  declare const REALTIME_PII_PATTERNS: readonly PiiPattern[];
1890
+ /** Every string leaf of a tool call's arguments, joined by newlines, bounded. */
1891
+ declare function argumentLeavesText(args: unknown, limit?: number): string;
1856
1892
  /**
1857
1893
  * Realtime adapter for detectPii: walks a tool-args value leaf by leaf and
1858
1894
  * returns only the high-signal PII patterns found. Used by the authorize path
@@ -2021,7 +2057,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
2021
2057
  * and fails CI when the hash drifts without a version bump — forgetting
2022
2058
  * is loud, not silent.
2023
2059
  */
2024
- declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v28";
2060
+ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v29";
2025
2061
  /**
2026
2062
  * SHA-256 prefix of the detector-source files
2027
2063
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -2032,7 +2068,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v28";
2032
2068
  * files changed, this hash must change too, and you must consciously
2033
2069
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
2034
2070
  */
2035
- declare const CANONICAL_EXTRACTOR_HASH = "11df698796585cbe";
2071
+ declare const CANONICAL_EXTRACTOR_HASH = "3b936dab47d27942";
2036
2072
  declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
2037
2073
  declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
2038
2074
  /**
@@ -2093,6 +2129,8 @@ interface DestinationHit extends SsrfMatch {
2093
2129
  argPath: string;
2094
2130
  host: string;
2095
2131
  reason: string;
2132
+ /** 'review' for a disguised spelling of a default-reachable address. */
2133
+ decision: 'block' | 'review';
2096
2134
  }
2097
2135
  /**
2098
2136
  * Judge a non-shell tool call. Returns the first protected destination, or
@@ -2102,6 +2140,7 @@ interface DestinationHit extends SsrfMatch {
2102
2140
  declare function ssrfDestinationFloor(toolName: string, args: unknown, opts?: {
2103
2141
  ssrfStrict?: boolean;
2104
2142
  ssrfAllow?: readonly string[];
2143
+ allowPrivate?: boolean;
2105
2144
  }): DestinationHit | null;
2106
2145
 
2107
2146
  declare const ARGUMENT_SCAN_LIMITS: {
@@ -2141,5 +2180,5 @@ declare function scanArgumentSecrets(args: unknown): DlpMatch | null;
2141
2180
  /** Engine version stamped on audit entries for future drift detection. */
2142
2181
  declare const ENGINE_VERSION = "1.4.0";
2143
2182
 
2144
- export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, CHECKS, CHECK_BY_ID, CHECK_GROUPS, CHECK_TEXT, CHECK_VERDICT_RANK, COMMAND_WRAPPERS, CONFIGURABLE_CHECK_IDS, COPY_VERBS, COST_PER_LOOP_ITER_USD, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, ENGINE_VERSION, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, REALTIME_PII_PATTERNS, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, TUNING_FIELDS, VERDICTS, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, catalogSettingsFromConfig, checkDangerousSql, checkIdForCheckedBy, checkIdForRule, checkToLegacyPolicy, checkValue, checksFromLegacyPolicy, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, entryDisplay, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hashDestination, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isDestructiveToolName, isHashedEntry, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isMaskedKind, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, maskDestination, maskPersonalData, maskPersonalValue, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, matchesTrustedEntry, matchesTrustedList, narrativeRuleLabel, normalizeCommandForPolicy, normalizeDestination, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, normalizeRecipient, normalizeTrustedEntry, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolveAllChecks, resolveCheck, resolveCheckMap, resolvePinned, resolveShellInput, safeMessage, sampleCopyCommand, scanArgs, scanArgumentSecrets, scanInjection, scanText, scanViews, sensitivePathMatch, shellRuleArgs, ssrfCheckId, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripInvisible, stripTerminalEscapes, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, trustedEntryOf, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };
2183
+ export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, CHECKS, CHECK_BY_ID, CHECK_GROUPS, CHECK_TEXT, CHECK_VERDICT_RANK, COMMAND_WRAPPERS, CONFIGURABLE_CHECK_IDS, COPY_VERBS, COST_PER_LOOP_ITER_USD, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, ENGINE_VERSION, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, REALTIME_PII_PATTERNS, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, TUNING_FIELDS, VERDICTS, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, argumentLeavesText, catalogSettingsFromConfig, checkDangerousSql, checkIdForCheckedBy, checkIdForRule, checkToLegacyPolicy, checkValue, checksFromLegacyPolicy, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, entryDisplay, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hashDestination, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isDestructiveToolName, isHashedEntry, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isMaskedKind, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, maskDestination, maskPersonalData, maskPersonalValue, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, matchesTrustedEntry, matchesTrustedList, narrativeRuleLabel, normalizeCommandForPolicy, normalizeDestination, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, normalizeRecipient, normalizeTrustedEntry, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolveAllChecks, resolveCheck, resolveCheckMap, resolvePinned, resolveShellInput, safeMessage, sampleCopyCommand, scanArgs, scanArgumentSecrets, scanInjection, scanText, scanViews, sensitivePathMatch, shellRuleArgs, shellScriptOperands, ssrfCheckId, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripInvisible, stripTerminalEscapes, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, trustedEntryOf, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };
2145
2184
  export type { ArgumentInspectionResult, AuditEntryForClassify, BlastEnvFinding, BlastFinding, BlastResult, BlastSummary, CanaryHit, CanaryValue, CanaryView, CanonicalAgent, CanonicalFinding, CanonicalFindingType, CanonicalSourceType, CatalogSettings, CheckDef, CheckGroup, CheckSource, CheckText, Destination, DestinationKind, DlpMatch, EgressPolicy, EgressVerdict, ExtractContext, FileAccess, FileAccessContext, FsOpVerdict, InjectionConfidence, InjectionContext, InjectionMatch, InspectionInput, InspectionLayers, LegacyPolicyKnobs, LoopWindowEvaluation, PackageEcosystem, PackageInstallRequest, PiiPattern, PipeChainAnalysis, PolicyConfig, PolicyContext, PolicyHostHooks, PolicyVerdict, PositionedArg, ProtectedFileVerdict, ProvenanceLookup, ProvenanceTrust, ResolvedCheck, RiskMetadata, ScanFinding, ScanSignals, ScanSummary, ScanView, ScoreTier, SessionExtractContext, SessionToolCall, Severity, ShellCommandAnalysis, ShellDestToken, ShellDestination, ShellExposure, ShellInputResolution, ShieldDefinition, ShieldOverrides, ShieldVerdict, SmartCondition, SmartRule, SsrfFloorOptions, SsrfMatch, SsrfTier, SsrfVerdict, ToolCallEntry, ToolCallRecord, ToolInspection, ToolInspectionEntry, TuningField, Verdict };
package/dist/index.d.ts CHANGED
@@ -193,6 +193,10 @@ interface SsrfVerdict extends SsrfMatch {
193
193
  host: string;
194
194
  binary: string;
195
195
  reason: string;
196
+ /** 'review' for a default-reachable address written in a disguised form
197
+ * (`0x7f000001`, `127.1`, `[::ffff:127.0.0.1]`) while the strict tier is
198
+ * off; 'block' everywhere else, as before. */
199
+ decision: 'block' | 'review';
196
200
  }
197
201
  interface SsrfFloorOptions {
198
202
  /** Exempts OVERRIDABLE tiers only. A tier-1 entry here is ignored (and is
@@ -201,6 +205,10 @@ interface SsrfFloorOptions {
201
205
  /** Opt-in tier 3: loopback and RFC1918. Off by default: a developer talks to
202
206
  * those constantly (72 of 308 destinations on measured real history). */
203
207
  ssrfStrict?: boolean;
208
+ /** The egress policy's allowPrivate, when egress is enabled: an operator who
209
+ * let private destinations through on purpose is not asked about a
210
+ * disguised spelling of one (ssrf-pins V3). */
211
+ allowPrivate?: boolean;
204
212
  }
205
213
  /**
206
214
  * Does this exemption list release this address?
@@ -406,6 +414,8 @@ interface FileAccess {
406
414
  cwd?: string;
407
415
  /** A read whose content leaves the machine as a request body or an upload. */
408
416
  upload?: true;
417
+ /** A directory listing (`ls`, `tree`, find's start points): the entry names, not a file's content. */
418
+ listing?: true;
409
419
  /** Unquoted shell pattern. Quoted metacharacters are escaped in this value. */
410
420
  glob?: string;
411
421
  /** The pattern is find's, not the shell's: `*` also selects dotfiles. */
@@ -493,6 +503,13 @@ interface CopyShape {
493
503
  archive?: 'tar' | 'zip' | 'ar' | '7z';
494
504
  /** flagOperand: the flags (short letter or long name) whose operand is the source. */
495
505
  sourceFlags?: string[];
506
+ /**
507
+ * flagOperand: the file a flag's operand names, or null when it names none.
508
+ * `curl -d @FILE` sends FILE and `curl -d '{"k":1}'` sends text; the flag
509
+ * (`-T`, `--data-binary`, resolved from its bundle or abbreviation) and the
510
+ * operand as written are passed. Absent, the operand is the file.
511
+ */
512
+ sourceOperand?: (flag: string, value: string) => string | null;
496
513
  /** GNU `-t DIR` / `--target-directory`: the destination is in a flag. */
497
514
  targetDirFlag?: boolean;
498
515
  /** Flags whose operand is NEVER a source: a short LETTER ('i') or a long name ('--exclude'). */
@@ -574,6 +591,17 @@ interface PositionedArg {
574
591
  * exactly the pre-stage-3 filter, which jail-position.spec.ts pins.
575
592
  */
576
593
  declare function positionedArgs(words: (string | null)[], from?: number, to?: number): PositionedArg[];
594
+ /**
595
+ * The script files a command runs, as written: the first operand of a shell
596
+ * (`bash x.sh`, `sh -e ./x.sh`, `source env.sh`, `. ./lib.sh`) and a head that
597
+ * is itself a path (`./deploy.sh`, `/tmp/run.sh`, `scripts/build.sh`). `-c`
598
+ * payloads are inline code, not files, and are read by the payload walkers.
599
+ * Wrappers (`sudo`, `env`, `timeout`) are seen through. Paths under
600
+ * `node_modules` or a `.bin` directory are installed tools, not scripts the
601
+ * session wrote, and are left out. Pure: the caller resolves against its cwd
602
+ * and decides whether a path is one the session wrote (fw#372 A3).
603
+ */
604
+ declare function shellScriptOperands(command: string): string[];
577
605
  interface ShellDestination {
578
606
  /** Extracted hostname, lowercased (e.g. "evil.com", "10.0.0.5"). */
579
607
  host: string;
@@ -994,7 +1022,13 @@ declare const DLP_SCAN_LIMITS: {
994
1022
  readonly maxDepth: 5;
995
1023
  };
996
1024
  declare function scanArgs(args: unknown, depth?: number, fieldPath?: string): DlpMatch | null;
997
- /** Scan a plain text string (e.g. Claude response prose) for DLP patterns. */
1025
+ /**
1026
+ * Scan a plain text string (tool output, Claude response prose) for DLP
1027
+ * patterns. The text as written first; then its decoded views (base64, hex,
1028
+ * percent, the bounded set the argument gate reads), so a credential a tool
1029
+ * returns encoded is still a finding (fw#372 B7). The first-level decoding is
1030
+ * proportional to the text and nested layers are budgeted, as in the gate.
1031
+ */
998
1032
  declare function scanText(text: string): DlpMatch | null;
999
1033
  declare function redactText(text: string): {
1000
1034
  result: string;
@@ -1846,13 +1880,15 @@ declare const SENSITIVE_PATH_RE: RegExp;
1846
1880
  */
1847
1881
  declare const FILE_TOOLS: Set<string>;
1848
1882
 
1849
- type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card' | 'IBAN';
1883
+ type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card' | 'IBAN' | 'Bank Routing Number' | 'National ID';
1850
1884
  /**
1851
1885
  * Detect PII patterns in a string. Returns a deduplicated list — one entry
1852
1886
  * per distinct pattern type, never multiple "Email" findings from one input.
1853
1887
  */
1854
1888
  declare function detectPii(text: string): PiiPattern[];
1855
1889
  declare const REALTIME_PII_PATTERNS: readonly PiiPattern[];
1890
+ /** Every string leaf of a tool call's arguments, joined by newlines, bounded. */
1891
+ declare function argumentLeavesText(args: unknown, limit?: number): string;
1856
1892
  /**
1857
1893
  * Realtime adapter for detectPii: walks a tool-args value leaf by leaf and
1858
1894
  * returns only the high-signal PII patterns found. Used by the authorize path
@@ -2021,7 +2057,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
2021
2057
  * and fails CI when the hash drifts without a version bump — forgetting
2022
2058
  * is loud, not silent.
2023
2059
  */
2024
- declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v28";
2060
+ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v29";
2025
2061
  /**
2026
2062
  * SHA-256 prefix of the detector-source files
2027
2063
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -2032,7 +2068,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v28";
2032
2068
  * files changed, this hash must change too, and you must consciously
2033
2069
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
2034
2070
  */
2035
- declare const CANONICAL_EXTRACTOR_HASH = "11df698796585cbe";
2071
+ declare const CANONICAL_EXTRACTOR_HASH = "3b936dab47d27942";
2036
2072
  declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
2037
2073
  declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
2038
2074
  /**
@@ -2093,6 +2129,8 @@ interface DestinationHit extends SsrfMatch {
2093
2129
  argPath: string;
2094
2130
  host: string;
2095
2131
  reason: string;
2132
+ /** 'review' for a disguised spelling of a default-reachable address. */
2133
+ decision: 'block' | 'review';
2096
2134
  }
2097
2135
  /**
2098
2136
  * Judge a non-shell tool call. Returns the first protected destination, or
@@ -2102,6 +2140,7 @@ interface DestinationHit extends SsrfMatch {
2102
2140
  declare function ssrfDestinationFloor(toolName: string, args: unknown, opts?: {
2103
2141
  ssrfStrict?: boolean;
2104
2142
  ssrfAllow?: readonly string[];
2143
+ allowPrivate?: boolean;
2105
2144
  }): DestinationHit | null;
2106
2145
 
2107
2146
  declare const ARGUMENT_SCAN_LIMITS: {
@@ -2141,5 +2180,5 @@ declare function scanArgumentSecrets(args: unknown): DlpMatch | null;
2141
2180
  /** Engine version stamped on audit entries for future drift detection. */
2142
2181
  declare const ENGINE_VERSION = "1.4.0";
2143
2182
 
2144
- export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, CHECKS, CHECK_BY_ID, CHECK_GROUPS, CHECK_TEXT, CHECK_VERDICT_RANK, COMMAND_WRAPPERS, CONFIGURABLE_CHECK_IDS, COPY_VERBS, COST_PER_LOOP_ITER_USD, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, ENGINE_VERSION, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, REALTIME_PII_PATTERNS, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, TUNING_FIELDS, VERDICTS, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, catalogSettingsFromConfig, checkDangerousSql, checkIdForCheckedBy, checkIdForRule, checkToLegacyPolicy, checkValue, checksFromLegacyPolicy, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, entryDisplay, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hashDestination, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isDestructiveToolName, isHashedEntry, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isMaskedKind, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, maskDestination, maskPersonalData, maskPersonalValue, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, matchesTrustedEntry, matchesTrustedList, narrativeRuleLabel, normalizeCommandForPolicy, normalizeDestination, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, normalizeRecipient, normalizeTrustedEntry, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolveAllChecks, resolveCheck, resolveCheckMap, resolvePinned, resolveShellInput, safeMessage, sampleCopyCommand, scanArgs, scanArgumentSecrets, scanInjection, scanText, scanViews, sensitivePathMatch, shellRuleArgs, ssrfCheckId, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripInvisible, stripTerminalEscapes, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, trustedEntryOf, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };
2183
+ export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, CHECKS, CHECK_BY_ID, CHECK_GROUPS, CHECK_TEXT, CHECK_VERDICT_RANK, COMMAND_WRAPPERS, CONFIGURABLE_CHECK_IDS, COPY_VERBS, COST_PER_LOOP_ITER_USD, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, ENGINE_VERSION, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, REALTIME_PII_PATTERNS, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, TUNING_FIELDS, VERDICTS, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, argumentLeavesText, catalogSettingsFromConfig, checkDangerousSql, checkIdForCheckedBy, checkIdForRule, checkToLegacyPolicy, checkValue, checksFromLegacyPolicy, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, entryDisplay, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hashDestination, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isDestructiveToolName, isHashedEntry, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isMaskedKind, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, maskDestination, maskPersonalData, maskPersonalValue, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, matchesTrustedEntry, matchesTrustedList, narrativeRuleLabel, normalizeCommandForPolicy, normalizeDestination, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, normalizeRecipient, normalizeTrustedEntry, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolveAllChecks, resolveCheck, resolveCheckMap, resolvePinned, resolveShellInput, safeMessage, sampleCopyCommand, scanArgs, scanArgumentSecrets, scanInjection, scanText, scanViews, sensitivePathMatch, shellRuleArgs, shellScriptOperands, ssrfCheckId, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripInvisible, stripTerminalEscapes, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, trustedEntryOf, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };
2145
2184
  export type { ArgumentInspectionResult, AuditEntryForClassify, BlastEnvFinding, BlastFinding, BlastResult, BlastSummary, CanaryHit, CanaryValue, CanaryView, CanonicalAgent, CanonicalFinding, CanonicalFindingType, CanonicalSourceType, CatalogSettings, CheckDef, CheckGroup, CheckSource, CheckText, Destination, DestinationKind, DlpMatch, EgressPolicy, EgressVerdict, ExtractContext, FileAccess, FileAccessContext, FsOpVerdict, InjectionConfidence, InjectionContext, InjectionMatch, InspectionInput, InspectionLayers, LegacyPolicyKnobs, LoopWindowEvaluation, PackageEcosystem, PackageInstallRequest, PiiPattern, PipeChainAnalysis, PolicyConfig, PolicyContext, PolicyHostHooks, PolicyVerdict, PositionedArg, ProtectedFileVerdict, ProvenanceLookup, ProvenanceTrust, ResolvedCheck, RiskMetadata, ScanFinding, ScanSignals, ScanSummary, ScanView, ScoreTier, SessionExtractContext, SessionToolCall, Severity, ShellCommandAnalysis, ShellDestToken, ShellDestination, ShellExposure, ShellInputResolution, ShieldDefinition, ShieldOverrides, ShieldVerdict, SmartCondition, SmartRule, SsrfFloorOptions, SsrfMatch, SsrfTier, SsrfVerdict, ToolCallEntry, ToolCallRecord, ToolInspection, ToolInspectionEntry, TuningField, Verdict };