@node9/policy-engine 2.8.4 → 2.9.0

package/dist/index.d.mts

@@ -136,6 +136,15 @@ interface DlpPattern {
      * Only set on broad patterns where the regex alone can't distinguish real secrets.
      */
     minEntropy?: number;
+    /**
+     * Structural validator run on the matched token (checksum, version byte).
+     * When present it DECIDES: a passing validator accepts the match outright,
+     * skipping the stopword and entropy heuristics (a checksum-valid token that
+     * happens to contain a stopword substring is a real secret, roughly 1 in
+     * 3,000 real WIF keys); a failing one rejects it. Must never throw; a throw
+     * is treated as "not suppressed" so a validator bug cannot hide a match.
+     */
+    validate?: (raw: string) => boolean;
 }
 declare const DLP_PATTERNS: DlpPattern[];
 /**
@@ -168,11 +177,6 @@ declare const DLP_SCAN_LIMITS: {
     /** Max nesting depth walked; anything deeper is NOT scanned. */
     readonly maxDepth: 5;
 };
-/**
- * Recursively scans an args value for known secret patterns.
- * Handles nested objects, arrays, and JSON-encoded strings.
- * Returns the first match found, or null if clean.
- */
 declare function scanArgs(args: unknown, depth?: number, fieldPath?: string): DlpMatch | null;
 /** Scan a plain text string (e.g. Claude response prose) for DLP patterns. */
 declare function scanText(text: string): DlpMatch | null;
@@ -264,6 +268,25 @@ declare function parseDestHost(token: string): string | null;
  * and parses the host. Deduplicated by host. Pure — no I/O, no DNS.
  */
 declare function extractShellDestinations(command: string): ShellDestination[];
