@node9/policy-engine 2.16.2 → 2.18.0

package/dist/index.d.mts

@@ -402,6 +402,15 @@ interface ShellCommandAnalysis {
  */
 declare function analyzeShellCommand(command: string): ShellCommandAnalysis;
 
+/**
+ * A destination a tool call will reach, whichever carrier declared it: a
+ * shell command (extractShellDestinations) or a tool argument
+ * (extractToolDestinations). The interface is still spelled ShellDestination
+ * where it lives (shell/index.ts, which is hashed by the extractor-version
+ * gate, so a rename there is not free); this is the name that says what the
+ * shape is for.
+ */
+type Destination = ShellDestination;
 interface EgressPolicy {
     /** Master switch. Default false — opt-in, like dlp.pii. */
     enabled: boolean;
@@ -459,7 +468,7 @@ declare function isPrivateHost(host: string): boolean;
  * first review; null if everything is allowed (or policy disabled / mode off).
  * Pure.
  */
-declare function evaluateEgress(dests: readonly ShellDestination[], policy: EgressPolicy): EgressVerdict | null;
+declare function evaluateEgress(dests: readonly Destination[], policy: EgressPolicy): EgressVerdict | null;
 
 interface PipeChainAnalysis {
     isPipeline: boolean;
@@ -628,16 +637,6 @@ declare function resolvePinned(matches: SmartRule[]): SmartRule | undefined;
  * Returns a reason string if dangerous, null if safe.
  */
 declare function checkDangerousSql(sql: string): string | null;
-/**
- * Stateless policy evaluation. Same waterfall as the original
- * proxy/src/policy/index.ts:evaluatePolicy, but config + context + I/O
- * hooks come in as parameters so this function works in any host.
- *
- * Returns 'allow' for ignored tools, the matched smart-rule verdict,
- * inline-execution review, eval-detection verdict, pipe-chain verdict,
- * provenance verdict, sandbox allow, dangerous-word review, or strict-mode
- * fallback. See the design doc for the full tier table.
- */
 declare function evaluatePolicy(config: PolicyConfig, toolName: string, args?: unknown, context?: PolicyContext, hooks?: PolicyHostHooks): Promise<PolicyVerdict>;
 /** Returns true when toolName matches the config's ignoredTools list. */
 declare function isIgnoredTool(toolName: string, config: PolicyConfig): boolean;
@@ -1439,6 +1438,33 @@ interface SsrfFloorOptions {
      *  those constantly (72 of 308 destinations on measured real history). */
     ssrfStrict?: boolean;
 }
+/**
+ * Does this exemption list release this address?
+ *
+ * ONE function, because the shell floor and the declared-URL floor must answer
+ * identically. They had two spellings of it — `normalizeIpLiteral(e) ?? e.trim()
+ * .toLowerCase()` here and `classifySsrf(a)?.normalized ?? a` in
+ * destinations.ts — and for an entry classifySsrf does not match they already
+ * disagreed. Nothing depended on the difference, which is exactly when it is
+ * cheap to remove.
+ *
+ * An entry is an exact address or a CIDR range. The range form exists so an
+ * operator can exempt the mesh-VPN range they actually use (100.64.0.0/10)
+ * instead of listing peers one at a time, which is what the settings panel's
+ * "remove this default" control needs.
+ *
+ * ⚠ This answers "is it in the list", NOT "may it be released". The caller
+ * keeps its `m.overridable` guard, and that guard is per ADDRESS, decided by
+ * classifySsrf before this is consulted. So a range can never release a
+ * protected address inside it: 100.100.100.200 (Alibaba IMDS) sits inside
+ * 100.64.0.0/10 and is named in METADATA_ADDRESSES above the range check, so
+ * it classifies as metadata / overridable:false and stays blocked with the
+ * whole range exempted. Pinned by E2 in exempt-range.spec.ts.
+ *
+ * Never throws: this runs on the hook path for every tool call, and a bad
+ * entry in a hand-edited config must not break every command on the machine.
+ */
+declare function ssrfExemptMatches(entries: readonly string[] | undefined, normalized: string | undefined): boolean;
 /**
  * The floor. Returns the first protected destination, or null.
  *
@@ -1464,6 +1490,25 @@ declare function ssrfFloor(tokens: ReadonlyArray<{
  * `[]` in a path means "every element of this array".
  */
 declare const DESTINATION_ARGS: ReadonlyMap<string, readonly string[]>;
+/**
+ * The hosts a non-shell tool call will reach, in the SAME shape the shell
+ * extractor produces, so both feed one evaluateEgress (G10).
+ *
+ * Measured 2026-09-20 on dev e748b4a, egress { mode: 'block', allow: [] }:
+ * `curl https://evil.example.com/` denied, the same URL through WebFetch, MCP
+ * fetch and browser navigate allowed. The allowlist was shell-only, and an
+ * agent that wants to exfiltrate does not need curl. The extraction below is
+ * what the floor above already does; the policy was never applied to it.
+ *
+ * Same closed table, same helpers, for the same reason: a tool is covered
+ * because it is LISTED, never because an argument looked like a URL. A tool
+ * not in DESTINATION_ARGS yields [] and is invisible to the egress policy,
+ * exactly as it is invisible to the floor. `binary` carries the tool name so
+ * the reason string and the audit row say which carrier it was.
+ *
+ * Never throws: this runs on the hook path for every tool call.
+ */
+declare function extractToolDestinations(toolName: string, args: unknown): Destination[];
 interface DestinationHit extends SsrfMatch {
     /** The path that carried it, for the message and the audit row. */
     argPath: string;
@@ -1483,4 +1528,4 @@ declare function ssrfDestinationFloor(toolName: string, args: unknown, opts?: {
 /** 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, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COMMAND_WRAPPERS, COPY_VERBS, COST_PER_LOOP_ITER_USD, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, 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, MAX_BLAST_PATH, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type PositionedArg, 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, fileOperandFlagsOf, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeIpLiteral, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolvePinned, safeMessage, sampleCopyCommand, scanArgs, scanInjection, scanText, sensitivePathMatch, ssrfDestinationFloor, ssrfFloor, ssrfReason, stripControlChars, stripTerminalEscapes, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, unwrapCommandHead, 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, COMMAND_WRAPPERS, COPY_VERBS, COST_PER_LOOP_ITER_USD, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type Destination, 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, MAX_BLAST_PATH, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type PositionedArg, 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, extractToolDestinations, fileOperandFlagsOf, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeIpLiteral, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolvePinned, safeMessage, sampleCopyCommand, scanArgs, scanInjection, scanText, sensitivePathMatch, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripTerminalEscapes, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };

package/dist/index.d.ts

@@ -402,6 +402,15 @@ interface ShellCommandAnalysis {
  */
 declare function analyzeShellCommand(command: string): ShellCommandAnalysis;
 
+/**
+ * A destination a tool call will reach, whichever carrier declared it: a
+ * shell command (extractShellDestinations) or a tool argument
+ * (extractToolDestinations). The interface is still spelled ShellDestination
+ * where it lives (shell/index.ts, which is hashed by the extractor-version
+ * gate, so a rename there is not free); this is the name that says what the
+ * shape is for.
+ */
+type Destination = ShellDestination;
 interface EgressPolicy {
     /** Master switch. Default false — opt-in, like dlp.pii. */
     enabled: boolean;
@@ -459,7 +468,7 @@ declare function isPrivateHost(host: string): boolean;
  * first review; null if everything is allowed (or policy disabled / mode off).
  * Pure.
  */
-declare function evaluateEgress(dests: readonly ShellDestination[], policy: EgressPolicy): EgressVerdict | null;
+declare function evaluateEgress(dests: readonly Destination[], policy: EgressPolicy): EgressVerdict | null;
 
 interface PipeChainAnalysis {
     isPipeline: boolean;
@@ -628,16 +637,6 @@ declare function resolvePinned(matches: SmartRule[]): SmartRule | undefined;
  * Returns a reason string if dangerous, null if safe.
  */
 declare function checkDangerousSql(sql: string): string | null;
-/**
- * Stateless policy evaluation. Same waterfall as the original
- * proxy/src/policy/index.ts:evaluatePolicy, but config + context + I/O
- * hooks come in as parameters so this function works in any host.
- *
- * Returns 'allow' for ignored tools, the matched smart-rule verdict,
- * inline-execution review, eval-detection verdict, pipe-chain verdict,
- * provenance verdict, sandbox allow, dangerous-word review, or strict-mode
- * fallback. See the design doc for the full tier table.
- */
 declare function evaluatePolicy(config: PolicyConfig, toolName: string, args?: unknown, context?: PolicyContext, hooks?: PolicyHostHooks): Promise<PolicyVerdict>;
 /** Returns true when toolName matches the config's ignoredTools list. */
 declare function isIgnoredTool(toolName: string, config: PolicyConfig): boolean;
@@ -1439,6 +1438,33 @@ interface SsrfFloorOptions {
      *  those constantly (72 of 308 destinations on measured real history). */
     ssrfStrict?: boolean;
 }
+/**
+ * Does this exemption list release this address?
+ *
+ * ONE function, because the shell floor and the declared-URL floor must answer
+ * identically. They had two spellings of it — `normalizeIpLiteral(e) ?? e.trim()
+ * .toLowerCase()` here and `classifySsrf(a)?.normalized ?? a` in
+ * destinations.ts — and for an entry classifySsrf does not match they already
+ * disagreed. Nothing depended on the difference, which is exactly when it is
+ * cheap to remove.
+ *
+ * An entry is an exact address or a CIDR range. The range form exists so an
+ * operator can exempt the mesh-VPN range they actually use (100.64.0.0/10)
+ * instead of listing peers one at a time, which is what the settings panel's
+ * "remove this default" control needs.
+ *
+ * ⚠ This answers "is it in the list", NOT "may it be released". The caller
+ * keeps its `m.overridable` guard, and that guard is per ADDRESS, decided by
+ * classifySsrf before this is consulted. So a range can never release a
+ * protected address inside it: 100.100.100.200 (Alibaba IMDS) sits inside
+ * 100.64.0.0/10 and is named in METADATA_ADDRESSES above the range check, so
+ * it classifies as metadata / overridable:false and stays blocked with the
+ * whole range exempted. Pinned by E2 in exempt-range.spec.ts.
+ *
+ * Never throws: this runs on the hook path for every tool call, and a bad
+ * entry in a hand-edited config must not break every command on the machine.
+ */
+declare function ssrfExemptMatches(entries: readonly string[] | undefined, normalized: string | undefined): boolean;
 /**
  * The floor. Returns the first protected destination, or null.
  *
@@ -1464,6 +1490,25 @@ declare function ssrfFloor(tokens: ReadonlyArray<{
  * `[]` in a path means "every element of this array".
  */
 declare const DESTINATION_ARGS: ReadonlyMap<string, readonly string[]>;
+/**
+ * The hosts a non-shell tool call will reach, in the SAME shape the shell
+ * extractor produces, so both feed one evaluateEgress (G10).
+ *
+ * Measured 2026-09-20 on dev e748b4a, egress { mode: 'block', allow: [] }:
+ * `curl https://evil.example.com/` denied, the same URL through WebFetch, MCP
+ * fetch and browser navigate allowed. The allowlist was shell-only, and an
+ * agent that wants to exfiltrate does not need curl. The extraction below is
+ * what the floor above already does; the policy was never applied to it.
+ *
+ * Same closed table, same helpers, for the same reason: a tool is covered
+ * because it is LISTED, never because an argument looked like a URL. A tool
+ * not in DESTINATION_ARGS yields [] and is invisible to the egress policy,
+ * exactly as it is invisible to the floor. `binary` carries the tool name so
+ * the reason string and the audit row say which carrier it was.
+ *
+ * Never throws: this runs on the hook path for every tool call.
+ */
+declare function extractToolDestinations(toolName: string, args: unknown): Destination[];
 interface DestinationHit extends SsrfMatch {
     /** The path that carried it, for the message and the audit row. */
     argPath: string;
@@ -1483,4 +1528,4 @@ declare function ssrfDestinationFloor(toolName: string, args: unknown, opts?: {
 /** 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, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COMMAND_WRAPPERS, COPY_VERBS, COST_PER_LOOP_ITER_USD, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, 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, MAX_BLAST_PATH, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type PositionedArg, 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, fileOperandFlagsOf, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeIpLiteral, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolvePinned, safeMessage, sampleCopyCommand, scanArgs, scanInjection, scanText, sensitivePathMatch, ssrfDestinationFloor, ssrfFloor, ssrfReason, stripControlChars, stripTerminalEscapes, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, unwrapCommandHead, 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, COMMAND_WRAPPERS, COPY_VERBS, COST_PER_LOOP_ITER_USD, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type Destination, 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, MAX_BLAST_PATH, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type PositionedArg, 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, extractToolDestinations, fileOperandFlagsOf, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeIpLiteral, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolvePinned, safeMessage, sampleCopyCommand, scanArgs, scanInjection, scanText, sensitivePathMatch, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripTerminalEscapes, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };

package/dist/index.js

@@ -90,6 +90,7 @@ __export(src_exports, {
   extractSessionLevelFindings: () => extractSessionLevelFindings,
   extractShellDestTokens: () => extractShellDestTokens,
   extractShellDestinations: () => extractShellDestinations,
+  extractToolDestinations: () => extractToolDestinations,
   fileOperandFlagsOf: () => fileOperandFlagsOf,
   getCompiledRegex: () => getCompiledRegex,
   getNestedValue: () => getNestedValue,
@@ -122,6 +123,7 @@ __export(src_exports, {
   scanText: () => scanText,
   sensitivePathMatch: () => sensitivePathMatch,
   ssrfDestinationFloor: () => ssrfDestinationFloor,
+  ssrfExemptMatches: () => ssrfExemptMatches,
   ssrfFloor: () => ssrfFloor,
   ssrfReason: () => ssrfReason,
   stripControlChars: () => stripControlChars,
@@ -3398,6 +3400,38 @@ function classifySsrf(host) {
     return null;
   }
 }
+function ssrfExemptMatches(entries, normalized) {
+  if (!entries?.length || !normalized) return false;
+  const target = bitsOf(normalized);
+  for (const raw of entries) {
+    const entry = raw.trim().toLowerCase();
+    if (!entry) continue;
+    const slash = entry.indexOf("/");
+    if (slash === -1) {
+      if ((normalizeIpLiteral(entry) ?? entry) === normalized) return true;
+      continue;
+    }
+    if (!target) continue;
+    const base = bitsOf(normalizeIpLiteral(entry.slice(0, slash)) ?? "");
+    const prefixText = entry.slice(slash + 1);
+    const prefix = /^\d+$/.test(prefixText) ? Number(prefixText) : NaN;
+    if (!base || !Number.isInteger(prefix) || prefix < 0 || // A v4 range never matches a v6 address, and the reverse: the widths
+    // differ, so `0.0.0.0/0` does not release `::1`.
+    base.length !== target.length || prefix > base.length) {
+      continue;
+    }
+    if (base.slice(0, prefix) === target.slice(0, prefix)) return true;
+  }
+  return false;
+}
+function bitsOf(normalized) {
+  const o = v4Octets(normalized);
+  if (o) {
+    return o.every((n) => Number.isInteger(n) && n >= 0 && n <= 255) ? o.map((n) => n.toString(2).padStart(8, "0")).join("") : null;
+  }
+  const g = expandIpv6(normalized);
+  return g ? g.map((n) => n.toString(2).padStart(16, "0")).join("") : null;
+}
 var TIER_REASON = {
   metadata: "a cloud instance-metadata endpoint, the classic credential-theft target",
   "link-local": "a link-local address",
@@ -3407,14 +3441,11 @@ var TIER_REASON = {
   private: "a loopback or private address"
 };
 function ssrfFloor(tokens, opts = {}) {
-  const exempt = new Set(
-    (opts.ssrfAllow ?? []).map((e) => normalizeIpLiteral(e) ?? e.trim().toLowerCase())
-  );
   for (const { token, binary } of tokens) {
     const m = classifySsrf(token);
     if (!m) continue;
     if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-    if (m.overridable && m.normalized && exempt.has(m.normalized)) continue;
+    if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
     return { ...m, host: token, binary, reason: ssrfReason(m, token) };
   }
   return null;
@@ -3445,18 +3476,18 @@ var DEFAULT_EGRESS_ALLOWLIST = [
   "*.ubuntu.com"
 ];
 function hostMatches(host, pattern) {
-  const h = host.toLowerCase();
-  const p = pattern.toLowerCase().trim();
+  const p = pattern.trim().toLowerCase();
   if (!p) return false;
   if (p === "*") return true;
+  const h = canonicalHost(host);
   if (p.startsWith("*.")) {
-    const suffix = p.slice(2);
+    const suffix = canonicalHost(p.slice(2));
     return h === suffix || h.endsWith("." + suffix);
   }
-  return h === p;
+  return h === canonicalHost(p);
 }
 function matchesAny(host, patterns) {
-  for (const p of patterns) if (hostMatches(host, p)) return true;
+  for (const p of patterns ?? []) if (hostMatches(host, p)) return true;
   return false;
 }
 var PRIVATE_HOST_SUFFIXES = [".local", ".internal", ".localhost"];
@@ -3467,13 +3498,17 @@ function isUniqueLocalV6(host) {
   return g !== null && (g[0] & 65024) === 64512;
 }
 function isPrivateHost(host) {
-  const h = host.trim().toLowerCase();
+  const h = host.trim().toLowerCase().replace(/\.$/, "");
   const m = classifySsrf(h);
   if (m) return m.kind === "address" && (m.tier === "private" || m.tier === "unspecified");
   if (h === "localhost") return true;
   if (PRIVATE_HOST_SUFFIXES.some((s) => h.endsWith(s))) return true;
   return isUniqueLocalV6(h);
 }
+function canonicalHost(host) {
+  const ip = normalizeIpLiteral(host);
+  return ip ?? host.trim().toLowerCase().replace(/\.$/, "");
+}
 function evaluateEgress(dests, policy) {
   if (!policy.enabled) return null;
   let review = null;
@@ -3867,11 +3902,26 @@ function hostOf(value) {
     return null;
   }
 }
+function extractToolDestinations(toolName, args) {
+  try {
+    const paths = DESTINATION_ARGS.get(bareToolName(toolName));
+    if (!paths) return [];
+    const out = [];
+    for (const path of paths) {
+      for (const value of valuesAt(args, path)) {
+        const host = hostOf(value);
+        if (host) out.push({ host, binary: toolName, raw: value });
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
 function ssrfDestinationFloor(toolName, args, opts = {}) {
   try {
     const paths = DESTINATION_ARGS.get(bareToolName(toolName));
     if (!paths) return null;
-    const exempt = new Set((opts.ssrfAllow ?? []).map((a) => classifySsrf(a)?.normalized ?? a));
     for (const path of paths) {
       for (const value of valuesAt(args, path)) {
         const host = hostOf(value);
@@ -3879,7 +3929,7 @@ function ssrfDestinationFloor(toolName, args, opts = {}) {
         const m = classifySsrf(host);
         if (!m) continue;
         if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-        if (m.overridable && m.normalized && exempt.has(m.normalized)) continue;
+        if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
         return { ...m, argPath: path, host, reason: ssrfReason(m, host) };
       }
     }
@@ -3985,6 +4035,16 @@ function pipeChainVerdict(command, isTrustedHost, highAction = "review") {
     tier: 3
   };
 }
+function egressPolicyVerdict(eg) {
+  return {
+    decision: eg.verdict,
+    blockedByLabel: eg.verdict === "block" ? "\u{1F310} Node9 Egress (Blocked)" : "\u{1F310} Node9 Egress (Review)",
+    reason: eg.reason,
+    ruleName: `egress:${eg.binary}:${eg.host}`,
+    ruleDescription: eg.reason,
+    tier: eg.verdict === "block" ? 3 : 4
+  };
+}
 async function evaluatePolicy(config, toolName, args, context = {}, hooks = {}) {
   const { agent, cwd, activeEnvironment } = context;
   const { checkProvenance, isTrustedHost } = hooks;
@@ -4019,7 +4079,14 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
       };
     }
   }
-  if (wouldBeIgnored && !context.skipIgnoredFastPath) return { decision: "allow" };
+  const pendingToolEgress = config.policy.egress?.enabled ? (() => {
+    const dests = extractToolDestinations(toolName, args);
+    const eg = dests.length > 0 ? evaluateEgress(dests, config.policy.egress) : null;
+    return eg ? egressPolicyVerdict(eg) : void 0;
+  })() : void 0;
+  if (wouldBeIgnored && !context.skipIgnoredFastPath) {
+    return pendingToolEgress ?? { decision: "allow" };
+  }
   const shellShaped = isBashTool(toolName) || inspectsShellCommand(toolName, config.policy.toolInspection);
   const shellShapedCommand = shellShaped ? isBashTool(toolName) && args && typeof args === "object" ? typeof args.command === "string" ? args.command : null : extractShellCommand(toolName, args, config.policy.toolInspection) : null;
   const bashCommand = agent !== "Terminal" ? shellShapedCommand : null;
@@ -4108,6 +4175,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
   }
   let allTokens = [];
   let pathTokens = [];
+  if (pendingToolEgress) return pendingToolEgress;
   const shellCommand = extractShellCommand(toolName, args, config.policy.toolInspection);
   if (shellCommand) {
     const analyzed = analyzeShellCommand(shellCommand);
@@ -4173,16 +4241,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
       const dests = extractShellDestinations(shellCommand);
       if (dests.length > 0) {
         const eg = evaluateEgress(dests, config.policy.egress);
-        if (eg) {
-          return {
-            decision: eg.verdict,
-            blockedByLabel: eg.verdict === "block" ? "\u{1F310} Node9 Egress (Blocked)" : "\u{1F310} Node9 Egress (Review)",
-            reason: eg.reason,
-            ruleName: `egress:${eg.binary}:${eg.host}`,
-            ruleDescription: eg.reason,
-            tier: eg.verdict === "block" ? 3 : 4
-          };
-        }
+        if (eg) return egressPolicyVerdict(eg);
       }
     }
     const firstToken = analyzed.actions[0] ?? "";
@@ -6106,6 +6165,7 @@ var ENGINE_VERSION = "1.4.0";
   extractSessionLevelFindings,
   extractShellDestTokens,
   extractShellDestinations,
+  extractToolDestinations,
   fileOperandFlagsOf,
   getCompiledRegex,
   getNestedValue,
@@ -6138,6 +6198,7 @@ var ENGINE_VERSION = "1.4.0";
   scanText,
   sensitivePathMatch,
   ssrfDestinationFloor,
+  ssrfExemptMatches,
   ssrfFloor,
   ssrfReason,
   stripControlChars,

package/dist/index.mjs

@@ -3258,6 +3258,38 @@ function classifySsrf(host) {
     return null;
   }
 }
+function ssrfExemptMatches(entries, normalized) {
+  if (!entries?.length || !normalized) return false;
+  const target = bitsOf(normalized);
+  for (const raw of entries) {
+    const entry = raw.trim().toLowerCase();
+    if (!entry) continue;
+    const slash = entry.indexOf("/");
+    if (slash === -1) {
+      if ((normalizeIpLiteral(entry) ?? entry) === normalized) return true;
+      continue;
+    }
+    if (!target) continue;
+    const base = bitsOf(normalizeIpLiteral(entry.slice(0, slash)) ?? "");
+    const prefixText = entry.slice(slash + 1);
+    const prefix = /^\d+$/.test(prefixText) ? Number(prefixText) : NaN;
+    if (!base || !Number.isInteger(prefix) || prefix < 0 || // A v4 range never matches a v6 address, and the reverse: the widths
+    // differ, so `0.0.0.0/0` does not release `::1`.
+    base.length !== target.length || prefix > base.length) {
+      continue;
+    }
+    if (base.slice(0, prefix) === target.slice(0, prefix)) return true;
+  }
+  return false;
+}
+function bitsOf(normalized) {
+  const o = v4Octets(normalized);
+  if (o) {
+    return o.every((n) => Number.isInteger(n) && n >= 0 && n <= 255) ? o.map((n) => n.toString(2).padStart(8, "0")).join("") : null;
+  }
+  const g = expandIpv6(normalized);
+  return g ? g.map((n) => n.toString(2).padStart(16, "0")).join("") : null;
+}
 var TIER_REASON = {
   metadata: "a cloud instance-metadata endpoint, the classic credential-theft target",
   "link-local": "a link-local address",
@@ -3267,14 +3299,11 @@ var TIER_REASON = {
   private: "a loopback or private address"
 };
 function ssrfFloor(tokens, opts = {}) {
-  const exempt = new Set(
-    (opts.ssrfAllow ?? []).map((e) => normalizeIpLiteral(e) ?? e.trim().toLowerCase())
-  );
   for (const { token, binary } of tokens) {
     const m = classifySsrf(token);
     if (!m) continue;
     if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-    if (m.overridable && m.normalized && exempt.has(m.normalized)) continue;
+    if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
     return { ...m, host: token, binary, reason: ssrfReason(m, token) };
   }
   return null;
@@ -3305,18 +3334,18 @@ var DEFAULT_EGRESS_ALLOWLIST = [
   "*.ubuntu.com"
 ];
 function hostMatches(host, pattern) {
-  const h = host.toLowerCase();
-  const p = pattern.toLowerCase().trim();
+  const p = pattern.trim().toLowerCase();
   if (!p) return false;
   if (p === "*") return true;
+  const h = canonicalHost(host);
   if (p.startsWith("*.")) {
-    const suffix = p.slice(2);
+    const suffix = canonicalHost(p.slice(2));
     return h === suffix || h.endsWith("." + suffix);
   }
-  return h === p;
+  return h === canonicalHost(p);
 }
 function matchesAny(host, patterns) {
-  for (const p of patterns) if (hostMatches(host, p)) return true;
+  for (const p of patterns ?? []) if (hostMatches(host, p)) return true;
   return false;
 }
 var PRIVATE_HOST_SUFFIXES = [".local", ".internal", ".localhost"];
@@ -3327,13 +3356,17 @@ function isUniqueLocalV6(host) {
   return g !== null && (g[0] & 65024) === 64512;
 }
 function isPrivateHost(host) {
-  const h = host.trim().toLowerCase();
+  const h = host.trim().toLowerCase().replace(/\.$/, "");
   const m = classifySsrf(h);
   if (m) return m.kind === "address" && (m.tier === "private" || m.tier === "unspecified");
   if (h === "localhost") return true;
   if (PRIVATE_HOST_SUFFIXES.some((s) => h.endsWith(s))) return true;
   return isUniqueLocalV6(h);
 }
+function canonicalHost(host) {
+  const ip = normalizeIpLiteral(host);
+  return ip ?? host.trim().toLowerCase().replace(/\.$/, "");
+}
 function evaluateEgress(dests, policy) {
   if (!policy.enabled) return null;
   let review = null;
@@ -3727,11 +3760,26 @@ function hostOf(value) {
     return null;
   }
 }
+function extractToolDestinations(toolName, args) {
+  try {
+    const paths = DESTINATION_ARGS.get(bareToolName(toolName));
+    if (!paths) return [];
+    const out = [];
+    for (const path of paths) {
+      for (const value of valuesAt(args, path)) {
+        const host = hostOf(value);
+        if (host) out.push({ host, binary: toolName, raw: value });
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
 function ssrfDestinationFloor(toolName, args, opts = {}) {
   try {
     const paths = DESTINATION_ARGS.get(bareToolName(toolName));
     if (!paths) return null;
-    const exempt = new Set((opts.ssrfAllow ?? []).map((a) => classifySsrf(a)?.normalized ?? a));
     for (const path of paths) {
       for (const value of valuesAt(args, path)) {
         const host = hostOf(value);
@@ -3739,7 +3787,7 @@ function ssrfDestinationFloor(toolName, args, opts = {}) {
         const m = classifySsrf(host);
         if (!m) continue;
         if (isStrictGatedTier(m.tier) && !opts.ssrfStrict) continue;
-        if (m.overridable && m.normalized && exempt.has(m.normalized)) continue;
+        if (m.overridable && ssrfExemptMatches(opts.ssrfAllow, m.normalized)) continue;
         return { ...m, argPath: path, host, reason: ssrfReason(m, host) };
       }
     }
@@ -3845,6 +3893,16 @@ function pipeChainVerdict(command, isTrustedHost, highAction = "review") {
     tier: 3
   };
 }
+function egressPolicyVerdict(eg) {
+  return {
+    decision: eg.verdict,
+    blockedByLabel: eg.verdict === "block" ? "\u{1F310} Node9 Egress (Blocked)" : "\u{1F310} Node9 Egress (Review)",
+    reason: eg.reason,
+    ruleName: `egress:${eg.binary}:${eg.host}`,
+    ruleDescription: eg.reason,
+    tier: eg.verdict === "block" ? 3 : 4
+  };
+}
 async function evaluatePolicy(config, toolName, args, context = {}, hooks = {}) {
   const { agent, cwd, activeEnvironment } = context;
   const { checkProvenance, isTrustedHost } = hooks;
@@ -3879,7 +3937,14 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
       };
     }
   }
-  if (wouldBeIgnored && !context.skipIgnoredFastPath) return { decision: "allow" };
+  const pendingToolEgress = config.policy.egress?.enabled ? (() => {
+    const dests = extractToolDestinations(toolName, args);
+    const eg = dests.length > 0 ? evaluateEgress(dests, config.policy.egress) : null;
+    return eg ? egressPolicyVerdict(eg) : void 0;
+  })() : void 0;
+  if (wouldBeIgnored && !context.skipIgnoredFastPath) {
+    return pendingToolEgress ?? { decision: "allow" };
+  }
   const shellShaped = isBashTool(toolName) || inspectsShellCommand(toolName, config.policy.toolInspection);
   const shellShapedCommand = shellShaped ? isBashTool(toolName) && args && typeof args === "object" ? typeof args.command === "string" ? args.command : null : extractShellCommand(toolName, args, config.policy.toolInspection) : null;
   const bashCommand = agent !== "Terminal" ? shellShapedCommand : null;
@@ -3968,6 +4033,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
   }
   let allTokens = [];
   let pathTokens = [];
+  if (pendingToolEgress) return pendingToolEgress;
   const shellCommand = extractShellCommand(toolName, args, config.policy.toolInspection);
   if (shellCommand) {
     const analyzed = analyzeShellCommand(shellCommand);
@@ -4033,16 +4099,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
       const dests = extractShellDestinations(shellCommand);
       if (dests.length > 0) {
         const eg = evaluateEgress(dests, config.policy.egress);
-        if (eg) {
-          return {
-            decision: eg.verdict,
-            blockedByLabel: eg.verdict === "block" ? "\u{1F310} Node9 Egress (Blocked)" : "\u{1F310} Node9 Egress (Review)",
-            reason: eg.reason,
-            ruleName: `egress:${eg.binary}:${eg.host}`,
-            ruleDescription: eg.reason,
-            tier: eg.verdict === "block" ? 3 : 4
-          };
-        }
+        if (eg) return egressPolicyVerdict(eg);
       }
     }
     const firstToken = analyzed.actions[0] ?? "";
@@ -5965,6 +6022,7 @@ export {
   extractSessionLevelFindings,
   extractShellDestTokens,
   extractShellDestinations,
+  extractToolDestinations,
   fileOperandFlagsOf,
   getCompiledRegex,
   getNestedValue,
@@ -5997,6 +6055,7 @@ export {
   scanText,
   sensitivePathMatch,
   ssrfDestinationFloor,
+  ssrfExemptMatches,
   ssrfFloor,
   ssrfReason,
   stripControlChars,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@node9/policy-engine",
-  "version": "2.16.2",
+  "version": "2.18.0",
   "description": "Shared policy evaluation engine for node9 — DLP, smart rules, AST shell parsing, shields, loop detection. Pure functions, no I/O. Used by both node9-proxy and the node9 SaaS firewall.",
   "license": "Apache-2.0",
   "homepage": "https://node9.ai",