@node9/policy-engine 2.14.0 → 2.14.1

package/dist/index.d.mts

@@ -207,6 +207,41 @@ declare function detectDangerousShellExec(command: string): 'block' | 'review' |
 /** @deprecated Use detectDangerousShellExec — kept for backwards compatibility */
 declare const detectDangerousEval: typeof detectDangerousShellExec;
 declare const FS_READ_TOOLS: Set<string>;
+interface PatternShape {
+    /** Flags MEASURED to consume the next word as a value. */
+    takesValue: Set<string>;
+    /**
+     * Flags MEASURED to consume NOTHING. Needed POSITIVELY, which is the lesson of
+     * /code-review round 2: the first cut excused "the first positional whose
+     * preceding flag is not known to consume", so an UNLISTED value-taking flag
+     * handed its own operand to the excuse. `grep --include-from KEY needle
+     * notes.txt` opened KEY under ugrep and read ALLOW. The comment that shipped
+     * with round 1 -- "a flag MISSING from the table only leaves a false positive"
+     * -- was wrong, and wrong in the unsafe direction.
+     *
+     * So the flag before a candidate word has THREE states, not two:
+     *   in noValue    -> the next word really is the first positional: excusable
+     *   in takesValue -> that word is the flag's value: skip it and keep looking
+     *   UNKNOWN       -> excuse NOTHING in this command
+     * Unknown is the safe state: it leaves a false positive, never a bypass. That
+     * is what makes this table's incompleteness safe, which no flag list can be on
+     * its own -- and it has to be, because `grep` is not one program (GNU grep,
+     * ugrep, busybox) and the engine cannot know which one will run.
+     */
+    noValue: Set<string>;
+    /** Flags whose operand IS the search pattern. */
+    patternFlags: Set<string>;
+    /** Flags after which NO positional pattern is expected (pattern from a file,
+     *  or a listing mode). */
+    noPatternFlags: Set<string>;
+}
+/** Exported so the spec DERIVES its control rows from the table rather than
+ *  hand-writing them: a flag added here gains a row for free. */
+declare const PATTERN_VERB_NAMES: string[];
+declare const patternShapeOf: (verb: string) => PatternShape | undefined;
+/** JAIL-10's table, exported for the same reason: the spec derives the split
+ *  between "operand is a FILE the verb opens" and "operand is an argument". */
+declare const fileOperandFlagsOf: (verb: string) => Set<string> | undefined;
 /** How a copy verb's arguments are read. */
 interface CopyShape {
     /**
@@ -224,6 +259,15 @@ interface CopyShape {
     targetDirFlag?: boolean;
     /** Flags whose operand is NEVER a source: a short LETTER ('i') or a long name ('--exclude'). */
     skipFlags?: string[];
+    /**
+     * Short LETTERS this verb's getopt treats as taking an argument. Needed to read
+     * a bundle the way getopt does: the FIRST such letter swallows the rest of the
+     * token, so `-St` is `-S t` (suffix "t") and NOT `--target-directory`.
+     * /code-review round 7 measured the cost of guessing: `cp -St ~/.ssh/id_rsa
+     * /tmp/stolen` copies the key on real coreutils 9.4 and produced no finding,
+     * because a `t` anywhere in the bundle was read as the target-directory flag.
+     */
+    valueLetters?: string[];
 }
 declare const COPY_VERBS: Record<string, CopyShape>;
 interface FsOpVerdict {
@@ -1251,7 +1295,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
  * and fails CI when the hash drifts without a version bump — forgetting
  * is loud, not silent.
  */
-declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v14";
+declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v15";
 /**
  * SHA-256 prefix of the detector-source files
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -1262,7 +1306,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v14";
  * files changed, this hash must change too, and you must consciously
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
  */
-declare const CANONICAL_EXTRACTOR_HASH = "8b5729fe236a195b";
+declare const CANONICAL_EXTRACTOR_HASH = "5dad4c8f07121f6c";
 declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
 declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
 /**
@@ -1382,4 +1426,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, NET_BINARIES, 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, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeIpLiteral, parseAllSshHostsFromCommand, parseDestHost, positionedArgs, previewArgs, redactText, resolvePinned, sampleCopyCommand, scanArgs, scanInjection, scanText, sensitivePathMatch, ssrfDestinationFloor, ssrfFloor, ssrfReason, 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 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, 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, sampleCopyCommand, scanArgs, scanInjection, scanText, sensitivePathMatch, ssrfDestinationFloor, ssrfFloor, ssrfReason, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };

package/dist/index.d.ts

@@ -207,6 +207,41 @@ declare function detectDangerousShellExec(command: string): 'block' | 'review' |
 /** @deprecated Use detectDangerousShellExec — kept for backwards compatibility */
 declare const detectDangerousEval: typeof detectDangerousShellExec;
 declare const FS_READ_TOOLS: Set<string>;
+interface PatternShape {
+    /** Flags MEASURED to consume the next word as a value. */
+    takesValue: Set<string>;
+    /**
+     * Flags MEASURED to consume NOTHING. Needed POSITIVELY, which is the lesson of
+     * /code-review round 2: the first cut excused "the first positional whose
+     * preceding flag is not known to consume", so an UNLISTED value-taking flag
+     * handed its own operand to the excuse. `grep --include-from KEY needle
+     * notes.txt` opened KEY under ugrep and read ALLOW. The comment that shipped
+     * with round 1 -- "a flag MISSING from the table only leaves a false positive"
+     * -- was wrong, and wrong in the unsafe direction.
+     *
+     * So the flag before a candidate word has THREE states, not two:
+     *   in noValue    -> the next word really is the first positional: excusable
+     *   in takesValue -> that word is the flag's value: skip it and keep looking
+     *   UNKNOWN       -> excuse NOTHING in this command
+     * Unknown is the safe state: it leaves a false positive, never a bypass. That
+     * is what makes this table's incompleteness safe, which no flag list can be on
+     * its own -- and it has to be, because `grep` is not one program (GNU grep,
+     * ugrep, busybox) and the engine cannot know which one will run.
+     */
+    noValue: Set<string>;
+    /** Flags whose operand IS the search pattern. */
+    patternFlags: Set<string>;
+    /** Flags after which NO positional pattern is expected (pattern from a file,
+     *  or a listing mode). */
+    noPatternFlags: Set<string>;
+}
+/** Exported so the spec DERIVES its control rows from the table rather than
+ *  hand-writing them: a flag added here gains a row for free. */
+declare const PATTERN_VERB_NAMES: string[];
+declare const patternShapeOf: (verb: string) => PatternShape | undefined;
+/** JAIL-10's table, exported for the same reason: the spec derives the split
+ *  between "operand is a FILE the verb opens" and "operand is an argument". */
+declare const fileOperandFlagsOf: (verb: string) => Set<string> | undefined;
 /** How a copy verb's arguments are read. */
 interface CopyShape {
     /**
@@ -224,6 +259,15 @@ interface CopyShape {
     targetDirFlag?: boolean;
     /** Flags whose operand is NEVER a source: a short LETTER ('i') or a long name ('--exclude'). */
     skipFlags?: string[];
+    /**
+     * Short LETTERS this verb's getopt treats as taking an argument. Needed to read
+     * a bundle the way getopt does: the FIRST such letter swallows the rest of the
+     * token, so `-St` is `-S t` (suffix "t") and NOT `--target-directory`.
+     * /code-review round 7 measured the cost of guessing: `cp -St ~/.ssh/id_rsa
+     * /tmp/stolen` copies the key on real coreutils 9.4 and produced no finding,
+     * because a `t` anywhere in the bundle was read as the target-directory flag.
+     */
+    valueLetters?: string[];
 }
 declare const COPY_VERBS: Record<string, CopyShape>;
 interface FsOpVerdict {
@@ -1251,7 +1295,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
  * and fails CI when the hash drifts without a version bump — forgetting
  * is loud, not silent.
  */
-declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v14";
+declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v15";
 /**
  * SHA-256 prefix of the detector-source files
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -1262,7 +1306,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v14";
  * files changed, this hash must change too, and you must consciously
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
  */
-declare const CANONICAL_EXTRACTOR_HASH = "8b5729fe236a195b";
+declare const CANONICAL_EXTRACTOR_HASH = "5dad4c8f07121f6c";
 declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
 declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
 /**
@@ -1382,4 +1426,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, NET_BINARIES, 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, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeIpLiteral, parseAllSshHostsFromCommand, parseDestHost, positionedArgs, previewArgs, redactText, resolvePinned, sampleCopyCommand, scanArgs, scanInjection, scanText, sensitivePathMatch, ssrfDestinationFloor, ssrfFloor, ssrfReason, 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 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, 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, sampleCopyCommand, scanArgs, scanInjection, scanText, sensitivePathMatch, ssrfDestinationFloor, ssrfFloor, ssrfReason, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };