@node9/policy-engine 1.0.0 → 1.4.0

package/dist/index.d.mts

@@ -313,7 +313,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 +410,328 @@ 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;
+
 /** 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 { type AuditEntryForClassify, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, COST_PER_LOOP_ITER_USD, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, FLAGS_WITH_VALUES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type Severity, type ShellCommandAnalysis, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallRecord, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, detectDangerousEval, detectDangerousShellExec, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractNetworkTargets, extractPositionalArgs, getCompiledRegex, getNestedValue, isIgnoredTool, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, redactText, scanArgs, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };

package/dist/index.d.ts

@@ -313,7 +313,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 +410,328 @@ 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;
+
 /** 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 { type AuditEntryForClassify, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, COST_PER_LOOP_ITER_USD, DLP_PATTERNS, type DlpMatch, ENGINE_VERSION, FLAGS_WITH_VALUES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type ProvenanceLookup, type ProvenanceTrust, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_REGEXES, type ScanFinding, type ScanSignals, type ScanSummary, type ScoreTier, type Severity, type ShellCommandAnalysis, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type ToolCallRecord, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, detectDangerousEval, detectDangerousShellExec, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractNetworkTargets, extractPositionalArgs, getCompiledRegex, getNestedValue, isIgnoredTool, isShieldVerdict, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, parseAllSshHostsFromCommand, redactText, scanArgs, scanText, sensitivePathMatch, summarizeBlast, summarizeScan, truncateBlastPath, validateOverrides, validateRegex, validateShieldDefinition };