+/** A raw destination-position token from a network binary, BEFORE parseDestHost.
+ *  The SSRF floor needs these because parseDestHost requires a dot and therefore
+ *  drops `2852039166`, which denotes a cloud metadata address (measured: that
+ *  command is allowed today at the strictest egress setting). */
+interface ShellDestToken {
+    token: string;
+    binary: string;
+}
+/**
+ * Destination-position tokens for every network binary in a command, unparsed.
+ *
+ * Same walk and same flag-skipping as extractShellDestinations, so the two agree
+ * on which arguments are destinations. It exists as a sibling rather than a
+ * widening of parseDestHost because the dot requirement there is a load-bearing
+ * false-positive guard: turning every numeric token into a HOST would change
+ * egress verdicts for every user. Asking whether a token DENOTES A PROTECTED
+ * ADDRESS has no false-positive surface, because that comparison is exact.
+ */
+declare function extractShellDestTokens(command: string): ShellDestToken[];
 declare function analyzeFsOperation(command: string): FsOpVerdict | null;
 interface ShellCommandAnalysis {
     /** First word of every CallExpr — the command names invoked. */
@@ -291,6 +314,14 @@ interface EgressPolicy {
     deny: string[];
     /** Auto-allow localhost / RFC1918 / *.local. Default true. */
     allowPrivate: boolean;
+    /** SSRF floor: exempts OVERRIDABLE tiers only (carrier-grade NAT, and
+     *  loopback/RFC1918 when ssrfStrict is on). A tier-1 entry is ignored here
+     *  and rejected at config load with a reason. */
+    ssrfAllow?: readonly string[];
+    /** SSRF floor tier 3: also block loopback and RFC1918. Off by default,
+     *  because a developer talks to those constantly (72 of 308 destinations on
+     *  measured real history). */
+    ssrfStrict?: boolean;
 }
 interface EgressVerdict {
     verdict: 'block' | 'review';
@@ -990,7 +1021,7 @@ declare const SENSITIVE_PATH_RE: RegExp;
  */
 declare const FILE_TOOLS: Set<string>;
 
-type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card';
+type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card' | 'IBAN';
 /**
  * Detect PII patterns in a string. Returns a deduplicated list — one entry
  * per distinct pattern type, never multiple "Email" findings from one input.
@@ -998,13 +1029,40 @@ type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card';
 declare function detectPii(text: string): PiiPattern[];
 declare const REALTIME_PII_PATTERNS: readonly PiiPattern[];
 /**
- * Realtime adapter for detectPii: walks a tool-args value (stringifying
- * objects/arrays) and returns only the high-signal PII patterns found. Used by
- * the authorize path to gate SSN / Credit Card in tool arguments. Pure.
+ * Realtime adapter for detectPii: walks a tool-args value leaf by leaf and
+ * returns only the high-signal PII patterns found. Used by the authorize path
+ * to gate SSN / Credit Card in tool arguments. Pure.
+ *
+ * Walks leaves rather than scanning JSON.stringify(args). Stringifying turns
+ * a real newline into the two characters backslash + `n`, and `n` is a word
+ * character, so a card or SSN that BEGINS A LINE inside a multi-line value
+ * (a CSV being written, for instance) had no \b in front of it and was
+ * invisible to the realtime gate. Raw leaves keep the real newline.
  */
 declare function detectArgsPii(args: unknown): PiiPattern[];
 
-type CanonicalFindingType = 'smart-rule' | 'ast-fs-op' | 'dlp' | 'pii' | 'sensitive-file-read' | 'privilege-escalation' | 'destructive-op' | 'pipe-to-shell' | 'eval-of-remote' | 'loop' | 'long-output-redacted';
+interface CanaryValue {
+    id: string;
+    value: string;
+    retired?: boolean;
+}
+type CanaryView = 'raw' | 'url-decoded' | 'base64-decoded' | 'hex-decoded' | 'separators-stripped';
+interface CanaryHit {
+    id: string;
+    view: CanaryView;
+    fieldPath?: string;
+    retired: boolean;
+}
+/** Values shorter than this are skipped by the matcher AND rejected by the registry (H12):
+ *  below 16 the separators-stripped view starts to collide with ordinary text. */
+declare const CANARY_MIN_LENGTH = 16;
+/** Exact containment of any registered value in any bounded view of the text. */
+declare function matchCanary(text: string, values: readonly CanaryValue[]): CanaryHit | null;
+/** Walks string leaves (depth <= 6, per-field budget), parsing JSON-in-string leaves
+ *  so escaped values are seen (B23), like scanArgs. */
+declare function matchCanaryArgs(args: unknown, values: readonly CanaryValue[]): CanaryHit | null;
+
+type CanonicalFindingType = 'smart-rule' | 'ast-fs-op' | 'dlp' | 'pii' | 'canary' | 'sensitive-file-read' | 'privilege-escalation' | 'destructive-op' | 'pipe-to-shell' | 'eval-of-remote' | 'loop' | 'long-output-redacted';
 type CanonicalAgent = 'claude' | 'gemini' | 'codex' | 'shell';
 type CanonicalSourceType = 'default' | 'shield' | 'user' | 'engine';
 interface CanonicalFinding {
@@ -1083,6 +1141,13 @@ interface ExtractContext {
     toolInspection: Record<string, string>;
     /** DLP enabled flag from PolicyConfig. */
     dlpEnabled: boolean;
+    /** Decoy credentials registered on this machine (value plus kind and plant
+     *  path for the finding text). Optional: absent or empty means no canary
+     *  pass, which keeps extractor output machine-independent in CI (H3). */
+    canaryValues?: ReadonlyArray<CanaryValue & {
+        kind?: string;
+        path?: string;
+    }>;
 }
 interface SessionExtractContext {
     sessionId: string;
@@ -1131,7 +1196,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
  * and fails CI when the hash drifts without a version bump — forgetting
  * is loud, not silent.
  */
-declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v9";
+declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v10";
 /**
  * SHA-256 prefix of the detector-source files
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -1142,7 +1207,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v9";
  * files changed, this hash must change too, and you must consciously
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
  */
-declare const CANONICAL_EXTRACTOR_HASH = "0d6c1ddb9a5af5b7";
+declare const CANONICAL_EXTRACTOR_HASH = "5c786cc174281e51";
 declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
 declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
 /**
@@ -1166,7 +1231,64 @@ declare function dedupeCanonicalFindings(findings: ReadonlyArray<CanonicalFindin
 declare function toScanFinding(c: CanonicalFinding): ScanFinding | null;
 declare function previewArgs(input: Record<string, unknown>, max: number): string;
 
+type SsrfTier = 'metadata' | 'link-local' | 'multicast' | 'unspecified' | 'cgnat' | 'private';
+interface SsrfMatch {
+    tier: SsrfTier;
+    /** false for tier 1: no allowlist entry exempts it. */
+    overridable: boolean;
+    /** 'address' when an IP literal matched, 'hostname' for the metadata name list. */
+    kind: 'address' | 'hostname';
+    /** The canonical address; absent for a hostname match. Never an empty string:
+     *  an empty value is dropped in flight by cloud.ts and the audit shipper. */
+    normalized?: string;
+}
+/** Longest legal DNS name. The caller does NOT reliably bound this: a URL with a
+ *  261-character host reaches us intact (measured), so we bound our own input. */
+declare const SSRF_MAX_HOST = 253;
+/**
+ * Fold any spelling of an IP literal to one canonical address, or null when the
+ * input is not an IP literal (a hostname, or malformed). Never throws.
+ *
+ * IPv4-mapped IPv6 folds to the IPv4 address it denotes (RFC 4291 2.5.5.2), so
+ * `[::ffff:a9fe:a9fe]` and `169.254.169.254` compare equal. Brackets and a zone
+ * id are stripped here: the caller does NOT strip them (measured).
+ */
+declare function normalizeIpLiteral(host: string): string | null;
+/**
+ * Classify a destination host. Returns null when it is not a protected address,
+ * which means the ordinary egress policy decides. Never throws.
+ *
+ * Ordering is significant: the exact metadata addresses are checked before the
+ * link-local range that contains them, so the reason names metadata.
+ */
+declare function classifySsrf(host: string): SsrfMatch | null;
+interface SsrfVerdict extends SsrfMatch {
+    /** The token as written in the command. */
+    host: string;
+    binary: string;
+    reason: string;
+}
+interface SsrfFloorOptions {
+    /** Exempts OVERRIDABLE tiers only. A tier-1 entry here is ignored (and is
+     *  rejected at config load with a reason, never silently). */
+    ssrfAllow?: readonly string[];
+    /** Opt-in tier 3: loopback and RFC1918. Off by default: a developer talks to
+     *  those constantly (72 of 308 destinations on measured real history). */
+    ssrfStrict?: boolean;
+}
+/**
+ * The floor. Returns the first protected destination, or null.
+ *
+ * Runs unconditionally: not gated on egress.enabled, mode, allow or allowPrivate.
+ * The one thing that does switch it off is `node9 pause`, which returns before
+ * every gate; that is stated as a limit rather than special-cased here.
+ */
+declare function ssrfFloor(tokens: ReadonlyArray<{
+    token: string;
+    binary: string;
+}>, opts?: SsrfFloorOptions): SsrfVerdict | null;
+
 /** Engine version stamped on audit entries for future drift detection. */
 declare const ENGINE_VERSION = "1.4.0";
 
-export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COST_PER_LOOP_ITER_USD, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestination, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, extractShellDestinations, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, parseDestHost, previewArgs, redactText, resolvePinned, scanArgs, scanInjection, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };
+export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COST_PER_LOOP_ITER_USD, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestToken, type ShellDestination, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type SsrfFloorOptions, type SsrfMatch, type SsrfTier, type SsrfVerdict, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifySsrf, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeIpLiteral, parseAllSshHostsFromCommand, parseDestHost, previewArgs, redactText, resolvePinned, scanArgs, scanInjection, scanText, sensitivePathMatch, ssrfFloor, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };

package/dist/index.d.ts

@@ -136,6 +136,15 @@ interface DlpPattern {
      * Only set on broad patterns where the regex alone can't distinguish real secrets.
      */
     minEntropy?: number;
+    /**
+     * Structural validator run on the matched token (checksum, version byte).
+     * When present it DECIDES: a passing validator accepts the match outright,
+     * skipping the stopword and entropy heuristics (a checksum-valid token that
+     * happens to contain a stopword substring is a real secret, roughly 1 in
+     * 3,000 real WIF keys); a failing one rejects it. Must never throw; a throw
+     * is treated as "not suppressed" so a validator bug cannot hide a match.
+     */
+    validate?: (raw: string) => boolean;
 }
 declare const DLP_PATTERNS: DlpPattern[];
 /**
@@ -168,11 +177,6 @@ declare const DLP_SCAN_LIMITS: {
     /** Max nesting depth walked; anything deeper is NOT scanned. */
     readonly maxDepth: 5;
 };
-/**
- * Recursively scans an args value for known secret patterns.
- * Handles nested objects, arrays, and JSON-encoded strings.
- * Returns the first match found, or null if clean.
- */
 declare function scanArgs(args: unknown, depth?: number, fieldPath?: string): DlpMatch | null;
 /** Scan a plain text string (e.g. Claude response prose) for DLP patterns. */
 declare function scanText(text: string): DlpMatch | null;
@@ -264,6 +268,25 @@ declare function parseDestHost(token: string): string | null;
  * and parses the host. Deduplicated by host. Pure — no I/O, no DNS.
  */
 declare function extractShellDestinations(command: string): ShellDestination[];
+/** A raw destination-position token from a network binary, BEFORE parseDestHost.
+ *  The SSRF floor needs these because parseDestHost requires a dot and therefore
+ *  drops `2852039166`, which denotes a cloud metadata address (measured: that
+ *  command is allowed today at the strictest egress setting). */
+interface ShellDestToken {
+    token: string;
+    binary: string;
+}
+/**
+ * Destination-position tokens for every network binary in a command, unparsed.
+ *
+ * Same walk and same flag-skipping as extractShellDestinations, so the two agree
+ * on which arguments are destinations. It exists as a sibling rather than a
+ * widening of parseDestHost because the dot requirement there is a load-bearing
+ * false-positive guard: turning every numeric token into a HOST would change
+ * egress verdicts for every user. Asking whether a token DENOTES A PROTECTED
+ * ADDRESS has no false-positive surface, because that comparison is exact.
+ */
+declare function extractShellDestTokens(command: string): ShellDestToken[];
 declare function analyzeFsOperation(command: string): FsOpVerdict | null;
 interface ShellCommandAnalysis {
     /** First word of every CallExpr — the command names invoked. */
@@ -291,6 +314,14 @@ interface EgressPolicy {
     deny: string[];
     /** Auto-allow localhost / RFC1918 / *.local. Default true. */
     allowPrivate: boolean;
+    /** SSRF floor: exempts OVERRIDABLE tiers only (carrier-grade NAT, and
+     *  loopback/RFC1918 when ssrfStrict is on). A tier-1 entry is ignored here
+     *  and rejected at config load with a reason. */
+    ssrfAllow?: readonly string[];
+    /** SSRF floor tier 3: also block loopback and RFC1918. Off by default,
+     *  because a developer talks to those constantly (72 of 308 destinations on
+     *  measured real history). */
+    ssrfStrict?: boolean;
 }
 interface EgressVerdict {
     verdict: 'block' | 'review';
@@ -990,7 +1021,7 @@ declare const SENSITIVE_PATH_RE: RegExp;
  */
 declare const FILE_TOOLS: Set<string>;
 
-type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card';
+type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card' | 'IBAN';
 /**
  * Detect PII patterns in a string. Returns a deduplicated list — one entry
  * per distinct pattern type, never multiple "Email" findings from one input.
@@ -998,13 +1029,40 @@ type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card';
 declare function detectPii(text: string): PiiPattern[];
 declare const REALTIME_PII_PATTERNS: readonly PiiPattern[];
 /**
- * Realtime adapter for detectPii: walks a tool-args value (stringifying
- * objects/arrays) and returns only the high-signal PII patterns found. Used by
- * the authorize path to gate SSN / Credit Card in tool arguments. Pure.
+ * Realtime adapter for detectPii: walks a tool-args value leaf by leaf and
+ * returns only the high-signal PII patterns found. Used by the authorize path
+ * to gate SSN / Credit Card in tool arguments. Pure.
+ *
+ * Walks leaves rather than scanning JSON.stringify(args). Stringifying turns
+ * a real newline into the two characters backslash + `n`, and `n` is a word
+ * character, so a card or SSN that BEGINS A LINE inside a multi-line value
+ * (a CSV being written, for instance) had no \b in front of it and was
+ * invisible to the realtime gate. Raw leaves keep the real newline.
  */
 declare function detectArgsPii(args: unknown): PiiPattern[];
 
-type CanonicalFindingType = 'smart-rule' | 'ast-fs-op' | 'dlp' | 'pii' | 'sensitive-file-read' | 'privilege-escalation' | 'destructive-op' | 'pipe-to-shell' | 'eval-of-remote' | 'loop' | 'long-output-redacted';
+interface CanaryValue {
+    id: string;
+    value: string;
+    retired?: boolean;
+}
+type CanaryView = 'raw' | 'url-decoded' | 'base64-decoded' | 'hex-decoded' | 'separators-stripped';
+interface CanaryHit {
+    id: string;
+    view: CanaryView;
+    fieldPath?: string;
+    retired: boolean;
+}
+/** Values shorter than this are skipped by the matcher AND rejected by the registry (H12):
+ *  below 16 the separators-stripped view starts to collide with ordinary text. */
+declare const CANARY_MIN_LENGTH = 16;
+/** Exact containment of any registered value in any bounded view of the text. */
+declare function matchCanary(text: string, values: readonly CanaryValue[]): CanaryHit | null;
+/** Walks string leaves (depth <= 6, per-field budget), parsing JSON-in-string leaves
+ *  so escaped values are seen (B23), like scanArgs. */
+declare function matchCanaryArgs(args: unknown, values: readonly CanaryValue[]): CanaryHit | null;
+
+type CanonicalFindingType = 'smart-rule' | 'ast-fs-op' | 'dlp' | 'pii' | 'canary' | 'sensitive-file-read' | 'privilege-escalation' | 'destructive-op' | 'pipe-to-shell' | 'eval-of-remote' | 'loop' | 'long-output-redacted';
 type CanonicalAgent = 'claude' | 'gemini' | 'codex' | 'shell';
 type CanonicalSourceType = 'default' | 'shield' | 'user' | 'engine';
 interface CanonicalFinding {
@@ -1083,6 +1141,13 @@ interface ExtractContext {
     toolInspection: Record<string, string>;
     /** DLP enabled flag from PolicyConfig. */
     dlpEnabled: boolean;
+    /** Decoy credentials registered on this machine (value plus kind and plant
+     *  path for the finding text). Optional: absent or empty means no canary
+     *  pass, which keeps extractor output machine-independent in CI (H3). */
+    canaryValues?: ReadonlyArray<CanaryValue & {
+        kind?: string;
+        path?: string;
+    }>;
 }
 interface SessionExtractContext {
     sessionId: string;
@@ -1131,7 +1196,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
  * and fails CI when the hash drifts without a version bump — forgetting
  * is loud, not silent.
  */
-declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v9";
+declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v10";
 /**
  * SHA-256 prefix of the detector-source files
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -1142,7 +1207,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v9";
  * files changed, this hash must change too, and you must consciously
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
  */
-declare const CANONICAL_EXTRACTOR_HASH = "0d6c1ddb9a5af5b7";
+declare const CANONICAL_EXTRACTOR_HASH = "5c786cc174281e51";
 declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
 declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
 /**
@@ -1166,7 +1231,64 @@ declare function dedupeCanonicalFindings(findings: ReadonlyArray<CanonicalFindin
 declare function toScanFinding(c: CanonicalFinding): ScanFinding | null;
 declare function previewArgs(input: Record<string, unknown>, max: number): string;
 
+type SsrfTier = 'metadata' | 'link-local' | 'multicast' | 'unspecified' | 'cgnat' | 'private';
+interface SsrfMatch {
+    tier: SsrfTier;
+    /** false for tier 1: no allowlist entry exempts it. */
+    overridable: boolean;
+    /** 'address' when an IP literal matched, 'hostname' for the metadata name list. */
+    kind: 'address' | 'hostname';
+    /** The canonical address; absent for a hostname match. Never an empty string:
+     *  an empty value is dropped in flight by cloud.ts and the audit shipper. */
+    normalized?: string;
+}
+/** Longest legal DNS name. The caller does NOT reliably bound this: a URL with a
+ *  261-character host reaches us intact (measured), so we bound our own input. */
+declare const SSRF_MAX_HOST = 253;
+/**
+ * Fold any spelling of an IP literal to one canonical address, or null when the
+ * input is not an IP literal (a hostname, or malformed). Never throws.
+ *
+ * IPv4-mapped IPv6 folds to the IPv4 address it denotes (RFC 4291 2.5.5.2), so
+ * `[::ffff:a9fe:a9fe]` and `169.254.169.254` compare equal. Brackets and a zone
+ * id are stripped here: the caller does NOT strip them (measured).
+ */
+declare function normalizeIpLiteral(host: string): string | null;
+/**
+ * Classify a destination host. Returns null when it is not a protected address,
+ * which means the ordinary egress policy decides. Never throws.
+ *
+ * Ordering is significant: the exact metadata addresses are checked before the
+ * link-local range that contains them, so the reason names metadata.
+ */
+declare function classifySsrf(host: string): SsrfMatch | null;
+interface SsrfVerdict extends SsrfMatch {
+    /** The token as written in the command. */
+    host: string;
+    binary: string;
+    reason: string;
+}
+interface SsrfFloorOptions {
+    /** Exempts OVERRIDABLE tiers only. A tier-1 entry here is ignored (and is
+     *  rejected at config load with a reason, never silently). */
+    ssrfAllow?: readonly string[];
+    /** Opt-in tier 3: loopback and RFC1918. Off by default: a developer talks to
+     *  those constantly (72 of 308 destinations on measured real history). */
+    ssrfStrict?: boolean;
+}
+/**
+ * The floor. Returns the first protected destination, or null.
+ *
+ * Runs unconditionally: not gated on egress.enabled, mode, allow or allowPrivate.
+ * The one thing that does switch it off is `node9 pause`, which returns before
+ * every gate; that is stated as a limit rather than special-cased here.
+ */
+declare function ssrfFloor(tokens: ReadonlyArray<{
+    token: string;
+    binary: string;
+}>, opts?: SsrfFloorOptions): SsrfVerdict | null;
+
 /** Engine version stamped on audit entries for future drift detection. */
 declare const ENGINE_VERSION = "1.4.0";
 
-export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COST_PER_LOOP_ITER_USD, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestination, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, extractShellDestinations, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, parseDestHost, previewArgs, redactText, resolvePinned, scanArgs, scanInjection, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };
+export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COST_PER_LOOP_ITER_USD, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestToken, type ShellDestination, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type SsrfFloorOptions, type SsrfMatch, type SsrfTier, type SsrfVerdict, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifySsrf, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeIpLiteral, parseAllSshHostsFromCommand, parseDestHost, previewArgs, redactText, resolvePinned, scanArgs, scanInjection, scanText, sensitivePathMatch, ssrfFloor, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };