@node9/policy-engine 2.41.3 → 2.42.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
@@ -444,6 +444,8 @@ interface FileAccess {
444
444
  dotGlob?: boolean;
445
445
  followFinal: boolean;
446
446
  recursive?: boolean;
447
+ /** A write that adds to the file (`>>`, `tee -a`): its content stays. */
448
+ append?: true;
447
449
  /** This basename-joined candidate applies only if this operand is a directory. */
448
450
  directoryTarget?: string;
449
451
  candidates?: string[];
@@ -888,6 +890,9 @@ interface PolicyHostHooks {
888
890
  checkProvenance?: (binary: string, cwd?: string) => ProvenanceLookup;
889
891
  /** Returns true if the host is on the user's trusted-hosts allowlist. */
890
892
  isTrustedHost?: (host: string) => boolean;
893
+ /** The agent settings file at `absPath` as it is on disk now (a regular
894
+ * file within the host's size cap), or null (node9Firewall#413 part 4). */
895
+ readAgentSettings?: (absPath: string) => string | null;
891
896
  }
892
897
  interface PolicyVerdict {
893
898
  decision: 'allow' | 'review' | 'block';
@@ -948,11 +953,12 @@ declare function resolvePinned(matches: SmartRule[]): SmartRule | undefined;
948
953
  * Returns a reason string if dangerous, null if safe.
949
954
  */
950
955
  declare function checkDangerousSql(sql: string): string | null;
951
- declare function evaluatePolicy(config: PolicyConfig, toolName: string, args?: unknown, context?: PolicyContext, hooks?: PolicyHostHooks): Promise<PolicyVerdict>;
956
+ declare function evaluatePolicy(config: PolicyConfig, toolName: string, args?: unknown, context?: PolicyContext, hostHooks?: PolicyHostHooks): Promise<PolicyVerdict>;
952
957
  /** Returns true when toolName matches the config's ignoredTools list. */
953
958
  declare function isIgnoredTool(toolName: string, config: PolicyConfig): boolean;
954
959
 
955
960
  type ProtectedFileVerdict = PolicyVerdict & {
961
+ ruleName: string;
956
962
  path: string;
957
963
  operation: FileAccess['operation'];
958
964
  };
@@ -1106,6 +1112,53 @@ declare function redactText(text: string): {
1106
1112
  found: string[];
1107
1113
  };
1108
1114
 
1115
+ type AgentFileKind = 'instructions' | 'memory' | 'agents' | 'commands' | 'skills' | 'settings';
1116
+ /** The kind of agent file a normalized path is, or null. */
1117
+ declare function agentFileKind(p: string): AgentFileKind | null;
1118
+
1119
+ /**
1120
+ * Scan text about to be written into an agent instruction or memory file.
1121
+ * The three signals above, plus the override, fake-role and destination
1122
+ * signals of scanInjection; any one is a finding. Read on every view
1123
+ * (normalised, base64 and hex decoded), as the output scanner does.
1124
+ */
1125
+ declare function scanInstructionWrite(text: string): InjectionMatch | null;
1126
+
1127
+ type GitCheckId = 'commands.git-destructive' | 'commands.git-hooks-bypass' | 'commands.git-stage-all';
1128
+ interface GitFinding {
1129
+ checkId: GitCheckId;
1130
+ /** The rule name the audit log and the catalog's legacy table know. */
1131
+ ruleName: 'review-force-push' | 'review-git-destructive' | 'review-git-hooks-bypass' | 'review-git-stage-all';
1132
+ reason: string;
1133
+ description: string;
1134
+ /** The invocation as resolved, for the reason and the explain trace. */
1135
+ shown: string;
1136
+ }
1137
+ interface GitAnalysis {
1138
+ /** False when mvdan-sh could not parse the command: nothing was judged. */
1139
+ parsed: boolean;
1140
+ findings: GitFinding[];
1141
+ }
1142
+ /** One git invocation after resolution. */
1143
+ interface GitInvocation {
1144
+ /** The subcommand, or null when it could not be read (a dynamic word). */
1145
+ sub: string | null;
1146
+ /** The words after the subcommand; null marks a dynamic word. */
1147
+ args: (string | null)[];
1148
+ /** `-c key=value` pairs given before the subcommand, lowercased keys. */
1149
+ config: Map<string, string>;
1150
+ /** Assignments applied to this call (`HUSKY=0 git …`, `env K=V git …`). */
1151
+ env: Map<string, string | null>;
1152
+ /** How the call was written, for the reason. */
1153
+ shown: string;
1154
+ }
1155
+ /**
1156
+ * Every git finding in a shell command. Cached by the raw text; pure.
1157
+ */
1158
+ declare function analyzeGit(command: string): GitAnalysis;
1159
+ /** The git invocations a command makes, resolved. Exposed for the explain trace and tests. */
1160
+ declare function gitInvocations(command: string): GitInvocation[];
1161
+
1109
1162
  /**
1110
1163
  * The OSV ecosystem name, verbatim: it is the index directory, the bucket path
1111
1164
  * of the OSV archive and the `ecosystem` of the online query at once. `VSCode`
@@ -2117,7 +2170,7 @@ declare function matchCanary(text: string, values: readonly CanaryValue[]): Cana
2117
2170
  * so escaped values are seen (B23), like scanArgs. */
2118
2171
  declare function matchCanaryArgs(args: unknown, values: readonly CanaryValue[]): CanaryHit | null;
2119
2172
 
2120
- 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';
2173
+ type CanonicalFindingType = 'smart-rule' | 'ast-fs-op' | 'file-access' | 'dlp' | 'pii' | 'canary' | 'sensitive-file-read' | 'privilege-escalation' | 'destructive-op' | 'pipe-to-shell' | 'eval-of-remote' | 'loop' | 'long-output-redacted';
2121
2174
  type CanonicalAgent = 'claude' | 'gemini' | 'codex' | 'shell';
2122
2175
  type CanonicalSourceType = 'default' | 'shield' | 'user' | 'engine';
2123
2176
  interface CanonicalFinding {
@@ -2150,6 +2203,9 @@ interface CanonicalFinding {
2150
2203
  sourceType: CanonicalSourceType;
2151
2204
  /** Optional shield/source label for UI. */
2152
2205
  shieldLabel?: string;
2206
+ /** The catalog check the gate names for the same call (`files.system-dirs`,
2207
+ * `commands.git-hooks-bypass`, ...). Set on 'file-access' findings. */
2208
+ checkId?: string;
2153
2209
  /** When this exact (post-dedupe) finding was first / last seen. */
2154
2210
  firstSeenAt: string;
2155
2211
  lastSeenAt: string;
@@ -2203,6 +2259,14 @@ interface ExtractContext {
2203
2259
  kind?: string;
2204
2260
  path?: string;
2205
2261
  }>;
2262
+ /** The session's working directory, absolute, when the transcript carries
2263
+ * one. A relative file_path resolves against it for the file checks. */
2264
+ cwd?: string;
2265
+ /** The user's home directory (first) as the gate's FileAccessContext has it. */
2266
+ homeDirs?: string[];
2267
+ /** Catalog settings for the file checks. Absent means the defaults (the
2268
+ * Standard level), which keeps extractor output machine-independent. */
2269
+ catalogSettings?: CatalogSettings;
2206
2270
  }
2207
2271
  interface SessionExtractContext {
2208
2272
  sessionId: string;
@@ -2251,7 +2315,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
2251
2315
  * and fails CI when the hash drifts without a version bump — forgetting
2252
2316
  * is loud, not silent.
2253
2317
  */
2254
- declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v31";
2318
+ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v32";
2255
2319
  /**
2256
2320
  * SHA-256 prefix of the detector-source files
2257
2321
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -2262,7 +2326,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v31";
2262
2326
  * files changed, this hash must change too, and you must consciously
2263
2327
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
2264
2328
  */
2265
- declare const CANONICAL_EXTRACTOR_HASH = "60048df5a64eb7c0";
2329
+ declare const CANONICAL_EXTRACTOR_HASH = "bf14326b92bf1718";
2266
2330
  declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
2267
2331
  declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
2268
2332
  /**
@@ -2374,5 +2438,5 @@ declare function scanArgumentSecrets(args: unknown): DlpMatch | null;
2374
2438
  /** Engine version stamped on audit entries for future drift detection. */
2375
2439
  declare const ENGINE_VERSION = "1.4.0";
2376
2440
 
2377
- export { ACTION_CHECKS, ACTION_TEMPLATES, AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, APP_SERVER_GLOB, APP_SHIELD_NAMES, APP_SHIELD_SPECS, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, CHECKS, CHECK_BY_ID, CHECK_GROUPS, CHECK_TEXT, CHECK_VERDICT_RANK, COMMAND_WRAPPERS, CONFIGURABLE_CHECK_IDS, COPY_VERBS, COST_PER_LOOP_ITER_USD, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, ENGINE_VERSION, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, GENERAL_ACTION_RULES, KNOB_GOVERNED, LEVELS, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, MODE_VALUES, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, REALTIME_PII_PATTERNS, REPLACED_SHIELDS, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, TUNING_FIELDS, VERDICTS, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, argumentLeavesText, catalogSettingsFromConfig, checkDangerousSql, checkIdForCheckedBy, checkIdForRule, checkToLegacyPolicy, checkValue, checksFromLegacyPolicy, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, entryDisplay, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileAccessView, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hashDestination, hostMatches, incompleteFileVerdict, inlineExecDescription, inlineExecReason, inlineExecReview, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isBlockAll, isDestructiveToolName, isHashedEntry, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isMaskedKind, isModeValue, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isRecordOnly, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, knobStatedChecks, levelCheckValue, levelChecks, levelOf, levelPackageSignals, maskDestination, maskPersonalData, maskPersonalValue, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, matchesTrustedEntry, matchesTrustedList, mcpServerFromToolName, narrativeRuleLabel, normalizeCommandForPolicy, normalizeDestination, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, normalizeRecipient, normalizeTrustedEntry, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolveAllChecks, resolveCheck, resolveCheckMap, resolvePinned, resolveShellInput, reviewsEveryInline, ruleServerMatches, safeMessage, sampleCopyCommand, scanArgs, scanArgumentSecrets, scanInjection, scanText, scanViews, sensitivePathMatch, shellRuleArgs, shellScriptOperands, ssrfCheckId, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripInvisible, stripTerminalEscapes, suggestFromApprovals, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, trustedEntryOf, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, unwrapRuleLabel, validateOverrides, validateRegex, validateShieldDefinition };
2378
- export type { ActionTemplateName, ApprovalRow, ArgumentInspectionResult, AuditEntryForClassify, BlastEnvFinding, BlastFinding, BlastResult, BlastSummary, CanaryHit, CanaryValue, CanaryView, CanonicalAgent, CanonicalFinding, CanonicalFindingType, CanonicalSourceType, CatalogSettings, CheckDef, CheckGroup, CheckSource, CheckText, Destination, DestinationKind, DlpMatch, EgressPolicy, EgressVerdict, ExtractContext, FileAccess, FileAccessContext, FsOpVerdict, InjectionConfidence, InjectionContext, InjectionMatch, InlineExecReview, InspectionInput, InspectionLayers, LegacyPolicyKnobs, Level, LoopWindowEvaluation, ModeValue, PackageEcosystem, PackageInstallRequest, PiiPattern, PipeChainAnalysis, PolicyConfig, PolicyContext, PolicyHostHooks, PolicyVerdict, PositionedArg, ProtectedFileVerdict, ProvenanceLookup, ProvenanceTrust, ResolvedCheck, RiskMetadata, ScanFinding, ScanSignals, ScanSummary, ScanView, ScoreTier, SessionExtractContext, SessionToolCall, Severity, ShellCommandAnalysis, ShellDestToken, ShellDestination, ShellExposure, ShellInputResolution, ShieldDefinition, ShieldOverrides, ShieldVerdict, SmartCondition, SmartRule, SsrfFloorOptions, SsrfMatch, SsrfTier, SsrfVerdict, SuggestOptions, Suggestion, ToolCallEntry, ToolCallRecord, ToolInspection, ToolInspectionEntry, TuningField, Verdict };
2441
+ export { ACTION_CHECKS, ACTION_TEMPLATES, AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, APP_SERVER_GLOB, APP_SHIELD_NAMES, APP_SHIELD_SPECS, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, CHECKS, CHECK_BY_ID, CHECK_GROUPS, CHECK_TEXT, CHECK_VERDICT_RANK, COMMAND_WRAPPERS, CONFIGURABLE_CHECK_IDS, COPY_VERBS, COST_PER_LOOP_ITER_USD, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, ENGINE_VERSION, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, GENERAL_ACTION_RULES, KNOB_GOVERNED, LEVELS, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, MODE_VALUES, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, REALTIME_PII_PATTERNS, REPLACED_SHIELDS, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, TUNING_FIELDS, VERDICTS, agentFileKind, analyzeFsOperation, analyzeGit, analyzePipeChain, analyzeShellCommand, argumentLeavesText, catalogSettingsFromConfig, checkDangerousSql, checkIdForCheckedBy, checkIdForRule, checkToLegacyPolicy, checkValue, checksFromLegacyPolicy, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, entryDisplay, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileAccessView, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitInvocations, gitRepoPath, hashDestination, hostMatches, incompleteFileVerdict, inlineExecDescription, inlineExecReason, inlineExecReview, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isBlockAll, isDestructiveToolName, isHashedEntry, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isMaskedKind, isModeValue, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isRecordOnly, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, knobStatedChecks, levelCheckValue, levelChecks, levelOf, levelPackageSignals, maskDestination, maskPersonalData, maskPersonalValue, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, matchesTrustedEntry, matchesTrustedList, mcpServerFromToolName, narrativeRuleLabel, normalizeCommandForPolicy, normalizeDestination, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, normalizeRecipient, normalizeTrustedEntry, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolveAllChecks, resolveCheck, resolveCheckMap, resolvePinned, resolveShellInput, reviewsEveryInline, ruleServerMatches, safeMessage, sampleCopyCommand, scanArgs, scanArgumentSecrets, scanInjection, scanInstructionWrite, scanText, scanViews, sensitivePathMatch, shellRuleArgs, shellScriptOperands, ssrfCheckId, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripInvisible, stripTerminalEscapes, suggestFromApprovals, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, trustedEntryOf, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, unwrapRuleLabel, validateOverrides, validateRegex, validateShieldDefinition };
2442
+ export type { ActionTemplateName, AgentFileKind, ApprovalRow, ArgumentInspectionResult, AuditEntryForClassify, BlastEnvFinding, BlastFinding, BlastResult, BlastSummary, CanaryHit, CanaryValue, CanaryView, CanonicalAgent, CanonicalFinding, CanonicalFindingType, CanonicalSourceType, CatalogSettings, CheckDef, CheckGroup, CheckSource, CheckText, Destination, DestinationKind, DlpMatch, EgressPolicy, EgressVerdict, ExtractContext, FileAccess, FileAccessContext, FsOpVerdict, GitAnalysis, GitFinding, GitInvocation, InjectionConfidence, InjectionContext, InjectionMatch, InlineExecReview, InspectionInput, InspectionLayers, LegacyPolicyKnobs, Level, LoopWindowEvaluation, ModeValue, PackageEcosystem, PackageInstallRequest, PiiPattern, PipeChainAnalysis, PolicyConfig, PolicyContext, PolicyHostHooks, PolicyVerdict, PositionedArg, ProtectedFileVerdict, ProvenanceLookup, ProvenanceTrust, ResolvedCheck, RiskMetadata, ScanFinding, ScanSignals, ScanSummary, ScanView, ScoreTier, SessionExtractContext, SessionToolCall, Severity, ShellCommandAnalysis, ShellDestToken, ShellDestination, ShellExposure, ShellInputResolution, ShieldDefinition, ShieldOverrides, ShieldVerdict, SmartCondition, SmartRule, SsrfFloorOptions, SsrfMatch, SsrfTier, SsrfVerdict, SuggestOptions, Suggestion, ToolCallEntry, ToolCallRecord, ToolInspection, ToolInspectionEntry, TuningField, Verdict };
package/dist/index.d.ts CHANGED
@@ -444,6 +444,8 @@ interface FileAccess {
444
444
  dotGlob?: boolean;
445
445
  followFinal: boolean;
446
446
  recursive?: boolean;
447
+ /** A write that adds to the file (`>>`, `tee -a`): its content stays. */
448
+ append?: true;
447
449
  /** This basename-joined candidate applies only if this operand is a directory. */
448
450
  directoryTarget?: string;
449
451
  candidates?: string[];
@@ -888,6 +890,9 @@ interface PolicyHostHooks {
888
890
  checkProvenance?: (binary: string, cwd?: string) => ProvenanceLookup;
889
891
  /** Returns true if the host is on the user's trusted-hosts allowlist. */
890
892
  isTrustedHost?: (host: string) => boolean;
893
+ /** The agent settings file at `absPath` as it is on disk now (a regular
894
+ * file within the host's size cap), or null (node9Firewall#413 part 4). */
895
+ readAgentSettings?: (absPath: string) => string | null;
891
896
  }
892
897
  interface PolicyVerdict {
893
898
  decision: 'allow' | 'review' | 'block';
@@ -948,11 +953,12 @@ declare function resolvePinned(matches: SmartRule[]): SmartRule | undefined;
948
953
  * Returns a reason string if dangerous, null if safe.
949
954
  */
950
955
  declare function checkDangerousSql(sql: string): string | null;
951
- declare function evaluatePolicy(config: PolicyConfig, toolName: string, args?: unknown, context?: PolicyContext, hooks?: PolicyHostHooks): Promise<PolicyVerdict>;
956
+ declare function evaluatePolicy(config: PolicyConfig, toolName: string, args?: unknown, context?: PolicyContext, hostHooks?: PolicyHostHooks): Promise<PolicyVerdict>;
952
957
  /** Returns true when toolName matches the config's ignoredTools list. */
953
958
  declare function isIgnoredTool(toolName: string, config: PolicyConfig): boolean;
954
959
 
955
960
  type ProtectedFileVerdict = PolicyVerdict & {
961
+ ruleName: string;
956
962
  path: string;
957
963
  operation: FileAccess['operation'];
958
964
  };
@@ -1106,6 +1112,53 @@ declare function redactText(text: string): {
1106
1112
  found: string[];
1107
1113
  };
1108
1114
 
1115
+ type AgentFileKind = 'instructions' | 'memory' | 'agents' | 'commands' | 'skills' | 'settings';
1116
+ /** The kind of agent file a normalized path is, or null. */
1117
+ declare function agentFileKind(p: string): AgentFileKind | null;
1118
+
1119
+ /**
1120
+ * Scan text about to be written into an agent instruction or memory file.
1121
+ * The three signals above, plus the override, fake-role and destination
1122
+ * signals of scanInjection; any one is a finding. Read on every view
1123
+ * (normalised, base64 and hex decoded), as the output scanner does.
1124
+ */
1125
+ declare function scanInstructionWrite(text: string): InjectionMatch | null;
1126
+
1127
+ type GitCheckId = 'commands.git-destructive' | 'commands.git-hooks-bypass' | 'commands.git-stage-all';
1128
+ interface GitFinding {
1129
+ checkId: GitCheckId;
1130
+ /** The rule name the audit log and the catalog's legacy table know. */
1131
+ ruleName: 'review-force-push' | 'review-git-destructive' | 'review-git-hooks-bypass' | 'review-git-stage-all';
1132
+ reason: string;
1133
+ description: string;
1134
+ /** The invocation as resolved, for the reason and the explain trace. */
1135
+ shown: string;
1136
+ }
1137
+ interface GitAnalysis {
1138
+ /** False when mvdan-sh could not parse the command: nothing was judged. */
1139
+ parsed: boolean;
1140
+ findings: GitFinding[];
1141
+ }
1142
+ /** One git invocation after resolution. */
1143
+ interface GitInvocation {
1144
+ /** The subcommand, or null when it could not be read (a dynamic word). */
1145
+ sub: string | null;
1146
+ /** The words after the subcommand; null marks a dynamic word. */
1147
+ args: (string | null)[];
1148
+ /** `-c key=value` pairs given before the subcommand, lowercased keys. */
1149
+ config: Map<string, string>;
1150
+ /** Assignments applied to this call (`HUSKY=0 git …`, `env K=V git …`). */
1151
+ env: Map<string, string | null>;
1152
+ /** How the call was written, for the reason. */
1153
+ shown: string;
1154
+ }
1155
+ /**
1156
+ * Every git finding in a shell command. Cached by the raw text; pure.
1157
+ */
1158
+ declare function analyzeGit(command: string): GitAnalysis;
1159
+ /** The git invocations a command makes, resolved. Exposed for the explain trace and tests. */
1160
+ declare function gitInvocations(command: string): GitInvocation[];
1161
+
1109
1162
  /**
1110
1163
  * The OSV ecosystem name, verbatim: it is the index directory, the bucket path
1111
1164
  * of the OSV archive and the `ecosystem` of the online query at once. `VSCode`
@@ -2117,7 +2170,7 @@ declare function matchCanary(text: string, values: readonly CanaryValue[]): Cana
2117
2170
  * so escaped values are seen (B23), like scanArgs. */
2118
2171
  declare function matchCanaryArgs(args: unknown, values: readonly CanaryValue[]): CanaryHit | null;
2119
2172
 
2120
- 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';
2173
+ type CanonicalFindingType = 'smart-rule' | 'ast-fs-op' | 'file-access' | 'dlp' | 'pii' | 'canary' | 'sensitive-file-read' | 'privilege-escalation' | 'destructive-op' | 'pipe-to-shell' | 'eval-of-remote' | 'loop' | 'long-output-redacted';
2121
2174
  type CanonicalAgent = 'claude' | 'gemini' | 'codex' | 'shell';
2122
2175
  type CanonicalSourceType = 'default' | 'shield' | 'user' | 'engine';
2123
2176
  interface CanonicalFinding {
@@ -2150,6 +2203,9 @@ interface CanonicalFinding {
2150
2203
  sourceType: CanonicalSourceType;
2151
2204
  /** Optional shield/source label for UI. */
2152
2205
  shieldLabel?: string;
2206
+ /** The catalog check the gate names for the same call (`files.system-dirs`,
2207
+ * `commands.git-hooks-bypass`, ...). Set on 'file-access' findings. */
2208
+ checkId?: string;
2153
2209
  /** When this exact (post-dedupe) finding was first / last seen. */
2154
2210
  firstSeenAt: string;
2155
2211
  lastSeenAt: string;
@@ -2203,6 +2259,14 @@ interface ExtractContext {
2203
2259
  kind?: string;
2204
2260
  path?: string;
2205
2261
  }>;
2262
+ /** The session's working directory, absolute, when the transcript carries
2263
+ * one. A relative file_path resolves against it for the file checks. */
2264
+ cwd?: string;
2265
+ /** The user's home directory (first) as the gate's FileAccessContext has it. */
2266
+ homeDirs?: string[];
2267
+ /** Catalog settings for the file checks. Absent means the defaults (the
2268
+ * Standard level), which keeps extractor output machine-independent. */
2269
+ catalogSettings?: CatalogSettings;
2206
2270
  }
2207
2271
  interface SessionExtractContext {
2208
2272
  sessionId: string;
@@ -2251,7 +2315,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
2251
2315
  * and fails CI when the hash drifts without a version bump — forgetting
2252
2316
  * is loud, not silent.
2253
2317
  */
2254
- declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v31";
2318
+ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v32";
2255
2319
  /**
2256
2320
  * SHA-256 prefix of the detector-source files
2257
2321
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -2262,7 +2326,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v31";
2262
2326
  * files changed, this hash must change too, and you must consciously
2263
2327
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
2264
2328
  */
2265
- declare const CANONICAL_EXTRACTOR_HASH = "60048df5a64eb7c0";
2329
+ declare const CANONICAL_EXTRACTOR_HASH = "bf14326b92bf1718";
2266
2330
  declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
2267
2331
  declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
2268
2332
  /**
@@ -2374,5 +2438,5 @@ declare function scanArgumentSecrets(args: unknown): DlpMatch | null;
2374
2438
  /** Engine version stamped on audit entries for future drift detection. */
2375
2439
  declare const ENGINE_VERSION = "1.4.0";
2376
2440
 
2377
- export { ACTION_CHECKS, ACTION_TEMPLATES, AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, APP_SERVER_GLOB, APP_SHIELD_NAMES, APP_SHIELD_SPECS, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, CHECKS, CHECK_BY_ID, CHECK_GROUPS, CHECK_TEXT, CHECK_VERDICT_RANK, COMMAND_WRAPPERS, CONFIGURABLE_CHECK_IDS, COPY_VERBS, COST_PER_LOOP_ITER_USD, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, ENGINE_VERSION, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, GENERAL_ACTION_RULES, KNOB_GOVERNED, LEVELS, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, MODE_VALUES, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, REALTIME_PII_PATTERNS, REPLACED_SHIELDS, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, TUNING_FIELDS, VERDICTS, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, argumentLeavesText, catalogSettingsFromConfig, checkDangerousSql, checkIdForCheckedBy, checkIdForRule, checkToLegacyPolicy, checkValue, checksFromLegacyPolicy, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, entryDisplay, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileAccessView, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hashDestination, hostMatches, incompleteFileVerdict, inlineExecDescription, inlineExecReason, inlineExecReview, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isBlockAll, isDestructiveToolName, isHashedEntry, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isMaskedKind, isModeValue, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isRecordOnly, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, knobStatedChecks, levelCheckValue, levelChecks, levelOf, levelPackageSignals, maskDestination, maskPersonalData, maskPersonalValue, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, matchesTrustedEntry, matchesTrustedList, mcpServerFromToolName, narrativeRuleLabel, normalizeCommandForPolicy, normalizeDestination, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, normalizeRecipient, normalizeTrustedEntry, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolveAllChecks, resolveCheck, resolveCheckMap, resolvePinned, resolveShellInput, reviewsEveryInline, ruleServerMatches, safeMessage, sampleCopyCommand, scanArgs, scanArgumentSecrets, scanInjection, scanText, scanViews, sensitivePathMatch, shellRuleArgs, shellScriptOperands, ssrfCheckId, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripInvisible, stripTerminalEscapes, suggestFromApprovals, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, trustedEntryOf, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, unwrapRuleLabel, validateOverrides, validateRegex, validateShieldDefinition };
2378
- export type { ActionTemplateName, ApprovalRow, ArgumentInspectionResult, AuditEntryForClassify, BlastEnvFinding, BlastFinding, BlastResult, BlastSummary, CanaryHit, CanaryValue, CanaryView, CanonicalAgent, CanonicalFinding, CanonicalFindingType, CanonicalSourceType, CatalogSettings, CheckDef, CheckGroup, CheckSource, CheckText, Destination, DestinationKind, DlpMatch, EgressPolicy, EgressVerdict, ExtractContext, FileAccess, FileAccessContext, FsOpVerdict, InjectionConfidence, InjectionContext, InjectionMatch, InlineExecReview, InspectionInput, InspectionLayers, LegacyPolicyKnobs, Level, LoopWindowEvaluation, ModeValue, PackageEcosystem, PackageInstallRequest, PiiPattern, PipeChainAnalysis, PolicyConfig, PolicyContext, PolicyHostHooks, PolicyVerdict, PositionedArg, ProtectedFileVerdict, ProvenanceLookup, ProvenanceTrust, ResolvedCheck, RiskMetadata, ScanFinding, ScanSignals, ScanSummary, ScanView, ScoreTier, SessionExtractContext, SessionToolCall, Severity, ShellCommandAnalysis, ShellDestToken, ShellDestination, ShellExposure, ShellInputResolution, ShieldDefinition, ShieldOverrides, ShieldVerdict, SmartCondition, SmartRule, SsrfFloorOptions, SsrfMatch, SsrfTier, SsrfVerdict, SuggestOptions, Suggestion, ToolCallEntry, ToolCallRecord, ToolInspection, ToolInspectionEntry, TuningField, Verdict };
2441
+ export { ACTION_CHECKS, ACTION_TEMPLATES, AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, APP_SERVER_GLOB, APP_SHIELD_NAMES, APP_SHIELD_SPECS, ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, CHECKS, CHECK_BY_ID, CHECK_GROUPS, CHECK_TEXT, CHECK_VERDICT_RANK, COMMAND_WRAPPERS, CONFIGURABLE_CHECK_IDS, COPY_VERBS, COST_PER_LOOP_ITER_USD, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, ENGINE_VERSION, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, GENERAL_ACTION_RULES, KNOB_GOVERNED, LEVELS, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, MODE_VALUES, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, REALTIME_PII_PATTERNS, REPLACED_SHIELDS, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, TUNING_FIELDS, VERDICTS, agentFileKind, analyzeFsOperation, analyzeGit, analyzePipeChain, analyzeShellCommand, argumentLeavesText, catalogSettingsFromConfig, checkDangerousSql, checkIdForCheckedBy, checkIdForRule, checkToLegacyPolicy, checkValue, checksFromLegacyPolicy, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, entryDisplay, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileAccessView, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitInvocations, gitRepoPath, hashDestination, hostMatches, incompleteFileVerdict, inlineExecDescription, inlineExecReason, inlineExecReview, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isBlockAll, isDestructiveToolName, isHashedEntry, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, isMaskedKind, isModeValue, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isRecordOnly, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, knobStatedChecks, levelCheckValue, levelChecks, levelOf, levelPackageSignals, maskDestination, maskPersonalData, maskPersonalValue, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, matchesTrustedEntry, matchesTrustedList, mcpServerFromToolName, narrativeRuleLabel, normalizeCommandForPolicy, normalizeDestination, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, normalizeRecipient, normalizeTrustedEntry, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolveAllChecks, resolveCheck, resolveCheckMap, resolvePinned, resolveShellInput, reviewsEveryInline, ruleServerMatches, safeMessage, sampleCopyCommand, scanArgs, scanArgumentSecrets, scanInjection, scanInstructionWrite, scanText, scanViews, sensitivePathMatch, shellRuleArgs, shellScriptOperands, ssrfCheckId, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripInvisible, stripTerminalEscapes, suggestFromApprovals, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, trustedEntryOf, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, unwrapRuleLabel, validateOverrides, validateRegex, validateShieldDefinition };
2442
+ export type { ActionTemplateName, AgentFileKind, ApprovalRow, ArgumentInspectionResult, AuditEntryForClassify, BlastEnvFinding, BlastFinding, BlastResult, BlastSummary, CanaryHit, CanaryValue, CanaryView, CanonicalAgent, CanonicalFinding, CanonicalFindingType, CanonicalSourceType, CatalogSettings, CheckDef, CheckGroup, CheckSource, CheckText, Destination, DestinationKind, DlpMatch, EgressPolicy, EgressVerdict, ExtractContext, FileAccess, FileAccessContext, FsOpVerdict, GitAnalysis, GitFinding, GitInvocation, InjectionConfidence, InjectionContext, InjectionMatch, InlineExecReview, InspectionInput, InspectionLayers, LegacyPolicyKnobs, Level, LoopWindowEvaluation, ModeValue, PackageEcosystem, PackageInstallRequest, PiiPattern, PipeChainAnalysis, PolicyConfig, PolicyContext, PolicyHostHooks, PolicyVerdict, PositionedArg, ProtectedFileVerdict, ProvenanceLookup, ProvenanceTrust, ResolvedCheck, RiskMetadata, ScanFinding, ScanSignals, ScanSummary, ScanView, ScoreTier, SessionExtractContext, SessionToolCall, Severity, ShellCommandAnalysis, ShellDestToken, ShellDestination, ShellExposure, ShellInputResolution, ShieldDefinition, ShieldOverrides, ShieldVerdict, SmartCondition, SmartRule, SsrfFloorOptions, SsrfMatch, SsrfTier, SsrfVerdict, SuggestOptions, Suggestion, ToolCallEntry, ToolCallRecord, ToolInspection, ToolInspectionEntry, TuningField, Verdict };