@occasiolabs/occasio 0.8.1

package/src/anomaly/cli.js

@@ -0,0 +1,143 @@
+'use strict';
+
+/**
+ * anomaly/cli.js — `occasio anomalies`
+ *
+ * Usage:
+ *   occasio anomalies                       Run all detectors over the last 15 min
+ *   occasio anomalies --window 5m           Override window size (s/m/h suffixes)
+ *   occasio anomalies --json                Machine-readable output
+ *   occasio anomalies --since <ISO>         Pin the "now" anchor (testing)
+ *   occasio anomalies --chain <path>        Override chain file
+ *
+ * Exit codes:
+ *   0  no alerts
+ *   1  alerts present (low only)
+ *   2  alerts present including medium/high
+ */
+
+const { runDetectors, DEFAULT_CHAIN, DEFAULT_WINDOW_MS } = require('./index');
+
+const C = {
+  r:  s => `\x1b[31m${s}\x1b[0m`,
+  y:  s => `\x1b[33m${s}\x1b[0m`,
+  g:  s => `\x1b[32m${s}\x1b[0m`,
+  c:  s => `\x1b[36m${s}\x1b[0m`,
+  d:  s => `\x1b[2m${s}\x1b[0m`,
+  b:  s => `\x1b[1m${s}\x1b[0m`,
+};
+
+const SEV_COLOR = { high: C.r, medium: C.y, low: C.c };
+const SEV_RANK  = { high: 3, medium: 2, low: 1 };
+
+function parseWindow(spec) {
+  if (!spec) return DEFAULT_WINDOW_MS;
+  const m = String(spec).trim().match(/^(\d+)\s*([smh]?)$/i);
+  if (!m) return DEFAULT_WINDOW_MS;
+  const n = parseInt(m[1], 10);
+  const unit = (m[2] || 'm').toLowerCase();
+  const mult = unit === 's' ? 1000 : unit === 'h' ? 3600_000 : 60_000;
+  return n * mult;
+}
+
+function flag(args, name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+function bool(args, name) { return args.indexOf(name) >= 0; }
+
+function runAnomaliesCli(args = []) {
+  if (bool(args, '--help') || bool(args, '-h')) {
+    process.stdout.write(
+      'Usage:\n' +
+      '  occasio anomalies [--window 15m] [--since <ISO>] [--chain <path>] [--json]\n' +
+      '\n' +
+      'Detectors:\n' +
+      '  deny-rate           BLOCK rate spike vs historical baseline\n' +
+      '  file-read-volume    Distinct files-read burst (recon pattern)\n' +
+      '  unknown-tool-input  Previously-unseen tool_inputs shape\n' +
+      '  secret-redact-rate  Secret-redaction count vs historical baseline\n'
+    );
+    return 0;
+  }
+
+  const windowMs = parseWindow(flag(args, '--window'));
+  const since    = flag(args, '--since');
+  const chain    = flag(args, '--chain') || DEFAULT_CHAIN;
+  const asJson   = bool(args, '--json');
+
+  const result = runDetectors({ chainFile: chain, windowMs, now: since });
+
+  if (asJson) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    renderHuman(result, windowMs);
+  }
+
+  // Exit code reflects worst alert severity. Detector errors are
+  // a separate signal — exit code 3 dedicated to "the EDR layer
+  // itself is broken", so CI can distinguish "everything OK" from
+  // "an alert fired" from "the detector failed before it could decide".
+  const errCount = (result.errors || []).length;
+  if (result.alerts.length === 0) {
+    return errCount > 0 ? 3 : 0;
+  }
+  const worst = result.alerts.reduce(
+    (m, a) => Math.max(m, SEV_RANK[a.severity] || 0), 0);
+  // Errors take precedence over low/medium alerts: a broken
+  // detector means we cannot trust the absence of higher-severity
+  // findings either.
+  if (errCount > 0 && worst < 2) return 3;
+  return worst >= 2 ? 2 : 1;
+}
+
+function renderHuman(result, windowMs) {
+  const winLabel = humanDuration(windowMs);
+  process.stdout.write(
+    `${C.b('occasio anomalies')}  ${C.d('window=' + winLabel + ', ' +
+       result.window_rows + ' rows in window, ' +
+       result.history_rows + ' historical)')}\n\n`);
+
+  const errs = result.errors || [];
+
+  if (result.alerts.length === 0 && errs.length === 0) {
+    process.stdout.write(`  ${C.g('✓')} no anomalies in the current window\n\n`);
+    return;
+  }
+
+  // Sort alerts high→low so worst is visible first.
+  const sorted = [...result.alerts].sort(
+    (a, b) => (SEV_RANK[b.severity] || 0) - (SEV_RANK[a.severity] || 0));
+  for (const a of sorted) {
+    const color = SEV_COLOR[a.severity] || C.d;
+    const sev   = color(`[${a.severity.toUpperCase()}]`);
+    process.stdout.write(`  ${sev} ${C.b(a.detector_id)} — ${a.message}\n`);
+    if (a.rows_implicated.length) {
+      const sample = a.rows_implicated[0];
+      process.stdout.write(`         ${C.d('implicated rows: ' + sample.slice(0,12) +
+        '…  (+' + (a.rows_implicated.length - 1) + ' more)')}\n`);
+    }
+  }
+
+  // Errors render separately so reviewers know to escalate to engineering,
+  // not to compliance. A crashed detector is a code defect, not a finding.
+  if (errs.length > 0) {
+    if (result.alerts.length > 0) process.stdout.write('\n');
+    process.stdout.write(`  ${C.r('!')} ${errs.length} detector(s) crashed — investigate as a bug, not a finding:\n`);
+    for (const e of errs) {
+      process.stdout.write(`     ${C.b(e.detector_id)}: ${e.error}\n`);
+    }
+  }
+
+  process.stdout.write('\n');
+  process.stdout.write(
+    `  ${C.d('Tip: `occasio replay --run <id>` to see the run that produced an implicated row.')}\n\n`);
+}
+
+function humanDuration(ms) {
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
+  if (ms < 3600_000) return `${Math.round(ms / 60_000)}m`;
+  return `${(ms / 3600_000).toFixed(1)}h`;
+}
+
+module.exports = { runAnomaliesCli, parseWindow, humanDuration };

package/src/anomaly/detectors/deny-rate.js

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * deny-rate — alert when the BLOCK rate in the window is materially higher
+ * than the historical BLOCK rate.
+ *
+ * Window count vs. historical rate-per-equivalent-window. Cold start: if
+ * historical has < 100 rows, only fire when window has ≥ MIN_ABSOLUTE blocks,
+ * to avoid spurious alerts on a fresh chain.
+ */
+
+const ID    = 'deny-rate';
+const LABEL = 'Deny rate spike';
+
+const MIN_ABSOLUTE          = 5;    // window must contain at least this many BLOCKs
+const MULTIPLIER_THRESHOLD  = 3.0;  // window rate >= baseline_rate × this
+const COLD_START_MIN_HISTORY = 100;
+
+function countBlocks(rows) {
+  let n = 0;
+  for (const r of rows) if (r.action === 'BLOCK') n++;
+  return n;
+}
+
+function evaluate(windowRows, historicalRows, opts) {
+  const winBlocks = countBlocks(windowRows);
+  if (winBlocks < MIN_ABSOLUTE) return [];
+
+  const winMs = opts.windowMs || 0;
+  if (winMs <= 0) return [];
+
+  // Historical rate: BLOCKs / (history span in ms) × winMs
+  if (historicalRows.length < COLD_START_MIN_HISTORY) {
+    // Cold start: only fire when window has a lot of blocks AND the
+    // overall window proportion is anomalously high. Avoids spurious
+    // alerts on a brand-new install.
+    const winRate = windowRows.length ? winBlocks / windowRows.length : 0;
+    if (winRate < 0.5) return [];
+    return [{
+      severity: 'medium',
+      observed: winBlocks,
+      baseline: 0,
+      message: `BLOCK count ${winBlocks} in current window (cold-start: no historical baseline yet, but ${(winRate * 100).toFixed(0)}% of window rows are blocked)`,
+      rows_implicated: implicatedHashes(windowRows),
+    }];
+  }
+
+  const histBlocks = countBlocks(historicalRows);
+  const firstTs = Date.parse(historicalRows[0]?.ts);
+  const lastTs  = Date.parse(historicalRows[historicalRows.length - 1]?.ts);
+  if (!Number.isFinite(firstTs) || !Number.isFinite(lastTs) || lastTs <= firstTs) return [];
+
+  const histSpanMs = lastTs - firstTs;
+  const histRatePerWindow = (histBlocks / histSpanMs) * winMs;
+  if (histRatePerWindow <= 0) {
+    return [{
+      severity: 'high',
+      observed: winBlocks,
+      baseline: 0,
+      message: `${winBlocks} BLOCKs in current window; historical baseline shows none — possible new attack pattern or policy change`,
+      rows_implicated: implicatedHashes(windowRows),
+    }];
+  }
+
+  const ratio = winBlocks / histRatePerWindow;
+  if (ratio < MULTIPLIER_THRESHOLD) return [];
+
+  const severity = ratio > 10 ? 'high' : 'medium';
+  return [{
+    severity,
+    observed: winBlocks,
+    baseline: Number(histRatePerWindow.toFixed(2)),
+    message: `BLOCK rate ${winBlocks} in current window vs. historical ${histRatePerWindow.toFixed(2)}/window (×${ratio.toFixed(1)})`,
+    rows_implicated: implicatedHashes(windowRows),
+  }];
+}
+
+function implicatedHashes(rows) {
+  return rows.filter(r => r.action === 'BLOCK' && typeof r.hash === 'string')
+             .slice(0, 5)
+             .map(r => r.hash);
+}
+
+module.exports = { id: ID, label: LABEL, evaluate };

package/src/anomaly/detectors/file-read-volume.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * file-read-volume — alert when the count of distinct files read in the
+ * window exceeds the per-window historical p95 by a configurable multiplier.
+ *
+ * Catches recon-style bursts where an agent suddenly reads dozens of files
+ * it has never touched. Uses **distinct** paths (not total reads) to avoid
+ * false positives from a single re-read loop.
+ */
+
+const ID    = 'file-read-volume';
+const LABEL = 'File-read volume spike';
+
+const MIN_ABSOLUTE        = 20;   // window must read at least this many distinct paths
+const P95_MULTIPLIER      = 1.5;  // window > p95 × this
+const COLD_START_MIN_RUNS = 5;    // need ≥ this many historical windows to compute p95
+
+function readTool(row) {
+  const t = String(row.tool_name || '').toLowerCase();
+  return t === 'read' || t === 'read_file';
+}
+
+function pathOf(row) {
+  return row.tool_inputs && (row.tool_inputs.path || row.tool_inputs.file_path) || null;
+}
+
+function distinctReadPaths(rows) {
+  const s = new Set();
+  for (const r of rows) {
+    if (!readTool(r)) continue;
+    const p = pathOf(r);
+    if (p) s.add(p);
+  }
+  return s;
+}
+
+// Build a p95 of "distinct read-paths per equivalent window" from history,
+// by splitting historical rows into N consecutive windows of size windowMs.
+function historicalDistinctP95(historicalRows, windowMs) {
+  if (!historicalRows.length) return { p95: 0, samples: 0 };
+  const first = Date.parse(historicalRows[0].ts);
+  const last  = Date.parse(historicalRows[historicalRows.length - 1].ts);
+  if (!Number.isFinite(first) || !Number.isFinite(last) || last <= first) {
+    return { p95: 0, samples: 0 };
+  }
+
+  const buckets = new Map();   // bucketIdx → Set<path>
+  for (const r of historicalRows) {
+    if (!readTool(r)) continue;
+    const p = pathOf(r);
+    if (!p) continue;
+    const t = Date.parse(r.ts);
+    if (!Number.isFinite(t)) continue;
+    const idx = Math.floor((t - first) / windowMs);
+    if (!buckets.has(idx)) buckets.set(idx, new Set());
+    buckets.get(idx).add(p);
+  }
+
+  const counts = Array.from(buckets.values()).map(s => s.size);
+  if (counts.length < COLD_START_MIN_RUNS) return { p95: 0, samples: counts.length };
+
+  counts.sort((a, b) => a - b);
+  const i95 = Math.min(counts.length - 1, Math.floor(counts.length * 0.95));
+  return { p95: counts[i95], samples: counts.length };
+}
+
+function evaluate(windowRows, historicalRows, opts) {
+  const winSet = distinctReadPaths(windowRows);
+  if (winSet.size < MIN_ABSOLUTE) return [];
+
+  const winMs = opts.windowMs || 0;
+  if (winMs <= 0) return [];
+
+  const { p95, samples } = historicalDistinctP95(historicalRows, winMs);
+  if (samples < COLD_START_MIN_RUNS) {
+    // Cold start fallback: fire only on very large bursts so we never
+    // alarm on a normal first session.
+    if (winSet.size < MIN_ABSOLUTE * 3) return [];
+    return [{
+      severity: 'medium',
+      observed: winSet.size,
+      baseline: null,
+      message: `${winSet.size} distinct files read in current window (cold-start: not enough historical windows yet to compute p95)`,
+      rows_implicated: firstReadHashes(windowRows),
+    }];
+  }
+
+  if (p95 === 0) return [];
+  if (winSet.size < p95 * P95_MULTIPLIER) return [];
+
+  const ratio = winSet.size / Math.max(p95, 1);
+  const severity = ratio > 4 ? 'high' : 'medium';
+  return [{
+    severity,
+    observed: winSet.size,
+    baseline: p95,
+    message: `${winSet.size} distinct files read in current window vs. p95 ${p95} (×${ratio.toFixed(1)})`,
+    rows_implicated: firstReadHashes(windowRows),
+  }];
+}
+
+function firstReadHashes(rows) {
+  return rows.filter(r => readTool(r) && typeof r.hash === 'string')
+             .slice(0, 5)
+             .map(r => r.hash);
+}
+
+module.exports = { id: ID, label: LABEL, evaluate };

package/src/anomaly/detectors/secret-redact-rate.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * secret-redact-rate — alert when the rate of secret-redaction events in the
+ * window is materially higher than baseline. Single redactions get a low-
+ * severity alert; spikes get medium/high. A non-zero window count when
+ * history is zero gets high severity (first-time-leak signal).
+ *
+ * `secrets_redacted` is an integer count on tool-call rows when the result
+ * carried redacted secrets. Any row with `secrets_redacted >= 1` counts.
+ */
+
+const ID    = 'secret-redact-rate';
+const LABEL = 'Secret-redaction rate';
+
+const MIN_HISTORY_FOR_RATE = 200;
+const MULTIPLIER_THRESHOLD = 5.0;
+
+function sumRedactions(rows) {
+  let n = 0;
+  for (const r of rows) {
+    const v = r.secrets_redacted;
+    if (typeof v === 'number' && v > 0) n += v;
+  }
+  return n;
+}
+
+function rowsWithRedactions(rows) {
+  const out = [];
+  for (const r of rows) {
+    if (typeof r.secrets_redacted === 'number' && r.secrets_redacted > 0) out.push(r);
+  }
+  return out;
+}
+
+function evaluate(windowRows, historicalRows, opts) {
+  const winRows = rowsWithRedactions(windowRows);
+  const winCount = sumRedactions(winRows);
+  if (winCount === 0) return [];
+
+  const winMs = opts.windowMs || 0;
+  if (winMs <= 0) return [];
+
+  // First-leak signal: there's redaction in the window, none in history.
+  if (historicalRows.length >= MIN_HISTORY_FOR_RATE) {
+    const histCount = sumRedactions(historicalRows);
+    if (histCount === 0) {
+      return [{
+        severity: 'high',
+        observed: winCount,
+        baseline: 0,
+        message: `${winCount} secret-redaction event(s) in current window; no historical baseline of redactions — first time we are blocking leaks from this agent/policy combination`,
+        rows_implicated: firstHashes(winRows),
+      }];
+    }
+
+    const firstTs = Date.parse(historicalRows[0].ts);
+    const lastTs  = Date.parse(historicalRows[historicalRows.length - 1].ts);
+    if (Number.isFinite(firstTs) && Number.isFinite(lastTs) && lastTs > firstTs) {
+      const histSpanMs    = lastTs - firstTs;
+      const histPerWindow = (histCount / histSpanMs) * winMs;
+      const ratio = winCount / Math.max(histPerWindow, 0.01);
+
+      if (ratio < MULTIPLIER_THRESHOLD) {
+        // Still surface non-spike redactions as low severity so reviewers
+        // see them. Compliance teams want to know about every leak attempt.
+        return [{
+          severity: 'low',
+          observed: winCount,
+          baseline: Number(histPerWindow.toFixed(2)),
+          message: `${winCount} secret-redaction event(s) in current window (baseline ${histPerWindow.toFixed(2)}/window, within normal range)`,
+          rows_implicated: firstHashes(winRows),
+        }];
+      }
+
+      const severity = ratio > 20 ? 'high' : 'medium';
+      return [{
+        severity,
+        observed: winCount,
+        baseline: Number(histPerWindow.toFixed(2)),
+        message: `${winCount} secret-redaction event(s) in current window vs. baseline ${histPerWindow.toFixed(2)}/window (×${ratio.toFixed(1)})`,
+        rows_implicated: firstHashes(winRows),
+      }];
+    }
+  }
+
+  // Cold-start: a single redaction is LOW (visible in JSON/SIEM, not loud
+  // for human review); a burst (≥ COLD_START_BURST) is MEDIUM. Calibration
+  // showed that emitting MEDIUM on every cold-start redaction produces a
+  // false-positive every coding session that touches files matching the
+  // built-in secret patterns (e.g. test fixtures, example configs). The
+  // burst threshold ensures real spikes still surface during warm-up.
+  const COLD_START_BURST = 5;
+  return [{
+    severity: winCount >= COLD_START_BURST ? 'medium' : 'low',
+    observed: winCount,
+    baseline: null,
+    message: `${winCount} secret-redaction event(s) in current window (cold-start: not enough history yet to compute baseline)`,
+    rows_implicated: firstHashes(winRows),
+  }];
+}
+
+function firstHashes(rows) {
+  return rows.filter(r => typeof r.hash === 'string').slice(0, 5).map(r => r.hash);
+}
+
+module.exports = { id: ID, label: LABEL, evaluate };

package/src/anomaly/detectors/unknown-tool-input.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * unknown-tool-input — alert when a tool is invoked with a `tool_inputs`
+ * shape (sorted-key fingerprint) that has never appeared in history.
+ *
+ * Catches "agent now passes a flag I've never seen it pass before" — e.g.
+ * a Bash call with `--privileged`, a Read with an unexpected option, a new
+ * MCP tool variant. Cold start: warm up over COLD_START_MIN_ROWS chain
+ * rows before firing.
+ */
+
+const ID    = 'unknown-tool-input';
+const LABEL = 'Unknown tool-input shape';
+
+// Calibrated against a ~3-day real audit chain (2518 rows of normal
+// coding usage). Pre-tune the detector fired 27 times in 3.2 days at
+// MEDIUM severity on benign new fingerprints (e.g. `grep` first called
+// with only a `path` key). After raising the cold-start floor and
+// dropping non-privileged novelty to LOW, the rate drops to ~1/day on
+// normal use while privileged-key novelty still fires HIGH. See
+// docs/edr-calibration.md for the run that produced these numbers.
+const COLD_START_MIN_ROWS = 200;
+// Keys that suggest privilege escalation or sandbox escape — novelty on
+// these is escalated to HIGH. Everything else: LOW (logged but not loud).
+const PRIVILEGED_KEY_RE = /\b(env|privileged|sudo|raw|exec|eval|stdin|cap|caps|seccomp)\b/;
+
+// Fingerprint = `${tool_name}:${sorted comma-separated tool_inputs keys}`.
+// Empty inputs → `${tool_name}:`. Non-object inputs are ignored (we only
+// fingerprint shape, not values).
+function fingerprint(row) {
+  if (!row.tool_name) return null;
+  const inputs = row.tool_inputs;
+  let keys = '';
+  if (inputs && typeof inputs === 'object' && !Array.isArray(inputs)) {
+    keys = Object.keys(inputs).filter(k => inputs[k] !== undefined).sort().join(',');
+  }
+  return `${String(row.tool_name).toLowerCase()}:${keys}`;
+}
+
+function evaluate(windowRows, historicalRows, _opts) {
+  if (historicalRows.length < COLD_START_MIN_ROWS) return [];
+
+  const knownFingerprints = new Set();
+  for (const r of historicalRows) {
+    if (r.kind && r.kind !== 'tool_call') continue;
+    const fp = fingerprint(r);
+    if (fp) knownFingerprints.add(fp);
+  }
+
+  // Group window rows by their (novel) fingerprint so we emit one alert per
+  // new shape, not one per row.
+  const byFp = new Map();
+  for (const r of windowRows) {
+    if (r.kind && r.kind !== 'tool_call') continue;
+    const fp = fingerprint(r);
+    if (!fp || knownFingerprints.has(fp)) continue;
+    if (!byFp.has(fp)) byFp.set(fp, []);
+    byFp.get(fp).push(r);
+  }
+  if (byFp.size === 0) return [];
+
+  const alerts = [];
+  for (const [fp, rows] of byFp) {
+    const [toolName, keysJoined] = fp.split(':');
+    const keysDisplay = keysJoined ? `{${keysJoined}}` : '{}';
+    // Privileged-key novelty is loud (HIGH). Everything else is LOW
+    // — visible in JSON/SIEM consumers but not noisy for human review.
+    // Calibration showed MEDIUM on non-privileged novelty was the
+    // largest source of false positives on normal usage.
+    const high = PRIVILEGED_KEY_RE.test(keysJoined);
+    alerts.push({
+      severity: high ? 'high' : 'low',
+      observed: rows.length,
+      baseline: 0,
+      message: `Tool '${toolName}' invoked with previously-unseen input shape ${keysDisplay} (${rows.length}× in current window)`,
+      rows_implicated: rows.filter(r => typeof r.hash === 'string').slice(0, 5).map(r => r.hash),
+    });
+  }
+  return alerts;
+}
+
+module.exports = { id: ID, label: LABEL, evaluate, _fingerprint: fingerprint };