src/anomaly.ts

Functions

Imports

It imports src/time.ts, src/watcher-detect.ts. Imported by src/watcher-gather.ts.

Source

1import type { Finding } from "./watcher-detect";
2import { HOUR_MS } from "./time";
3
4// ANOMALY RULES ON THE AUDIT LOG (OWASP agentic hardening item 6, ASI10;
5// capsid/research/design-owasp-hardening.md; Dustin's D4 of 2026-10-03: a hit is a watcher
6// finding plus a Portal attention item, nothing more. No suspension and no revoke: that
7// is re-decided after two weeks of measured false positives. D5 dropped the path rule.)
8//
9// Per minted agent (actor "agent:<name>", the watcher itself excepted), the last 24 hours
10// against the 14 days before them, from audit_log counted per actor, action and hour:
11//   - a new action: an action the agent wrote in the last day and never in its baseline.
12//     An agent with no baseline at all is judged by the first-use rule instead;
13//   - a rate spike: its busiest hour in the last day over RATE_FACTOR times its busiest
14//     baseline hour, and at least RATE_FLOOR rows, so a quiet agent's second call is not
15//     a spike;
16//   - an off-hours first use: an agent with no baseline whose first row falls between
17//     00:00 and 06:00 America/Chicago.
18// The window is a day so a hit stays a finding for a day, then clears itself.
19//
20// What audit_log cannot see, it cannot judge: a read that writes no audit row is not
21// counted. The hook receiver's tool rows (session_events, PostToolUse and
22// PostToolUseFailure; Dustin's D1 of 2026-10-03 shares them with these rules) cover that,
23// on a series of their own: tool calls run at hundreds an hour, so mixed into the audit
24// read they would trip the rate rule and the new-action rule on the first day. One rule
25// reads them, toolRateFindings: the same spike test against the agent's own tool baseline,
26// at TOOL_RATE_FLOOR. There is no first-use or new-tool rule for tools, so the first day
27// of tool reporting pages nobody.
28
29const BASELINE_DAYS = 14;
30const RECENT_HOURS = 24;
31const RATE_FACTOR = 3;
32export const RATE_FLOOR = 30;
33// Tool calls come in hundreds an hour in ordinary work, so the floor is far above the
34// audit rows' 30.
35export const TOOL_RATE_FLOOR = 600;
36const OFF_HOURS_END = 6;
37
38/** One row of the grouped read: an actor's rows of one action in one UTC hour. */
39export interface ActionHour {
40  actor: string;
41  action: string;
42  // "YYYY-MM-DDTHH", UTC.
43  hour: string;
44  n: number;
45}
46
47/** The window's start for readActionHours, in audit_log's datetime format. */
48function anomalySince(now: Date): string {
49  return new Date(now.getTime() - (BASELINE_DAYS * 24 + RECENT_HOURS) * HOUR_MS).toISOString().slice(0, 19).replace("T", " ");
50}
51
52/** The read the rules run on: every minted agent's audit rows of the last BASELINE_DAYS
53 *  plus one days, grouped by action and hour, the watcher (`except`) left out. On the
54 *  audit_log_at index (migrations/0005), bounded by the window. */
55export async function readActionHours(db: D1Database, now: Date, except: string): Promise<ActionHour[]> {
56  const { results } = await db
57    .prepare(
58      `SELECT actor, action, strftime('%Y-%m-%dT%H', at) AS hour, COUNT(*) AS n
59       FROM audit_log WHERE at >= ?1 AND actor LIKE 'agent:%' AND actor <> ?2
60       GROUP BY actor, action, hour`
61    )
62    .bind(anomalySince(now), except)
63    .all<ActionHour>();
64  return results ?? [];
65}
66
67/** The window's start for readToolHours, in session_events' ISO format
68 *  (YYYY-MM-DDTHH:MM:SS.sssZ, unlike audit_log's space-separated datetime). */
69function toolSince(now: Date): string {
70  return new Date(now.getTime() - (BASELINE_DAYS * 24 + RECENT_HOURS) * HOUR_MS).toISOString();
71}
72
73/** One row of the tool read: an actor's tool calls in one UTC hour. */
74export interface ToolHour {
75  actor: string;
76  // "YYYY-MM-DDTHH", UTC.
77  hour: string;
78  n: number;
79}
80
81/** Every minted agent's tool-use rows of the last BASELINE_DAYS plus one days, counted
82 *  per actor and hour, the watcher (`except`) left out. session_events is indexed on
83 *  (session_id, id) and (job_id, id) only, so this is a scan, not an index range. It is
84 *  bounded by the 30-day prune the hook receiver runs (src/ops-hooks.ts), which keeps
85 *  the table to a month of rows; an index would need a migration and is not worth one. */
86export async function readToolHours(db: D1Database, now: Date, except: string): Promise<ToolHour[]> {
87  const { results } = await db
88    .prepare(
89      `SELECT agent AS actor, strftime('%Y-%m-%dT%H', at) AS hour, COUNT(*) AS n
90       FROM session_events
91       WHERE event IN ('PostToolUse', 'PostToolUseFailure') AND at >= ?1 AND agent LIKE 'agent:%' AND agent <> ?2
92       GROUP BY agent, hour`
93    )
94    .bind(toolSince(now), except)
95    .all<ToolHour>();
96  return results ?? [];
97}
98
99function slug(text: string): string {
100  return text.toLowerCase().replace(/^agent:/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
101}
102
103/** The hour of day in America/Chicago for a UTC hour key. */
104export function chicagoHour(hourKey: string): number {
105  const h = new Intl.DateTimeFormat("en-US", { timeZone: "America/Chicago", hour: "numeric", hourCycle: "h23" }).format(new Date(`${hourKey}:00:00Z`));
106  return Number(h) % 24;
107}
108
109const mk = (fingerprint: string, headline: string, evidence: string[]): Finding => ({
110  fingerprint,
111  namespace: "capsid",
112  title: `Watcher: ${headline} [${fingerprint}]`,
113  body: [
114    "An agent acted out of its usual pattern (OWASP item 6, anomaly rules). A finding only:",
115    "nothing was suspended or revoked (Dustin, D4 of 2026-10-03). Confirm whether the",
116    "activity was expected; if it was, fail this job saying so, which counts toward the",
117    "false-positive measure. If it was not, revoke the key with capsid_admin_manage_agents action revoke.",
118    "",
119    "## Evidence",
120    "",
121    ...evidence.map((line) => `- ${line}`),
122  ].join("\n"),
123  evidence,
124});
125
126export function anomalyFindings(rows: readonly ActionHour[], now: Date): Finding[] {
127  const recentFrom = new Date(now.getTime() - RECENT_HOURS * HOUR_MS).toISOString().slice(0, 13);
128  const byActor = new Map<string, { base: ActionHour[]; recent: ActionHour[] }>();
129  for (const r of rows) {
130    const a = byActor.get(r.actor) ?? { base: [], recent: [] };
131    (r.hour >= recentFrom ? a.recent : a.base).push(r);
132    byActor.set(r.actor, a);
133  }
134  const out: Finding[] = [];
135  for (const [actor, { base, recent }] of [...byActor].sort(([x], [y]) => x.localeCompare(y))) {
136    if (recent.length === 0) continue;
137    const perHour = (list: ActionHour[]) => {
138      const m = new Map<string, number>();
139      for (const r of list) m.set(r.hour, (m.get(r.hour) ?? 0) + r.n);
140      return m;
141    };
142    if (base.length === 0) {
143      const first = [...recent].sort((x, y) => x.hour.localeCompare(y.hour))[0];
144      const local = chicagoHour(first.hour);
145      if (local < OFF_HOURS_END) {
146        out.push(mk(`anomaly-first-use-${slug(actor)}`, `${actor} was first used at ${String(local).padStart(2, "0")}:00 Chicago time`, [`first audit row in the hour ${first.hour}:00Z (${first.action})`, `no row in the ${BASELINE_DAYS} days before`]));
147      }
148      continue;
149    }
150    const known = new Set(base.map((r) => r.action));
151    const fresh = [...new Set(recent.map((r) => r.action))].filter((a) => !known.has(a)).sort();
152    for (const action of fresh) {
153      const n = recent.filter((r) => r.action === action).reduce((s, r) => s + r.n, 0);
154      out.push(mk(`anomaly-new-action-${slug(actor)}-${slug(action)}`, `${actor} did '${action}', which it had not done in ${BASELINE_DAYS} days`, [`${n} row(s) of '${action}' in the last ${RECENT_HOURS} hours`, `its baseline actions: ${[...known].sort().join(", ")}`]));
155    }
156    const baseMax = Math.max(...perHour(base).values());
157    const [peakHour, peak] = [...perHour(recent)].sort((x, y) => y[1] - x[1])[0];
158    if (peak >= RATE_FLOOR && peak > RATE_FACTOR * baseMax) {
159      out.push(mk(`anomaly-rate-${slug(actor)}`, `${actor} wrote ${peak} audit rows in one hour, over ${RATE_FACTOR} times its busiest`, [`${peak} rows in the hour ${peakHour}:00Z`, `its busiest hour in the ${BASELINE_DAYS} days before: ${baseMax}`]));
160    }
161  }
162  return out;
163}
164
165/** The rate rule on tool calls: an agent's busiest hour in the last day over RATE_FACTOR
166 *  times its busiest baseline hour, and at least TOOL_RATE_FLOOR calls. An agent with no
167 *  tool baseline is skipped: tool reporting starts as nobody's baseline, and a first-use
168 *  rule would page for every agent on its first day. */
169export function toolRateFindings(rows: readonly ToolHour[], now: Date): Finding[] {
170  const recentFrom = new Date(now.getTime() - RECENT_HOURS * HOUR_MS).toISOString().slice(0, 13);
171  const byActor = new Map<string, { base: Map<string, number>; recent: Map<string, number> }>();
172  for (const r of rows) {
173    const a = byActor.get(r.actor) ?? { base: new Map<string, number>(), recent: new Map<string, number>() };
174    const side = r.hour >= recentFrom ? a.recent : a.base;
175    side.set(r.hour, (side.get(r.hour) ?? 0) + r.n);
176    byActor.set(r.actor, a);
177  }
178  const out: Finding[] = [];
179  for (const [actor, { base, recent }] of [...byActor].sort(([x], [y]) => x.localeCompare(y))) {
180    if (recent.size === 0 || base.size === 0) continue;
181    const baseMax = Math.max(...base.values());
182    const [peakHour, peak] = [...recent].sort((x, y) => y[1] - x[1])[0];
183    if (peak >= TOOL_RATE_FLOOR && peak > RATE_FACTOR * baseMax) {
184      out.push(mk(`anomaly-tool-rate-${slug(actor)}`, `${actor} made ${peak} tool calls in one hour, over ${RATE_FACTOR} times its busiest`, [`${peak} tool calls in the hour ${peakHour}:00Z`, `its busiest hour in the ${BASELINE_DAYS} days before: ${baseMax}`]));
185    }
186  }
187  return out;
188}