@node9/policy-engine 2.13.1 → 2.14.0

package/dist/index.d.mts

@@ -207,6 +207,25 @@ 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>;
+/** How a copy verb's arguments are read. */
+interface CopyShape {
+    /**
+     *  allButLast   cp SRC... DEST         (GNU -t moves DEST into a flag: every slot is a source)
+     *  first        ln TARGET LINK
+     *  all          gzip -c FILE
+     *  archive      tar/zip/ar/7z: the inputs after the archive slot, in a WRITING mode
+     *  flagOperand  the source is a flag's operand: az ... upload -f SRC / --file SRC
+     */
+    source: 'allButLast' | 'first' | 'all' | 'archive' | 'flagOperand';
+    archive?: 'tar' | 'zip' | 'ar' | '7z';
+    /** flagOperand: the flags (short letter or long name) whose operand is the source. */
+    sourceFlags?: string[];
+    /** GNU `-t DIR` / `--target-directory`: the destination is in a flag. */
+    targetDirFlag?: boolean;
+    /** Flags whose operand is NEVER a source: a short LETTER ('i') or a long name ('--exclude'). */
+    skipFlags?: string[];
+}
+declare const COPY_VERBS: Record<string, CopyShape>;
 interface FsOpVerdict {
     ruleName: string;
     verdict: 'block' | 'review';
@@ -253,6 +272,29 @@ declare function detectInlineExec(command: string): boolean;
  * the tool-managed cache allow-list. Used to gate `rm -rf` on home paths.
  */
 declare function isProtectedHomePath(rawPath: string): boolean;
+/**
+ * Extract literal-text positional arguments from a CallExpr. Skips flags
+ * (anything starting with `-`) and ParamExp/CmdSubst (dynamic) parts. Returns
+ * the resolved string for each arg that is purely literal text.
+ */
+/** A resolved, non-flag argument and where it sits. */
+interface PositionedArg {
+    /** The resolved literal. */
+    value: string;
+    /** 0-based SLOT among non-flag words -- `cp SRC DEST`: SRC is 0, DEST is 1. */
+    index: number;
+    /** Absolute index in the resolved word list, for explainability. */
+    argv: number;
+    /** The flag immediately before this word (`ssh -i KEY`: '-i'), else null. */
+    afterFlag: string | null;
+}
+/**
+ * The positioned non-flag words of `words[from..to)`. A dynamic word (null)
+ * occupies no slot AND breaks the flag link -- `-v $SRC KEY` gives KEY no flag,
+ * because something unknowable sat between them. Its `.map(a => a.value)` is
+ * exactly the pre-stage-3 filter, which jail-position.spec.ts pins.
+ */
+declare function positionedArgs(words: (string | null)[], from?: number, to?: number): PositionedArg[];
 interface ShellDestination {
     /** Extracted hostname, lowercased (e.g. "evil.com", "10.0.0.5"). */
     host: string;
@@ -295,6 +337,12 @@ interface ShellDestToken {
  */
 declare function extractShellDestTokens(command: string): ShellDestToken[];
 declare function analyzeFsOperation(command: string): FsOpVerdict | null;
+/**
+ * One representative command per copy verb, for a gate test that DERIVES its
+ * rows from COPY_VERBS instead of keeping a second hand list (the trap the
+ * prescreen comment above describes). `src` is the path being copied out.
+ */
+declare function sampleCopyCommand(verb: string, src: string): string;
 interface ShellCommandAnalysis {
     /** First word of every CallExpr — the command names invoked. */
     actions: string[];
@@ -1203,7 +1251,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-v13";
+declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v14";
 /**
  * SHA-256 prefix of the detector-source files
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -1214,7 +1262,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v13";
  * files changed, this hash must change too, and you must consciously
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
  */
-declare const CANONICAL_EXTRACTOR_HASH = "4622a2f41696af04";
+declare const CANONICAL_EXTRACTOR_HASH = "8b5729fe236a195b";
 declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
 declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
 /**
@@ -1334,4 +1382,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, 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 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, previewArgs, redactText, resolvePinned, 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, 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 };

package/dist/index.d.ts

@@ -207,6 +207,25 @@ 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>;
+/** How a copy verb's arguments are read. */
+interface CopyShape {
+    /**
+     *  allButLast   cp SRC... DEST         (GNU -t moves DEST into a flag: every slot is a source)
+     *  first        ln TARGET LINK
+     *  all          gzip -c FILE
+     *  archive      tar/zip/ar/7z: the inputs after the archive slot, in a WRITING mode
+     *  flagOperand  the source is a flag's operand: az ... upload -f SRC / --file SRC
+     */
+    source: 'allButLast' | 'first' | 'all' | 'archive' | 'flagOperand';
+    archive?: 'tar' | 'zip' | 'ar' | '7z';
+    /** flagOperand: the flags (short letter or long name) whose operand is the source. */
+    sourceFlags?: string[];
+    /** GNU `-t DIR` / `--target-directory`: the destination is in a flag. */
+    targetDirFlag?: boolean;
+    /** Flags whose operand is NEVER a source: a short LETTER ('i') or a long name ('--exclude'). */
+    skipFlags?: string[];
+}
+declare const COPY_VERBS: Record<string, CopyShape>;
 interface FsOpVerdict {
     ruleName: string;
     verdict: 'block' | 'review';
@@ -253,6 +272,29 @@ declare function detectInlineExec(command: string): boolean;
  * the tool-managed cache allow-list. Used to gate `rm -rf` on home paths.
  */
 declare function isProtectedHomePath(rawPath: string): boolean;
+/**
+ * Extract literal-text positional arguments from a CallExpr. Skips flags
+ * (anything starting with `-`) and ParamExp/CmdSubst (dynamic) parts. Returns
+ * the resolved string for each arg that is purely literal text.
+ */
+/** A resolved, non-flag argument and where it sits. */
+interface PositionedArg {
+    /** The resolved literal. */
+    value: string;
+    /** 0-based SLOT among non-flag words -- `cp SRC DEST`: SRC is 0, DEST is 1. */
+    index: number;
+    /** Absolute index in the resolved word list, for explainability. */
+    argv: number;
+    /** The flag immediately before this word (`ssh -i KEY`: '-i'), else null. */
+    afterFlag: string | null;
+}
+/**
+ * The positioned non-flag words of `words[from..to)`. A dynamic word (null)
+ * occupies no slot AND breaks the flag link -- `-v $SRC KEY` gives KEY no flag,
+ * because something unknowable sat between them. Its `.map(a => a.value)` is
+ * exactly the pre-stage-3 filter, which jail-position.spec.ts pins.
+ */
+declare function positionedArgs(words: (string | null)[], from?: number, to?: number): PositionedArg[];
 interface ShellDestination {
     /** Extracted hostname, lowercased (e.g. "evil.com", "10.0.0.5"). */
     host: string;
@@ -295,6 +337,12 @@ interface ShellDestToken {
  */
 declare function extractShellDestTokens(command: string): ShellDestToken[];
 declare function analyzeFsOperation(command: string): FsOpVerdict | null;
+/**
+ * One representative command per copy verb, for a gate test that DERIVES its
+ * rows from COPY_VERBS instead of keeping a second hand list (the trap the
+ * prescreen comment above describes). `src` is the path being copied out.
+ */
+declare function sampleCopyCommand(verb: string, src: string): string;
 interface ShellCommandAnalysis {
     /** First word of every CallExpr — the command names invoked. */
     actions: string[];
@@ -1203,7 +1251,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-v13";
+declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v14";
 /**
  * SHA-256 prefix of the detector-source files
  * (canonical.ts + pii.ts + destructive-regex.ts).
@@ -1214,7 +1262,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v13";
  * files changed, this hash must change too, and you must consciously
  * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
  */
-declare const CANONICAL_EXTRACTOR_HASH = "4622a2f41696af04";
+declare const CANONICAL_EXTRACTOR_HASH = "8b5729fe236a195b";
 declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
 declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
 /**
@@ -1334,4 +1382,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, 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 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, previewArgs, redactText, resolvePinned, 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, 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 };

package/dist/index.js

@@ -37,6 +37,7 @@ __export(src_exports, {
   CANONICAL_EXTRACTOR_HASH: () => CANONICAL_EXTRACTOR_HASH,
   CANONICAL_EXTRACTOR_VERSION: () => CANONICAL_EXTRACTOR_VERSION,
   COMMAND_WRAPPERS: () => COMMAND_WRAPPERS,
+  COPY_VERBS: () => COPY_VERBS,
   COST_PER_LOOP_ITER_USD: () => COST_PER_LOOP_ITER_USD,
   DEFAULT_EGRESS_ALLOWLIST: () => DEFAULT_EGRESS_ALLOWLIST,
   DESTINATION_ARGS: () => DESTINATION_ARGS,
@@ -106,9 +107,11 @@ __export(src_exports, {
   normalizeIpLiteral: () => normalizeIpLiteral,
   parseAllSshHostsFromCommand: () => parseAllSshHostsFromCommand,
   parseDestHost: () => parseDestHost,
+  positionedArgs: () => positionedArgs,
   previewArgs: () => previewArgs,
   redactText: () => redactText,
   resolvePinned: () => resolvePinned,
+  sampleCopyCommand: () => sampleCopyCommand,
   scanArgs: () => scanArgs,
   scanInjection: () => scanInjection,
   scanText: () => scanText,
@@ -1442,12 +1445,56 @@ var FS_READ_TOOLS = /* @__PURE__ */ new Set([
   "nl",
   "dd"
 ]);
+var SCP_VALUE_FLAGS = ["i", "F", "o", "c", "S", "P", "J", "D", "W", "l"];
+var RSYNC_SKIP = [
+  "e",
+  "--rsh",
+  "--exclude",
+  "--exclude-from",
+  "--include",
+  "--include-from",
+  "--files-from",
+  "f",
+  "--filter"
+];
+var COPY_VERBS = {
+  cp: { source: "allButLast", targetDirFlag: true },
+  mv: { source: "allButLast", targetDirFlag: true },
+  install: { source: "allButLast", targetDirFlag: true },
+  ln: { source: "first", targetDirFlag: true },
+  scp: { source: "allButLast", skipFlags: SCP_VALUE_FLAGS },
+  rsync: { source: "allButLast", skipFlags: RSYNC_SKIP },
+  tar: {
+    source: "archive",
+    archive: "tar",
+    skipFlags: ["f", "X", "T", "--file", "--exclude", "--exclude-from", "--files-from"]
+  },
+  zip: { source: "archive", archive: "zip", skipFlags: ["x", "i", "--exclude", "--include"] },
+  ar: { source: "archive", archive: "ar" },
+  "7z": { source: "archive", archive: "7z", skipFlags: ["x", "--exclude"] },
+  gzip: { source: "all" },
+  bzip2: { source: "all" },
+  xz: { source: "all" },
+  "docker cp": { source: "allButLast" },
+  "kubectl cp": { source: "allButLast" },
+  "gsutil cp": { source: "allButLast" },
+  "gsutil rsync": { source: "allButLast" },
+  "rclone copy": { source: "allButLast" },
+  "rclone sync": { source: "allButLast" },
+  "aws s3 cp": { source: "allButLast" },
+  "aws s3 mv": { source: "allButLast" },
+  "aws s3 sync": { source: "allButLast" },
+  "gcloud storage cp": { source: "allButLast" },
+  "az storage blob upload": { source: "flagOperand", sourceFlags: ["f", "--file"] }
+};
+var TAR_MODE_WORD = /^[a-zA-Z]+$/;
+var COPY_VERB_HEADS = new Set(Object.keys(COPY_VERBS).map((k) => k.split(" ")[0]));
 var FS_OP_PRESCREEN_RE = new RegExp(
   // A quote is a separator too: `eval "cat X"` and `sh -c 'cat X'` put the
   // reader right after `"` / `'`, and without these two characters the
   // prescreen rejected every string-wrapped read before the parser ran.
   // Found 2026-09-11 by instrumenting the walk -- no CallExpr was ever visited.
-  `(?:^|[\\s|;&("'\`\\n])(?:rm|${[...FS_READ_TOOLS].map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b|(?<!<)<(?!<)`
+  `(?:^|[\\s|;&("'\`\\n/])(?:rm|${[...FS_READ_TOOLS, ...COPY_VERB_HEADS].map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b|(?<!<)<(?!<)`
 );
 var HOME_CACHE_ALLOWLIST = [
   ".cache",
@@ -1882,20 +1929,32 @@ function isProtectedHomePath(rawPath) {
   }
   return true;
 }
-function extractLiteralArgs(callExpr) {
-  const args = callExpr.Args || [];
-  if (args.length === 0) return { name: "", flags: [], paths: [], words: [] };
-  const words = args.map((a) => resolveWordLiteral(a));
-  const name = (words[0] ?? "").toLowerCase();
-  const flags = [];
-  const paths = [];
-  for (let i = 1; i < words.length; i++) {
+function positionedArgs(words, from = 1, to = words.length) {
+  const out = [];
+  let afterFlag = null;
+  for (let i = from; i < to; i++) {
     const v = words[i];
-    if (v === null) continue;
-    if (v.startsWith("-")) flags.push(v);
-    else paths.push(v);
+    if (v === null) {
+      afterFlag = null;
+      continue;
+    }
+    if (v.startsWith("-")) {
+      afterFlag = v;
+      continue;
+    }
+    out.push({ value: v, index: out.length, argv: i, afterFlag });
+    afterFlag = null;
   }
-  return { name, flags, paths, words };
+  return out;
+}
+function extractLiteralArgs(callExpr) {
+  const rawArgs = callExpr.Args || [];
+  if (rawArgs.length === 0) return { name: "", flags: [], paths: [], words: [], args: [] };
+  const words = rawArgs.map((a) => resolveWordLiteral(a));
+  const name = baseWord(words[0]);
+  const flags = words.slice(1).filter((w) => w !== null && w.startsWith("-"));
+  const args = positionedArgs(words);
+  return { name, flags, paths: args.map((a) => a.value), words, args };
 }
 var NET_BINARIES = /* @__PURE__ */ new Set([
   "curl",
@@ -2319,6 +2378,9 @@ function analyzeFsOperationImpl(command, depth = 0) {
           if (result?.verdict === "block") return false;
         }
       }
+      for (const p of copySourcePaths(words)) {
+        result = stricter(result, copyVerdictOf(matchSensitivePath2(p)));
+      }
       return true;
     });
     return result;
@@ -2331,6 +2393,157 @@ function stricter(a, b) {
   if (!b) return a;
   return b.verdict === "block" && a.verdict !== "block" ? b : a;
 }
+function flagInfo(w) {
+  if (w.startsWith("--")) {
+    const eq = w.indexOf("=");
+    return eq < 0 ? { letter: null, long: w, attached: null } : { letter: null, long: w.slice(0, eq), attached: w.slice(eq + 1) };
+  }
+  const m = /^-([a-zA-Z]+)(.*)$/.exec(w);
+  if (!m) return { letter: null, long: null, attached: null };
+  return { letter: m[1][m[1].length - 1], long: null, attached: m[2] === "" ? null : m[2] };
+}
+function flagIs(w, names) {
+  if (w === null) return false;
+  const f = flagInfo(w);
+  return names.some((n) => n.startsWith("--") ? f.long === n : f.letter === n);
+}
+function operandOf(a, names) {
+  if (!names || a.afterFlag === null) return false;
+  return flagIs(a.afterFlag, names) && flagInfo(a.afterFlag).attached === null;
+}
+function resolveCopyShape(words, h) {
+  const verb = baseWord(words[h]);
+  if (!verb) return null;
+  const direct = COPY_VERBS[verb];
+  if (direct) return { shape: direct, last: h };
+  const slots = positionedArgs(words, h + 1);
+  for (let i = 0; i < slots.length; i++) {
+    for (let n = 3; n >= 1; n--) {
+      const part = slots.slice(i, i + n);
+      if (part.length < n) continue;
+      const key = [verb, ...part.map((a) => a.value.toLowerCase())].join(" ");
+      const shape = COPY_VERBS[key];
+      if (shape) return { shape, last: part[n - 1].argv };
+    }
+    if (slots[i].afterFlag === null) return null;
+  }
+  return null;
+}
+var FIND_OPTIONS = /* @__PURE__ */ new Set(["-H", "-L", "-P"]);
+function findStartPoints(words, h) {
+  const k = words.findIndex((w, i) => i > h && w !== null && FIND_EXEC_FLAGS.has(w));
+  if (k < 0) return { k, starts: [] };
+  const firstPredicate = words.findIndex(
+    (w, i) => i > h && w !== null && w.startsWith("-") && !FIND_OPTIONS.has(w)
+  );
+  const end = firstPredicate > h ? firstPredicate : k;
+  return { k, starts: positionalAfter(words, h + 1, end) };
+}
+function copySourcePaths(words) {
+  const h = unwrapCommandHead(words);
+  const fi = words.findIndex((w, i) => i <= h && baseWord(w) === "find");
+  if (fi >= 0) {
+    const { k, starts } = findStartPoints(words, fi);
+    if (k < 0) return [];
+    const action = unwrapCommandHead(words.slice(k + 1));
+    return resolveCopyShape(words.slice(k + 1), action) ? starts : [];
+  }
+  if (!COPY_VERB_HEADS.has(baseWord(words[h]))) return [];
+  const r = resolveCopyShape(words, h);
+  if (!r) return [];
+  const { shape, last } = r;
+  const args = positionedArgs(words, last + 1);
+  const tail = words.slice(last + 1);
+  const skipped = (a) => operandOf(a, shape.skipFlags);
+  const targetDir = shape.targetDirFlag === true && tail.some((w) => w !== null && w.startsWith("-") && flagIs(w, ["t", "--target-directory"]));
+  const targetOperand = (a) => targetDir && operandOf(a, ["t", "--target-directory"]);
+  const lastOperand = [...tail].reverse().find((w) => w === null || !w.startsWith("-"));
+  const dynamicDest = lastOperand === null;
+  const destIsLastOperand = (shape.source === "allButLast" || shape.source === "first") && !targetDir && !dynamicDest;
+  if (destIsLastOperand && typeof lastOperand === "string" && matchSensitivePath2(lastOperand))
+    return [];
+  let src;
+  switch (shape.source) {
+    case "all":
+      src = args;
+      break;
+    case "first":
+      src = targetDir ? args : args.slice(0, 1);
+      break;
+    case "flagOperand": {
+      const inline = tail.filter((w) => w !== null && w.startsWith("--")).map((w) => flagInfo(w)).filter((f) => f.attached !== null && (shape.sourceFlags ?? []).includes(f.long ?? "")).map((f) => f.attached);
+      return [
+        ...args.filter(
+          (a) => flagIs(a.afterFlag, shape.sourceFlags ?? []) && flagInfo(a.afterFlag).attached === null
+        ).map((a) => a.value),
+        ...inline
+      ];
+    }
+    case "archive":
+      src = archiveInputs(shape.archive, args, tail);
+      break;
+    case "allButLast":
+      src = targetDir || dynamicDest ? args : args.slice(0, -1);
+      break;
+  }
+  return src.filter((a) => !skipped(a) && !targetOperand(a)).map((a) => a.value);
+}
+function archiveInputs(kind, args, tail) {
+  const first = args[0];
+  const bareKey = first && first.afterFlag === null && TAR_MODE_WORD.test(first.value);
+  if (kind === "tar") {
+    const flagsText = tail.filter((w) => w !== null && w.startsWith("-")).join(" ");
+    const mode = (bareKey ? first.value : "") + flagsText;
+    const extracting = /x|t/.test(bareKey ? first.value.replace(/f/g, "") : "") || /(^|\s)-[a-zA-Z]*[xt]|--extract|--list|--get/.test(flagsText);
+    const writing = /[cruA]/.test(bareKey ? first.value : "") || /(^|\s)-[a-zA-Z]*[cruA]|--create|--append|--update|--concatenate/.test(flagsText);
+    if (extracting && !writing) return [];
+    void mode;
+    let i = 0;
+    if (bareKey) {
+      i = 1;
+      const next = args[1];
+      if (first.value.includes("f") && next && next.afterFlag === null) i = 2;
+    }
+    return args.slice(i);
+  }
+  if (kind === "zip") return first && first.afterFlag === "-" ? args : args.slice(1);
+  if (kind === "ar") return bareKey ? args.slice(2) : args.slice(1);
+  return args.slice(2);
+}
+function sampleCopyCommand(verb, src) {
+  const shape = COPY_VERBS[verb];
+  if (!shape) throw new Error(`not a copy verb: ${verb}`);
+  const remote = /^(scp|rsync|aws |gsutil|gcloud|rclone|docker|kubectl)/.test(verb);
+  switch (shape.source) {
+    case "first":
+      return `${verb} -s ${src} /tmp/n9-link`;
+    case "all":
+      return `${verb} -c ${src} > /tmp/n9-out`;
+    case "flagOperand":
+      return `${verb} -f ${src} -c n9`;
+    case "archive":
+      return shape.archive === "tar" ? `tar czf /tmp/n9-out.tgz ${src}` : shape.archive === "zip" ? `zip -r /tmp/n9-out.zip ${src}` : shape.archive === "ar" ? `ar rc /tmp/n9-out.a ${src}` : `7z a /tmp/n9-out.7z ${src}`;
+    case "allButLast":
+      return `${verb} ${src} ${remote ? verb.startsWith("scp") || verb === "rsync" ? "user@host.invalid:/tmp/" : verb.startsWith("docker") || verb.startsWith("kubectl") ? "ctr:/tmp/" : "remote:/n9/" : "/tmp/n9-copy"}`;
+  }
+}
+var COPY_RULE_OF = {
+  "shield:project-jail:block-read-ssh": "shield:project-jail:review-copy-ssh",
+  "shield:project-jail:block-read-aws": "shield:project-jail:review-copy-aws",
+  "shield:project-jail:block-read-env": "shield:project-jail:review-copy-env",
+  "shield:project-jail:review-read-credentials": "shield:project-jail:review-copy-credentials"
+};
+function copyVerdictOf(hit) {
+  if (!hit) return null;
+  const ruleName = COPY_RULE_OF[hit.ruleName];
+  if (!ruleName) return null;
+  return {
+    ruleName,
+    verdict: "review",
+    reason: `Copying ${hit.path} moves a credential out of its jail (project-jail shield)`,
+    path: hit.path
+  };
+}
 function matchSensitivePath2(p) {
   for (const sp of SENSITIVE_PATH_RULES) {
     if (sp.match(p))
@@ -2338,14 +2551,15 @@ function matchSensitivePath2(p) {
   }
   return null;
 }
-var isReaderWord = (w) => w !== null && FS_READ_TOOLS.has(w.split("/").pop()?.toLowerCase() ?? "");
-var positionalAfter = (words, from, to = words.length) => words.slice(from, to).filter((w) => w !== null && !w.startsWith("-"));
+function baseWord(w) {
+  return (w ?? "").split("/").pop()?.toLowerCase() ?? "";
+}
+var isReaderWord = (w) => w !== null && FS_READ_TOOLS.has(baseWord(w));
+var positionalAfter = (words, from, to = words.length) => positionedArgs(words, from, to).map((a) => a.value);
 function wrappedReadPaths(words, name) {
   if (name === "find") {
-    const k = words.findIndex((w) => w !== null && FIND_EXEC_FLAGS.has(w));
-    if (k < 1 || !isReaderWord(words[k + 1] ?? null)) return null;
-    const firstPredicate = words.findIndex((w, i) => i > 0 && w !== null && w.startsWith("-"));
-    return positionalAfter(words, 1, firstPredicate > 0 ? firstPredicate : k);
+    const { k, starts } = findStartPoints(words, 0);
+    return k > 0 && isReaderWord(words[k + 1] ?? null) ? starts : null;
   }
   if (!COMMAND_WRAPPERS.has(name) && !RUNNER_WRAPPERS.has(name)) return null;
   const h = unwrapCommandHead(words);
@@ -3233,6 +3447,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
   const shellShaped = isBashTool(toolName) || inspectsShellCommand(toolName, config.policy.toolInspection);
   const shellShapedCommand = shellShaped ? isBashTool(toolName) && args && typeof args === "object" ? typeof args.command === "string" ? args.command : null : extractShellCommand(toolName, args, config.policy.toolInspection) : null;
   const bashCommand = agent !== "Terminal" ? shellShapedCommand : null;
+  let pendingAstReview;
   if (bashCommand !== null) {
     const pipeVerdict = pipeChainVerdict(
       bashCommand,
@@ -3244,7 +3459,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
     if (fsVerdict) {
       const isShieldRule = fsVerdict.ruleName.startsWith("shield:");
       const labelPrefix = isShieldRule ? "project-jail (AST)" : "Node9 (AST)";
-      return {
+      const astVerdict = {
         decision: fsVerdict.verdict,
         blockedByLabel: `${labelPrefix}: ${fsVerdict.ruleName}`,
         reason: fsVerdict.reason,
@@ -3252,6 +3467,8 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
         ruleName: fsVerdict.ruleName,
         ruleDescription: fsVerdict.reason
       };
+      if (fsVerdict.verdict === "block") return astVerdict;
+      pendingAstReview = astVerdict;
     }
     const sqlAction = resolveCheck(config.policy.commandChecks?.sqlDdl);
     const sqlVerdict = sqlAction === "off" ? null : analyzeSqlDestructive(bashCommand);
@@ -3294,7 +3511,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
     const matchedRule = resolvePinned(matches);
     if (matchedRule) {
       if (matchedRule.verdict === "allow")
-        return { decision: "allow", ruleName: matchedRule.name ?? matchedRule.tool };
+        return pendingAstReview ?? { decision: "allow", ruleName: matchedRule.name ?? matchedRule.tool };
       return {
         decision: matchedRule.verdict,
         blockedByLabel: `Smart Rule: ${matchedRule.name ?? matchedRule.tool}`,
@@ -3321,6 +3538,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
     allTokens = analyzed.allTokens;
     pathTokens = analyzed.paths;
     const candidates = [];
+    if (pendingAstReview) candidates.push(pendingAstReview);
     const evalVerdict = detectDangerousShellExec(shellCommand);
     if (evalVerdict === "block") {
       return {
@@ -4427,6 +4645,12 @@ function classifyRuleSeverity(name, verdict) {
     "read-ssh",
     "read-gcp",
     "read-cred",
+    // Stage 4 (2026-09-11): a copy of a credential file scores like a READ of it --
+    // read-ssh/aws/cred are critical, so copy-ssh/aws/cred are; read-env is high
+    // (below), so copy-env joins the high list, not this one (/code-review).
+    "copy-ssh",
+    "copy-aws",
+    "copy-cred",
     "delete-repo",
     "helm-uninstall",
     "drop-table",
@@ -4439,6 +4663,7 @@ function classifyRuleSeverity(name, verdict) {
   ];
   if (criticalPatterns.some((p) => n.includes(p))) return "critical";
   const highPatterns = [
+    "copy-env",
     "force-push",
     "force_push",
     "git-destructive",
@@ -4456,6 +4681,11 @@ function narrativeRuleLabel(name) {
   const map = {
     "read-aws": "AWS credentials read",
     "read-ssh": "SSH private key read",
+    // Stage 4 copy twins, so `scan --narrative` prints a label, not a raw slug.
+    "copy-ssh": "SSH private key copied out",
+    "copy-aws": "AWS credentials copied out",
+    "copy-env": ".env file copied out",
+    "copy-cred": "credential file copied out",
     "read-gcp": "GCP credentials read",
     "read-cred": "credential file read",
     "delete-repo": "GitHub repository deletion",
@@ -4853,8 +5083,8 @@ function matchCanaryArgs(args, values) {
 
 // src/scan/canonical.ts
 var LONG_OUTPUT_THRESHOLD_BYTES = 100 * 1024;
-var CANONICAL_EXTRACTOR_VERSION = "canonical-v13";
-var CANONICAL_EXTRACTOR_HASH = "4622a2f41696af04";
+var CANONICAL_EXTRACTOR_VERSION = "canonical-v14";
+var CANONICAL_EXTRACTOR_HASH = "8b5729fe236a195b";
 var DEDUPE_PREVIEW_LEN = 120;
 function extractCanonicalFindings(call, ctx) {
   const out = [];
@@ -5231,6 +5461,7 @@ var ENGINE_VERSION = "1.4.0";
   CANONICAL_EXTRACTOR_HASH,
   CANONICAL_EXTRACTOR_VERSION,
   COMMAND_WRAPPERS,
+  COPY_VERBS,
   COST_PER_LOOP_ITER_USD,
   DEFAULT_EGRESS_ALLOWLIST,
   DESTINATION_ARGS,
@@ -5300,9 +5531,11 @@ var ENGINE_VERSION = "1.4.0";
   normalizeIpLiteral,
   parseAllSshHostsFromCommand,
   parseDestHost,
+  positionedArgs,
   previewArgs,
   redactText,
   resolvePinned,
+  sampleCopyCommand,
   scanArgs,
   scanInjection,
   scanText,

package/dist/index.mjs

@@ -1312,12 +1312,56 @@ var FS_READ_TOOLS = /* @__PURE__ */ new Set([
   "nl",
   "dd"
 ]);
+var SCP_VALUE_FLAGS = ["i", "F", "o", "c", "S", "P", "J", "D", "W", "l"];
+var RSYNC_SKIP = [
+  "e",
+  "--rsh",
+  "--exclude",
+  "--exclude-from",
+  "--include",
+  "--include-from",
+  "--files-from",
+  "f",
+  "--filter"
+];
+var COPY_VERBS = {
+  cp: { source: "allButLast", targetDirFlag: true },
+  mv: { source: "allButLast", targetDirFlag: true },
+  install: { source: "allButLast", targetDirFlag: true },
+  ln: { source: "first", targetDirFlag: true },
+  scp: { source: "allButLast", skipFlags: SCP_VALUE_FLAGS },
+  rsync: { source: "allButLast", skipFlags: RSYNC_SKIP },
+  tar: {
+    source: "archive",
+    archive: "tar",
+    skipFlags: ["f", "X", "T", "--file", "--exclude", "--exclude-from", "--files-from"]
+  },
+  zip: { source: "archive", archive: "zip", skipFlags: ["x", "i", "--exclude", "--include"] },
+  ar: { source: "archive", archive: "ar" },
+  "7z": { source: "archive", archive: "7z", skipFlags: ["x", "--exclude"] },
+  gzip: { source: "all" },
+  bzip2: { source: "all" },
+  xz: { source: "all" },
+  "docker cp": { source: "allButLast" },
+  "kubectl cp": { source: "allButLast" },
+  "gsutil cp": { source: "allButLast" },
+  "gsutil rsync": { source: "allButLast" },
+  "rclone copy": { source: "allButLast" },
+  "rclone sync": { source: "allButLast" },
+  "aws s3 cp": { source: "allButLast" },
+  "aws s3 mv": { source: "allButLast" },
+  "aws s3 sync": { source: "allButLast" },
+  "gcloud storage cp": { source: "allButLast" },
+  "az storage blob upload": { source: "flagOperand", sourceFlags: ["f", "--file"] }
+};
+var TAR_MODE_WORD = /^[a-zA-Z]+$/;
+var COPY_VERB_HEADS = new Set(Object.keys(COPY_VERBS).map((k) => k.split(" ")[0]));
 var FS_OP_PRESCREEN_RE = new RegExp(
   // A quote is a separator too: `eval "cat X"` and `sh -c 'cat X'` put the
   // reader right after `"` / `'`, and without these two characters the
   // prescreen rejected every string-wrapped read before the parser ran.
   // Found 2026-09-11 by instrumenting the walk -- no CallExpr was ever visited.
-  `(?:^|[\\s|;&("'\`\\n])(?:rm|${[...FS_READ_TOOLS].map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b|(?<!<)<(?!<)`
+  `(?:^|[\\s|;&("'\`\\n/])(?:rm|${[...FS_READ_TOOLS, ...COPY_VERB_HEADS].map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b|(?<!<)<(?!<)`
 );
 var HOME_CACHE_ALLOWLIST = [
   ".cache",
@@ -1752,20 +1796,32 @@ function isProtectedHomePath(rawPath) {
   }
   return true;
 }
-function extractLiteralArgs(callExpr) {
-  const args = callExpr.Args || [];
-  if (args.length === 0) return { name: "", flags: [], paths: [], words: [] };
-  const words = args.map((a) => resolveWordLiteral(a));
-  const name = (words[0] ?? "").toLowerCase();
-  const flags = [];
-  const paths = [];
-  for (let i = 1; i < words.length; i++) {
+function positionedArgs(words, from = 1, to = words.length) {
+  const out = [];
+  let afterFlag = null;
+  for (let i = from; i < to; i++) {
     const v = words[i];
-    if (v === null) continue;
-    if (v.startsWith("-")) flags.push(v);
-    else paths.push(v);
+    if (v === null) {
+      afterFlag = null;
+      continue;
+    }
+    if (v.startsWith("-")) {
+      afterFlag = v;
+      continue;
+    }
+    out.push({ value: v, index: out.length, argv: i, afterFlag });
+    afterFlag = null;
   }
-  return { name, flags, paths, words };
+  return out;
+}
+function extractLiteralArgs(callExpr) {
+  const rawArgs = callExpr.Args || [];
+  if (rawArgs.length === 0) return { name: "", flags: [], paths: [], words: [], args: [] };
+  const words = rawArgs.map((a) => resolveWordLiteral(a));
+  const name = baseWord(words[0]);
+  const flags = words.slice(1).filter((w) => w !== null && w.startsWith("-"));
+  const args = positionedArgs(words);
+  return { name, flags, paths: args.map((a) => a.value), words, args };
 }
 var NET_BINARIES = /* @__PURE__ */ new Set([
   "curl",
@@ -2189,6 +2245,9 @@ function analyzeFsOperationImpl(command, depth = 0) {
           if (result?.verdict === "block") return false;
         }
       }
+      for (const p of copySourcePaths(words)) {
+        result = stricter(result, copyVerdictOf(matchSensitivePath2(p)));
+      }
       return true;
     });
     return result;
@@ -2201,6 +2260,157 @@ function stricter(a, b) {
   if (!b) return a;
   return b.verdict === "block" && a.verdict !== "block" ? b : a;
 }
+function flagInfo(w) {
+  if (w.startsWith("--")) {
+    const eq = w.indexOf("=");
+    return eq < 0 ? { letter: null, long: w, attached: null } : { letter: null, long: w.slice(0, eq), attached: w.slice(eq + 1) };
+  }
+  const m = /^-([a-zA-Z]+)(.*)$/.exec(w);
+  if (!m) return { letter: null, long: null, attached: null };
+  return { letter: m[1][m[1].length - 1], long: null, attached: m[2] === "" ? null : m[2] };
+}
+function flagIs(w, names) {
+  if (w === null) return false;
+  const f = flagInfo(w);
+  return names.some((n) => n.startsWith("--") ? f.long === n : f.letter === n);
+}
+function operandOf(a, names) {
+  if (!names || a.afterFlag === null) return false;
+  return flagIs(a.afterFlag, names) && flagInfo(a.afterFlag).attached === null;
+}
+function resolveCopyShape(words, h) {
+  const verb = baseWord(words[h]);
+  if (!verb) return null;
+  const direct = COPY_VERBS[verb];
+  if (direct) return { shape: direct, last: h };
+  const slots = positionedArgs(words, h + 1);
+  for (let i = 0; i < slots.length; i++) {
+    for (let n = 3; n >= 1; n--) {
+      const part = slots.slice(i, i + n);
+      if (part.length < n) continue;
+      const key = [verb, ...part.map((a) => a.value.toLowerCase())].join(" ");
+      const shape = COPY_VERBS[key];
+      if (shape) return { shape, last: part[n - 1].argv };
+    }
+    if (slots[i].afterFlag === null) return null;
+  }
+  return null;
+}
+var FIND_OPTIONS = /* @__PURE__ */ new Set(["-H", "-L", "-P"]);
+function findStartPoints(words, h) {
+  const k = words.findIndex((w, i) => i > h && w !== null && FIND_EXEC_FLAGS.has(w));
+  if (k < 0) return { k, starts: [] };
+  const firstPredicate = words.findIndex(
+    (w, i) => i > h && w !== null && w.startsWith("-") && !FIND_OPTIONS.has(w)
+  );
+  const end = firstPredicate > h ? firstPredicate : k;
+  return { k, starts: positionalAfter(words, h + 1, end) };
+}
+function copySourcePaths(words) {
+  const h = unwrapCommandHead(words);
+  const fi = words.findIndex((w, i) => i <= h && baseWord(w) === "find");
+  if (fi >= 0) {
+    const { k, starts } = findStartPoints(words, fi);
+    if (k < 0) return [];
+    const action = unwrapCommandHead(words.slice(k + 1));
+    return resolveCopyShape(words.slice(k + 1), action) ? starts : [];
+  }
+  if (!COPY_VERB_HEADS.has(baseWord(words[h]))) return [];
+  const r = resolveCopyShape(words, h);
+  if (!r) return [];
+  const { shape, last } = r;
+  const args = positionedArgs(words, last + 1);
+  const tail = words.slice(last + 1);
+  const skipped = (a) => operandOf(a, shape.skipFlags);
+  const targetDir = shape.targetDirFlag === true && tail.some((w) => w !== null && w.startsWith("-") && flagIs(w, ["t", "--target-directory"]));
+  const targetOperand = (a) => targetDir && operandOf(a, ["t", "--target-directory"]);
+  const lastOperand = [...tail].reverse().find((w) => w === null || !w.startsWith("-"));
+  const dynamicDest = lastOperand === null;
+  const destIsLastOperand = (shape.source === "allButLast" || shape.source === "first") && !targetDir && !dynamicDest;
+  if (destIsLastOperand && typeof lastOperand === "string" && matchSensitivePath2(lastOperand))
+    return [];
+  let src;
+  switch (shape.source) {
+    case "all":
+      src = args;
+      break;
+    case "first":
+      src = targetDir ? args : args.slice(0, 1);
+      break;
+    case "flagOperand": {
+      const inline = tail.filter((w) => w !== null && w.startsWith("--")).map((w) => flagInfo(w)).filter((f) => f.attached !== null && (shape.sourceFlags ?? []).includes(f.long ?? "")).map((f) => f.attached);
+      return [
+        ...args.filter(
+          (a) => flagIs(a.afterFlag, shape.sourceFlags ?? []) && flagInfo(a.afterFlag).attached === null
+        ).map((a) => a.value),
+        ...inline
+      ];
+    }
+    case "archive":
+      src = archiveInputs(shape.archive, args, tail);
+      break;
+    case "allButLast":
+      src = targetDir || dynamicDest ? args : args.slice(0, -1);
+      break;
+  }
+  return src.filter((a) => !skipped(a) && !targetOperand(a)).map((a) => a.value);
+}
+function archiveInputs(kind, args, tail) {
+  const first = args[0];
+  const bareKey = first && first.afterFlag === null && TAR_MODE_WORD.test(first.value);
+  if (kind === "tar") {
+    const flagsText = tail.filter((w) => w !== null && w.startsWith("-")).join(" ");
+    const mode = (bareKey ? first.value : "") + flagsText;
+    const extracting = /x|t/.test(bareKey ? first.value.replace(/f/g, "") : "") || /(^|\s)-[a-zA-Z]*[xt]|--extract|--list|--get/.test(flagsText);
+    const writing = /[cruA]/.test(bareKey ? first.value : "") || /(^|\s)-[a-zA-Z]*[cruA]|--create|--append|--update|--concatenate/.test(flagsText);
+    if (extracting && !writing) return [];
+    void mode;
+    let i = 0;
+    if (bareKey) {
+      i = 1;
+      const next = args[1];
+      if (first.value.includes("f") && next && next.afterFlag === null) i = 2;
+    }
+    return args.slice(i);
+  }
+  if (kind === "zip") return first && first.afterFlag === "-" ? args : args.slice(1);
+  if (kind === "ar") return bareKey ? args.slice(2) : args.slice(1);
+  return args.slice(2);
+}
+function sampleCopyCommand(verb, src) {
+  const shape = COPY_VERBS[verb];
+  if (!shape) throw new Error(`not a copy verb: ${verb}`);
+  const remote = /^(scp|rsync|aws |gsutil|gcloud|rclone|docker|kubectl)/.test(verb);
+  switch (shape.source) {
+    case "first":
+      return `${verb} -s ${src} /tmp/n9-link`;
+    case "all":
+      return `${verb} -c ${src} > /tmp/n9-out`;
+    case "flagOperand":
+      return `${verb} -f ${src} -c n9`;
+    case "archive":
+      return shape.archive === "tar" ? `tar czf /tmp/n9-out.tgz ${src}` : shape.archive === "zip" ? `zip -r /tmp/n9-out.zip ${src}` : shape.archive === "ar" ? `ar rc /tmp/n9-out.a ${src}` : `7z a /tmp/n9-out.7z ${src}`;
+    case "allButLast":
+      return `${verb} ${src} ${remote ? verb.startsWith("scp") || verb === "rsync" ? "user@host.invalid:/tmp/" : verb.startsWith("docker") || verb.startsWith("kubectl") ? "ctr:/tmp/" : "remote:/n9/" : "/tmp/n9-copy"}`;
+  }
+}
+var COPY_RULE_OF = {
+  "shield:project-jail:block-read-ssh": "shield:project-jail:review-copy-ssh",
+  "shield:project-jail:block-read-aws": "shield:project-jail:review-copy-aws",
+  "shield:project-jail:block-read-env": "shield:project-jail:review-copy-env",
+  "shield:project-jail:review-read-credentials": "shield:project-jail:review-copy-credentials"
+};
+function copyVerdictOf(hit) {
+  if (!hit) return null;
+  const ruleName = COPY_RULE_OF[hit.ruleName];
+  if (!ruleName) return null;
+  return {
+    ruleName,
+    verdict: "review",
+    reason: `Copying ${hit.path} moves a credential out of its jail (project-jail shield)`,
+    path: hit.path
+  };
+}
 function matchSensitivePath2(p) {
   for (const sp of SENSITIVE_PATH_RULES) {
     if (sp.match(p))
@@ -2208,14 +2418,15 @@ function matchSensitivePath2(p) {
   }
   return null;
 }
-var isReaderWord = (w) => w !== null && FS_READ_TOOLS.has(w.split("/").pop()?.toLowerCase() ?? "");
-var positionalAfter = (words, from, to = words.length) => words.slice(from, to).filter((w) => w !== null && !w.startsWith("-"));
+function baseWord(w) {
+  return (w ?? "").split("/").pop()?.toLowerCase() ?? "";
+}
+var isReaderWord = (w) => w !== null && FS_READ_TOOLS.has(baseWord(w));
+var positionalAfter = (words, from, to = words.length) => positionedArgs(words, from, to).map((a) => a.value);
 function wrappedReadPaths(words, name) {
   if (name === "find") {
-    const k = words.findIndex((w) => w !== null && FIND_EXEC_FLAGS.has(w));
-    if (k < 1 || !isReaderWord(words[k + 1] ?? null)) return null;
-    const firstPredicate = words.findIndex((w, i) => i > 0 && w !== null && w.startsWith("-"));
-    return positionalAfter(words, 1, firstPredicate > 0 ? firstPredicate : k);
+    const { k, starts } = findStartPoints(words, 0);
+    return k > 0 && isReaderWord(words[k + 1] ?? null) ? starts : null;
   }
   if (!COMMAND_WRAPPERS.has(name) && !RUNNER_WRAPPERS.has(name)) return null;
   const h = unwrapCommandHead(words);
@@ -3103,6 +3314,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
   const shellShaped = isBashTool(toolName) || inspectsShellCommand(toolName, config.policy.toolInspection);
   const shellShapedCommand = shellShaped ? isBashTool(toolName) && args && typeof args === "object" ? typeof args.command === "string" ? args.command : null : extractShellCommand(toolName, args, config.policy.toolInspection) : null;
   const bashCommand = agent !== "Terminal" ? shellShapedCommand : null;
+  let pendingAstReview;
   if (bashCommand !== null) {
     const pipeVerdict = pipeChainVerdict(
       bashCommand,
@@ -3114,7 +3326,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
     if (fsVerdict) {
       const isShieldRule = fsVerdict.ruleName.startsWith("shield:");
       const labelPrefix = isShieldRule ? "project-jail (AST)" : "Node9 (AST)";
-      return {
+      const astVerdict = {
         decision: fsVerdict.verdict,
         blockedByLabel: `${labelPrefix}: ${fsVerdict.ruleName}`,
         reason: fsVerdict.reason,
@@ -3122,6 +3334,8 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
         ruleName: fsVerdict.ruleName,
         ruleDescription: fsVerdict.reason
       };
+      if (fsVerdict.verdict === "block") return astVerdict;
+      pendingAstReview = astVerdict;
     }
     const sqlAction = resolveCheck(config.policy.commandChecks?.sqlDdl);
     const sqlVerdict = sqlAction === "off" ? null : analyzeSqlDestructive(bashCommand);
@@ -3164,7 +3378,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
     const matchedRule = resolvePinned(matches);
     if (matchedRule) {
       if (matchedRule.verdict === "allow")
-        return { decision: "allow", ruleName: matchedRule.name ?? matchedRule.tool };
+        return pendingAstReview ?? { decision: "allow", ruleName: matchedRule.name ?? matchedRule.tool };
       return {
         decision: matchedRule.verdict,
         blockedByLabel: `Smart Rule: ${matchedRule.name ?? matchedRule.tool}`,
@@ -3191,6 +3405,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
     allTokens = analyzed.allTokens;
     pathTokens = analyzed.paths;
     const candidates = [];
+    if (pendingAstReview) candidates.push(pendingAstReview);
     const evalVerdict = detectDangerousShellExec(shellCommand);
     if (evalVerdict === "block") {
       return {
@@ -4297,6 +4512,12 @@ function classifyRuleSeverity(name, verdict) {
     "read-ssh",
     "read-gcp",
     "read-cred",
+    // Stage 4 (2026-09-11): a copy of a credential file scores like a READ of it --
+    // read-ssh/aws/cred are critical, so copy-ssh/aws/cred are; read-env is high
+    // (below), so copy-env joins the high list, not this one (/code-review).
+    "copy-ssh",
+    "copy-aws",
+    "copy-cred",
     "delete-repo",
     "helm-uninstall",
     "drop-table",
@@ -4309,6 +4530,7 @@ function classifyRuleSeverity(name, verdict) {
   ];
   if (criticalPatterns.some((p) => n.includes(p))) return "critical";
   const highPatterns = [
+    "copy-env",
     "force-push",
     "force_push",
     "git-destructive",
@@ -4326,6 +4548,11 @@ function narrativeRuleLabel(name) {
   const map = {
     "read-aws": "AWS credentials read",
     "read-ssh": "SSH private key read",
+    // Stage 4 copy twins, so `scan --narrative` prints a label, not a raw slug.
+    "copy-ssh": "SSH private key copied out",
+    "copy-aws": "AWS credentials copied out",
+    "copy-env": ".env file copied out",
+    "copy-cred": "credential file copied out",
     "read-gcp": "GCP credentials read",
     "read-cred": "credential file read",
     "delete-repo": "GitHub repository deletion",
@@ -4723,8 +4950,8 @@ function matchCanaryArgs(args, values) {
 
 // src/scan/canonical.ts
 var LONG_OUTPUT_THRESHOLD_BYTES = 100 * 1024;
-var CANONICAL_EXTRACTOR_VERSION = "canonical-v13";
-var CANONICAL_EXTRACTOR_HASH = "4622a2f41696af04";
+var CANONICAL_EXTRACTOR_VERSION = "canonical-v14";
+var CANONICAL_EXTRACTOR_HASH = "8b5729fe236a195b";
 var DEDUPE_PREVIEW_LEN = 120;
 function extractCanonicalFindings(call, ctx) {
   const out = [];
@@ -5100,6 +5327,7 @@ export {
   CANONICAL_EXTRACTOR_HASH,
   CANONICAL_EXTRACTOR_VERSION,
   COMMAND_WRAPPERS,
+  COPY_VERBS,
   COST_PER_LOOP_ITER_USD,
   DEFAULT_EGRESS_ALLOWLIST,
   DESTINATION_ARGS,
@@ -5169,9 +5397,11 @@ export {
   normalizeIpLiteral,
   parseAllSshHostsFromCommand,
   parseDestHost,
+  positionedArgs,
   previewArgs,
   redactText,
   resolvePinned,
+  sampleCopyCommand,
   scanArgs,
   scanInjection,
   scanText,

package/package.json

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