@node9/policy-engine 2.32.0 → 2.33.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
@@ -113,6 +113,19 @@ type ToolInspectionEntry = string | {
113
113
  field: string;
114
114
  };
115
115
  type ToolInspection = Record<string, ToolInspectionEntry>;
116
+ /**
117
+ * Inspection mappings by provenance. `trusted` is the shipped defaults plus the
118
+ * user's own and the workspace's entries, with full authority. `project` is a
119
+ * repository-carried config file, which an agent can write in-session: it may
120
+ * add a shell tool or a shell field, never turn a recognized executor into a
121
+ * non-shell tool or point its inspection at a decoy field (fw#338, review 3).
122
+ */
123
+ interface InspectionLayers {
124
+ trusted: ToolInspection;
125
+ project?: ToolInspection;
126
+ }
127
+ /** A plain map is read as trusted with no project layer. */
128
+ type InspectionInput = ToolInspection | InspectionLayers;
116
129
  type ShellInputResolution = {
117
130
  kind: 'not-shell';
118
131
  } | {
@@ -125,10 +138,17 @@ type ShellInputResolution = {
125
138
  };
126
139
  declare const BASH_TOOL_NAMES: Set<string>;
127
140
  declare function isBashTool(tool: string): boolean;
128
- declare function isShellShapedTool(tool: string, inspection?: ToolInspection): boolean;
129
- declare function resolveShellInput(tool: string, args: unknown, inspection?: ToolInspection): ShellInputResolution;
141
+ /** The merged policy's maps as layers; the host keeps the project layer apart. */
142
+ declare function inspectionLayers(policy: {
143
+ toolInspection: ToolInspection;
144
+ projectToolInspection?: ToolInspection;
145
+ }): InspectionLayers;
146
+ /** The first matching entry, trusted layer first. For legacy (SQL, explain) lookups. */
147
+ declare function inspectionEntry(tool: string, inspection?: InspectionInput): ToolInspectionEntry | undefined;
148
+ declare function isShellShapedTool(tool: string, inspection?: InspectionInput): boolean;
149
+ declare function resolveShellInput(tool: string, args: unknown, inspection?: InspectionInput): ShellInputResolution;
130
150
  /** Only Bash-scoped rules receive the canonical projection. Caller data is never mutated. */
131
- declare function shellRuleArgs(tool: string, args: unknown, ruleTool: string | string[] | undefined, inspection?: ToolInspection): unknown;
151
+ declare function shellRuleArgs(tool: string, args: unknown, ruleTool: string | string[] | undefined, inspection?: InspectionInput): unknown;
132
152
 
133
153
  type SsrfTier = 'metadata' | 'link-local' | 'multicast' | 'unspecified' | 'cgnat' | 'private';
134
154
  interface SsrfMatch {
@@ -511,7 +531,7 @@ declare const COMMAND_WRAPPERS: Set<string>;
511
531
  * `run_shell_command`, `execute_bash`, `terminal.execute`) must not silently
512
532
  * void them. An absent rule scope matches everything (callers' prior semantics).
513
533
  */
514
- declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?: ToolInspection): boolean;
534
+ declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?: InspectionInput): boolean;
515
535
  /** Strip leading wrappers/runners from a resolved arg list, returning the index
516
536
  * of the real command head. Handles `sudo -u www python3`, `env -u FOO python3`,
517
537
  * `timeout 5 python3`, `uv run python`, `conda run -n env python`,
@@ -689,6 +709,8 @@ interface PolicyConfig {
689
709
  dangerousWords: string[];
690
710
  ignoredTools: string[];
691
711
  toolInspection: ToolInspection;
712
+ /** Entries from a repository-carried config file; they may only add inspection. */
713
+ projectToolInspection?: ToolInspection;
692
714
  smartRules: SmartRule[];
693
715
  dlp: {
694
716
  enabled: boolean;
@@ -842,7 +864,7 @@ type ProtectedFileVerdict = PolicyVerdict & {
842
864
  declare function incompleteFileVerdict(operation?: FileAccess['operation']): ProtectedFileVerdict;
843
865
  /** Closed adapters: an arbitrary tool's path-shaped argument is not an operation. */
844
866
  declare function fileToolOperation(tool: string, args: unknown): FileAccess['operation'] | null;
845
- declare function collectFileAccesses(tool: string, args: unknown, context?: FileAccessContext, inspection?: ToolInspection): FileAccess[];
867
+ declare function collectFileAccesses(tool: string, args: unknown, context?: FileAccessContext, inspection?: InspectionInput): FileAccess[];
846
868
  declare function evaluateProtectedFileAccess(accesses: FileAccess[], context: FileAccessContext, settings: CatalogSettings): ProtectedFileVerdict | null;
847
869
 
848
870
  type InjectionConfidence = 'low' | 'medium' | 'high';
@@ -855,6 +877,10 @@ interface InjectionContext {
855
877
  /** Tool that produced the output. Untrusted origins (web/network) raise
856
878
  * confidence — a fetched page is attacker-influenceable; a local read isn't. */
857
879
  tool?: string;
880
+ /** The caller's own answer to "did this output come from outside?" (the
881
+ * #318 source roles: an unannotated MCP tool, a shell fetch). When set it
882
+ * decides the booster; when absent the tool-name regex below does. */
883
+ untrusted?: boolean;
858
884
  }
859
885
  /**
860
886
  * Scan tool output for indirect prompt injection. Returns the matched signals +
@@ -1866,7 +1892,7 @@ interface ExtractContext {
1866
1892
  }>;
1867
1893
  /** toolInspection map from PolicyConfig — drives shell-command extraction
1868
1894
  * for tools that aren't the standard 'bash' name. Defaults handled by caller. */
1869
- toolInspection: ToolInspection;
1895
+ toolInspection: InspectionInput;
1870
1896
  /** DLP enabled flag from PolicyConfig. */
1871
1897
  dlpEnabled: boolean;
1872
1898
  /** Decoy credentials registered on this machine (value plus kind and plant
@@ -1924,7 +1950,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
1924
1950
  * and fails CI when the hash drifts without a version bump — forgetting
1925
1951
  * is loud, not silent.
1926
1952
  */
1927
- declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v25";
1953
+ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v26";
1928
1954
  /**
1929
1955
  * SHA-256 prefix of the detector-source files
1930
1956
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -1935,7 +1961,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v25";
1935
1961
  * files changed, this hash must change too, and you must consciously
1936
1962
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
1937
1963
  */
1938
- declare const CANONICAL_EXTRACTOR_HASH = "48ef4af5dd89198d";
1964
+ declare const CANONICAL_EXTRACTOR_HASH = "dec8c65145686360";
1939
1965
  declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
1940
1966
  declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
1941
1967
  /**
@@ -2010,7 +2036,7 @@ declare function ssrfDestinationFloor(toolName: string, args: unknown, opts?: {
2010
2036
  declare const ARGUMENT_SCAN_LIMITS: {
2011
2037
  readonly maxDepth: 12;
2012
2038
  readonly maxNodes: 16384;
2013
- /** Raw text is matched in windows of this size; decoding views use the first window. */
2039
+ /** Text is matched and decoded in windows of this size. */
2014
2040
  readonly maxStringCharacters: 100000;
2015
2041
  /** Windows overlap by this much so a token on a window edge is still seen whole. */
2016
2042
  readonly windowOverlap: 4096;
@@ -2023,10 +2049,11 @@ declare const ARGUMENT_SCAN_LIMITS: {
2023
2049
  interface ArgumentInspectionResult {
2024
2050
  match: DlpMatch | null;
2025
2051
  /**
2026
- * `incomplete` when any part of the input was not fully inspected. Reasons
2027
- * starting with `argument-` mean raw text or structure was skipped; reasons
2028
- * starting with `decode-` mean every byte of raw text was matched but the
2029
- * derived decoding views were cut short.
2052
+ * `incomplete` when any part of the input was not fully inspected: raw text
2053
+ * or structure skipped (`argument-*`), a decoding layer past the nested
2054
+ * limits (`decode-nested`), a flood of joinable hostname labels
2055
+ * (`decode-labels`), or the recovery-phrase hash budget (`mnemonic-budget`).
2056
+ * Every reason requires review; none is a documented allow.
2030
2057
  */
2031
2058
  coverage: 'complete' | 'incomplete';
2032
2059
  reasons: string[];
@@ -2034,14 +2061,13 @@ interface ArgumentInspectionResult {
2034
2061
  /** Bounded input inspection. Output redaction deliberately retains its own API. */
2035
2062
  declare function inspectArgumentSecrets(args: unknown): ArgumentInspectionResult;
2036
2063
  /**
2037
- * Existing DLP approval routing. A finding wins. Otherwise raw text or
2038
- * structure that was skipped (`argument-*` reasons) requires review; a cut
2039
- * short decoding budget over fully matched raw text does not interrupt the
2040
- * call, because ordinary documents full of links or hashes exhaust it.
2064
+ * Existing DLP approval routing. A finding wins. Otherwise any part of the
2065
+ * input that was not fully inspected requires review: there is no limit an
2066
+ * attacker can reach that ends in a clean result.
2041
2067
  */
2042
2068
  declare function scanArgumentSecrets(args: unknown): DlpMatch | null;
2043
2069
 
2044
2070
  /** Engine version stamped on audit entries for future drift detection. */
2045
2071
  declare const ENGINE_VERSION = "1.4.0";
2046
2072
 
2047
- export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, type ArgumentInspectionResult, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, 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, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, type CatalogSettings, type CheckDef, type CheckGroup, type CheckSource, type CheckText, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type Destination, type DestinationKind, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, type FileAccess, type FileAccessContext, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LegacyPolicyKnobs, type LoopWindowEvaluation, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, type PackageEcosystem, type PackageInstallRequest, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type PositionedArg, type ProtectedFileVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type ResolvedCheck, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, type ScanFinding, type ScanSignals, type ScanSummary, type ScanView, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestToken, type ShellDestination, type ShellExposure, type ShellInputResolution, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type SsrfFloorOptions, type SsrfMatch, type SsrfTier, type SsrfVerdict, TUNING_FIELDS, type ToolCallEntry, type ToolCallRecord, type ToolInspection, type ToolInspectionEntry, type TuningField, VERDICTS, type Verdict, 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, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, isAgentInstructionPath, isBashTool, isDestructiveToolName, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, 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, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };
2073
+ export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, type ArgumentInspectionResult, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, 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, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, type CatalogSettings, type CheckDef, type CheckGroup, type CheckSource, type CheckText, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type Destination, type DestinationKind, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, type FileAccess, type FileAccessContext, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, type InspectionInput, type InspectionLayers, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LegacyPolicyKnobs, type LoopWindowEvaluation, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, type PackageEcosystem, type PackageInstallRequest, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type PositionedArg, type ProtectedFileVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type ResolvedCheck, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, type ScanFinding, type ScanSignals, type ScanSummary, type ScanView, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestToken, type ShellDestination, type ShellExposure, type ShellInputResolution, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type SsrfFloorOptions, type SsrfMatch, type SsrfTier, type SsrfVerdict, TUNING_FIELDS, type ToolCallEntry, type ToolCallRecord, type ToolInspection, type ToolInspectionEntry, type TuningField, VERDICTS, type Verdict, 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, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isDestructiveToolName, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, 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, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };
package/dist/index.d.ts CHANGED
@@ -113,6 +113,19 @@ type ToolInspectionEntry = string | {
113
113
  field: string;
114
114
  };
115
115
  type ToolInspection = Record<string, ToolInspectionEntry>;
116
+ /**
117
+ * Inspection mappings by provenance. `trusted` is the shipped defaults plus the
118
+ * user's own and the workspace's entries, with full authority. `project` is a
119
+ * repository-carried config file, which an agent can write in-session: it may
120
+ * add a shell tool or a shell field, never turn a recognized executor into a
121
+ * non-shell tool or point its inspection at a decoy field (fw#338, review 3).
122
+ */
123
+ interface InspectionLayers {
124
+ trusted: ToolInspection;
125
+ project?: ToolInspection;
126
+ }
127
+ /** A plain map is read as trusted with no project layer. */
128
+ type InspectionInput = ToolInspection | InspectionLayers;
116
129
  type ShellInputResolution = {
117
130
  kind: 'not-shell';
118
131
  } | {
@@ -125,10 +138,17 @@ type ShellInputResolution = {
125
138
  };
126
139
  declare const BASH_TOOL_NAMES: Set<string>;
127
140
  declare function isBashTool(tool: string): boolean;
128
- declare function isShellShapedTool(tool: string, inspection?: ToolInspection): boolean;
129
- declare function resolveShellInput(tool: string, args: unknown, inspection?: ToolInspection): ShellInputResolution;
141
+ /** The merged policy's maps as layers; the host keeps the project layer apart. */
142
+ declare function inspectionLayers(policy: {
143
+ toolInspection: ToolInspection;
144
+ projectToolInspection?: ToolInspection;
145
+ }): InspectionLayers;
146
+ /** The first matching entry, trusted layer first. For legacy (SQL, explain) lookups. */
147
+ declare function inspectionEntry(tool: string, inspection?: InspectionInput): ToolInspectionEntry | undefined;
148
+ declare function isShellShapedTool(tool: string, inspection?: InspectionInput): boolean;
149
+ declare function resolveShellInput(tool: string, args: unknown, inspection?: InspectionInput): ShellInputResolution;
130
150
  /** Only Bash-scoped rules receive the canonical projection. Caller data is never mutated. */
131
- declare function shellRuleArgs(tool: string, args: unknown, ruleTool: string | string[] | undefined, inspection?: ToolInspection): unknown;
151
+ declare function shellRuleArgs(tool: string, args: unknown, ruleTool: string | string[] | undefined, inspection?: InspectionInput): unknown;
132
152
 
133
153
  type SsrfTier = 'metadata' | 'link-local' | 'multicast' | 'unspecified' | 'cgnat' | 'private';
134
154
  interface SsrfMatch {
@@ -511,7 +531,7 @@ declare const COMMAND_WRAPPERS: Set<string>;
511
531
  * `run_shell_command`, `execute_bash`, `terminal.execute`) must not silently
512
532
  * void them. An absent rule scope matches everything (callers' prior semantics).
513
533
  */
514
- declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?: ToolInspection): boolean;
534
+ declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?: InspectionInput): boolean;
515
535
  /** Strip leading wrappers/runners from a resolved arg list, returning the index
516
536
  * of the real command head. Handles `sudo -u www python3`, `env -u FOO python3`,
517
537
  * `timeout 5 python3`, `uv run python`, `conda run -n env python`,
@@ -689,6 +709,8 @@ interface PolicyConfig {
689
709
  dangerousWords: string[];
690
710
  ignoredTools: string[];
691
711
  toolInspection: ToolInspection;
712
+ /** Entries from a repository-carried config file; they may only add inspection. */
713
+ projectToolInspection?: ToolInspection;
692
714
  smartRules: SmartRule[];
693
715
  dlp: {
694
716
  enabled: boolean;
@@ -842,7 +864,7 @@ type ProtectedFileVerdict = PolicyVerdict & {
842
864
  declare function incompleteFileVerdict(operation?: FileAccess['operation']): ProtectedFileVerdict;
843
865
  /** Closed adapters: an arbitrary tool's path-shaped argument is not an operation. */
844
866
  declare function fileToolOperation(tool: string, args: unknown): FileAccess['operation'] | null;
845
- declare function collectFileAccesses(tool: string, args: unknown, context?: FileAccessContext, inspection?: ToolInspection): FileAccess[];
867
+ declare function collectFileAccesses(tool: string, args: unknown, context?: FileAccessContext, inspection?: InspectionInput): FileAccess[];
846
868
  declare function evaluateProtectedFileAccess(accesses: FileAccess[], context: FileAccessContext, settings: CatalogSettings): ProtectedFileVerdict | null;
847
869
 
848
870
  type InjectionConfidence = 'low' | 'medium' | 'high';
@@ -855,6 +877,10 @@ interface InjectionContext {
855
877
  /** Tool that produced the output. Untrusted origins (web/network) raise
856
878
  * confidence — a fetched page is attacker-influenceable; a local read isn't. */
857
879
  tool?: string;
880
+ /** The caller's own answer to "did this output come from outside?" (the
881
+ * #318 source roles: an unannotated MCP tool, a shell fetch). When set it
882
+ * decides the booster; when absent the tool-name regex below does. */
883
+ untrusted?: boolean;
858
884
  }
859
885
  /**
860
886
  * Scan tool output for indirect prompt injection. Returns the matched signals +
@@ -1866,7 +1892,7 @@ interface ExtractContext {
1866
1892
  }>;
1867
1893
  /** toolInspection map from PolicyConfig — drives shell-command extraction
1868
1894
  * for tools that aren't the standard 'bash' name. Defaults handled by caller. */
1869
- toolInspection: ToolInspection;
1895
+ toolInspection: InspectionInput;
1870
1896
  /** DLP enabled flag from PolicyConfig. */
1871
1897
  dlpEnabled: boolean;
1872
1898
  /** Decoy credentials registered on this machine (value plus kind and plant
@@ -1924,7 +1950,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
1924
1950
  * and fails CI when the hash drifts without a version bump — forgetting
1925
1951
  * is loud, not silent.
1926
1952
  */
1927
- declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v25";
1953
+ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v26";
1928
1954
  /**
1929
1955
  * SHA-256 prefix of the detector-source files
1930
1956
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -1935,7 +1961,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v25";
1935
1961
  * files changed, this hash must change too, and you must consciously
1936
1962
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
1937
1963
  */
1938
- declare const CANONICAL_EXTRACTOR_HASH = "48ef4af5dd89198d";
1964
+ declare const CANONICAL_EXTRACTOR_HASH = "dec8c65145686360";
1939
1965
  declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
1940
1966
  declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
1941
1967
  /**
@@ -2010,7 +2036,7 @@ declare function ssrfDestinationFloor(toolName: string, args: unknown, opts?: {
2010
2036
  declare const ARGUMENT_SCAN_LIMITS: {
2011
2037
  readonly maxDepth: 12;
2012
2038
  readonly maxNodes: 16384;
2013
- /** Raw text is matched in windows of this size; decoding views use the first window. */
2039
+ /** Text is matched and decoded in windows of this size. */
2014
2040
  readonly maxStringCharacters: 100000;
2015
2041
  /** Windows overlap by this much so a token on a window edge is still seen whole. */
2016
2042
  readonly windowOverlap: 4096;
@@ -2023,10 +2049,11 @@ declare const ARGUMENT_SCAN_LIMITS: {
2023
2049
  interface ArgumentInspectionResult {
2024
2050
  match: DlpMatch | null;
2025
2051
  /**
2026
- * `incomplete` when any part of the input was not fully inspected. Reasons
2027
- * starting with `argument-` mean raw text or structure was skipped; reasons
2028
- * starting with `decode-` mean every byte of raw text was matched but the
2029
- * derived decoding views were cut short.
2052
+ * `incomplete` when any part of the input was not fully inspected: raw text
2053
+ * or structure skipped (`argument-*`), a decoding layer past the nested
2054
+ * limits (`decode-nested`), a flood of joinable hostname labels
2055
+ * (`decode-labels`), or the recovery-phrase hash budget (`mnemonic-budget`).
2056
+ * Every reason requires review; none is a documented allow.
2030
2057
  */
2031
2058
  coverage: 'complete' | 'incomplete';
2032
2059
  reasons: string[];
@@ -2034,14 +2061,13 @@ interface ArgumentInspectionResult {
2034
2061
  /** Bounded input inspection. Output redaction deliberately retains its own API. */
2035
2062
  declare function inspectArgumentSecrets(args: unknown): ArgumentInspectionResult;
2036
2063
  /**
2037
- * Existing DLP approval routing. A finding wins. Otherwise raw text or
2038
- * structure that was skipped (`argument-*` reasons) requires review; a cut
2039
- * short decoding budget over fully matched raw text does not interrupt the
2040
- * call, because ordinary documents full of links or hashes exhaust it.
2064
+ * Existing DLP approval routing. A finding wins. Otherwise any part of the
2065
+ * input that was not fully inspected requires review: there is no limit an
2066
+ * attacker can reach that ends in a clean result.
2041
2067
  */
2042
2068
  declare function scanArgumentSecrets(args: unknown): DlpMatch | null;
2043
2069
 
2044
2070
  /** Engine version stamped on audit entries for future drift detection. */
2045
2071
  declare const ENGINE_VERSION = "1.4.0";
2046
2072
 
2047
- export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, type ArgumentInspectionResult, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, 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, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, type CatalogSettings, type CheckDef, type CheckGroup, type CheckSource, type CheckText, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type Destination, type DestinationKind, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, type FileAccess, type FileAccessContext, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LegacyPolicyKnobs, type LoopWindowEvaluation, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, type PackageEcosystem, type PackageInstallRequest, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type PositionedArg, type ProtectedFileVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type ResolvedCheck, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, type ScanFinding, type ScanSignals, type ScanSummary, type ScanView, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestToken, type ShellDestination, type ShellExposure, type ShellInputResolution, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type SsrfFloorOptions, type SsrfMatch, type SsrfTier, type SsrfVerdict, TUNING_FIELDS, type ToolCallEntry, type ToolCallRecord, type ToolInspection, type ToolInspectionEntry, type TuningField, VERDICTS, type Verdict, 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, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, isAgentInstructionPath, isBashTool, isDestructiveToolName, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, 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, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };
2073
+ export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, type ArgumentInspectionResult, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, 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, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, type CatalogSettings, type CheckDef, type CheckGroup, type CheckSource, type CheckText, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type Destination, type DestinationKind, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, type FileAccess, type FileAccessContext, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, type InspectionInput, type InspectionLayers, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LegacyPolicyKnobs, type LoopWindowEvaluation, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, type PackageEcosystem, type PackageInstallRequest, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type PositionedArg, type ProtectedFileVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type ResolvedCheck, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, type ScanFinding, type ScanSignals, type ScanSummary, type ScanView, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestToken, type ShellDestination, type ShellExposure, type ShellInputResolution, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type SsrfFloorOptions, type SsrfMatch, type SsrfTier, type SsrfVerdict, TUNING_FIELDS, type ToolCallEntry, type ToolCallRecord, type ToolInspection, type ToolInspectionEntry, type TuningField, VERDICTS, type Verdict, 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, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isDestructiveToolName, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, 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, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };