@shomra/agent 0.3.22 → 0.3.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shomra/agent",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "description": "Shomra - adversarial assurance for AI agents, as a local-first CLI. Blocks dangerous tool-calls before they run, attacks your own guardrails to prove they hold, and gates AI artifacts in your editor and CI.",
   "type": "module",
   "bin": {

package/src/detect/guard-signals.mjs

@@ -1,5 +1,6 @@
 export { autonomySeverity, localAutonomy } from './signals/autonomy.mjs';
 export { RISKY_CONFIG_MARKERS } from './signals/config-markers.mjs';
+export { classifyConsequence } from './signals/consequence.mjs';
 export { detectCredentialHarvest } from './signals/credential-harvest.mjs';
 export { claimSeverity, detectDurableClaims } from './signals/durable-claims.mjs';
 export { SUSPICIOUS_EGRESS_HOSTS, egressHost } from './signals/egress.mjs';

package/src/detect/signals/consequence.mjs

@@ -0,0 +1,56 @@
+/**
+ * How much a tool call COSTS if it is wrong - the ladder the backend grades on,
+ * mirrored here so the client can decide it OFFLINE.
+ *
+ * ⚠ THIS IS THE FAIL-CLOSED KEY. The hook fails open by design: an agent that
+ * hard-stops on an unreachable SaaS backend is one nobody keeps installed. But
+ * failing open on EVERY call means an attacker buys a bypass with a slow input
+ * or a rate limit. Grading the consequence on-machine is what lets the hook
+ * keep ordinary work flowing while still refusing a destructive call it could
+ * not get screened.
+ *
+ * ⚠ It is a MIRROR of src/modules/runtime/intent/domain/consequence.ts and must
+ * stay one - pinned by the backend's test/parity/consequence-mirror-bench.mjs.
+ * Drift here is asymmetric in the same way every other mirror is: stricter than
+ * the server blocks work no server verdict would have blocked, and looser puts
+ * a hole in the floor at exactly the moment the floor is all there is.
+ */
+const SEVERE_VERB = /\b(delete|destroy|drop|purge|revoke|terminate|shutdown|wipe|erase|truncate|force[-_]?push|rm)\b/i;
+
+const MATERIAL_VERB =
+  /\b(transfer|pay|payment|refund|charge|invoice|wire|send|email|post|publish|deploy|release|merge|approve|grant|invite|share|upload|export)\b/i;
+
+const AUTHORITY_GRANT =
+  /\b(assume|impersonate|escalate|elevate|sudo|attach|grant|bind|add|put|set|create|assign)\s+(?:\w+\s+){0,2}(role|member|policy|binding|permission|principal|group|user|iam|owner|admin|access)\b/i;
+
+const PRIVILEGED_TARGET =
+  /\b(admin|administrator|owner|owners|root|superuser|orgadmin|administratoraccess|poweruser|cluster[-_]?admin|iam:\*)\b/i;
+
+const PERSISTENCE_TARGET =
+  /(^|\/)\.(ssh|aws|kube)\/|authorized_keys|\.bashrc|\.zshrc|\.profile|crontab|\/etc\/(sudoers|passwd|shadow)|systemd|(^|\/)\.env(\.|$)/i;
+
+const PRODUCTION = /\b(prod|production|live|main|master|release)\b/i;
+
+/* ⚠ `force[-_]?push` never matched the way anybody writes it, so `git push
+ * --force origin main` graded MATERIAL and the fail-closed rung never covered
+ * it. --force-with-lease is included on purpose: it refuses when the remote
+ * moved, which makes it safer, not less destructive. */
+const FORCE_PUSH = /\bgit\s+push\b[^|;&\n]*?\s--?f(?:orce(?:-with-lease)?)?\b/i;
+
+export function classifyConsequence(input) {
+  const leaf = String(input.tool ?? '').replace(/^mcp__[^_]+__/, '');
+  const raw = `${leaf} ${input.args ?? ''}`;
+  const blob = raw.replace(/[_-]+/g, ' ').replace(/([a-z0-9])([A-Z])/g, '$1 $2');
+
+  if (typeof input.amount === 'number' && input.amount > 0) {
+    return SEVERE_VERB.test(blob) ? 'severe' : 'material';
+  }
+  if (PERSISTENCE_TARGET.test(raw)) return 'severe';
+  if (SEVERE_VERB.test(blob) || FORCE_PUSH.test(raw)) return 'severe';
+  if (AUTHORITY_GRANT.test(blob)) return PRIVILEGED_TARGET.test(blob) ? 'severe' : 'material';
+  if (input.isShell) return 'material';
+  if (MATERIAL_VERB.test(blob)) return 'material';
+  if (input.isEgress) return 'material';
+  if (input.actionId && PRODUCTION.test(blob) && MATERIAL_VERB.test(input.actionId)) return 'severe';
+  return 'routine';
+}

package/src/guard/command-resolve.mjs

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAX_LEN = 16 * 1024;
+const MAX_UNRESOLVED = 8;
+const MAX_PATH_ENTRIES = 64;
+
+const ASSIGN_PREFIX = /^\s*([A-Za-z_][A-Za-z0-9_]*)=("[^"]*"|'[^']*'|\S*)\s+/;
+const VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+const SUBST_RE = /\$\([^)]*\)|`[^`\n]*`/;
+const POSITIONAL_RE = /\$[@*#?$0-9]/;
+const INDIRECTION = /[$`]/;
+const ALIAS_OR_FUNCTION = /(?:^|[\s;&|(])(?:alias\s+[A-Za-z_][\w-]*\s*=|function\s+[A-Za-z_][\w-]*\s*(?:\(\s*\))?\s*\{|[A-Za-z_][\w-]*\s*\(\s*\)\s*\{)/;
+
+function unquote(v) {
+  const s = String(v ?? '');
+  if (s.length >= 2 && ((s[0] === '"' && s.endsWith('"')) || (s[0] === "'" && s.endsWith("'")))) return s.slice(1, -1);
+  return s;
+}
+
+function inlineAssignments(command) {
+  const vars = new Map();
+  let rest = command;
+  for (let m = ASSIGN_PREFIX.exec(rest); m; m = ASSIGN_PREFIX.exec(rest)) {
+    vars.set(m[1], unquote(m[2]));
+    rest = rest.slice(m[0].length);
+  }
+  return { vars, rest };
+}
+
+/**
+ * ⚠ A VARIABLE NOBODY DEFINED STAYS LITERAL AND IS REPORTED UNRESOLVED. Letting
+ * it fall through to the empty string is how `rm -rf $DIR/` becomes `rm -rf /`
+ * and gets screened as the second one. Absence is reported, never substituted.
+ */
+function substitute(text, vars, env, unresolved) {
+  return text.replace(VAR_RE, (whole, braced, bare) => {
+    const name = braced || bare;
+    if (vars.has(name)) return vars.get(name);
+    const fromEnv = env?.[name];
+    if (typeof fromEnv === 'string' && fromEnv.length) return fromEnv;
+    if (unresolved.length < MAX_UNRESOLVED && !unresolved.includes(whole)) unresolved.push(whole);
+    return whole;
+  });
+}
+
+function isExecutable(file, statSync) {
+  try {
+    const st = statSync(file);
+    return st.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function locate(word, effectivePath, cwd, statSync) {
+  if (!word) return null;
+  if (word.includes('/') || word.includes('\\')) {
+    const abs = path.isAbsolute(word) ? word : path.resolve(cwd || '.', word);
+    return isExecutable(abs, statSync) ? abs : null;
+  }
+  const entries = String(effectivePath ?? '').split(path.delimiter).filter(Boolean).slice(0, MAX_PATH_ENTRIES);
+  for (const dir of entries) {
+    const candidate = path.join(dir, word);
+    if (isExecutable(candidate, statSync)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * What this command's indirection points at, resolved from the environment and
+ * the filesystem this machine actually has - the two things the server does not
+ * hold and no pattern can recover from the string.
+ *
+ * ⚠⚠ IT NEVER EXECUTES ANYTHING. `$(…)` and backticks are REPORTED unresolved,
+ * never evaluated: running attacker-influenced text in order to screen it is the
+ * vulnerability, not the control. Same reason the scanner resolves an MCP source
+ * without launching it.
+ *
+ * ⚠ The result CLEARS NOTHING server-side. It is evidence the backend screens
+ * with the same detectors it ran on the literal text, and it may only ever add.
+ */
+export function resolveCommand(command, opts = {}) {
+  const cmd = typeof command === 'string' ? command.slice(0, MAX_LEN) : '';
+  if (!cmd.trim()) return null;
+
+  const env = opts.env ?? process.env;
+  const statSync = opts.statSync ?? fs.statSync;
+  const cwd = opts.cwd ?? env.PWD ?? process.cwd();
+
+  if (!INDIRECTION.test(cmd) && !ALIAS_OR_FUNCTION.test(cmd)) return null;
+
+  const unresolved = [];
+  if (SUBST_RE.test(cmd)) unresolved.push('command-substitution');
+  if (POSITIONAL_RE.test(cmd)) unresolved.push('positional-parameter');
+  if (ALIAS_OR_FUNCTION.test(cmd)) unresolved.push('alias-or-function');
+
+  const { vars, rest } = inlineAssignments(cmd);
+  const resolved = substitute(cmd, vars, env, unresolved);
+
+  const effectivePath = vars.has('PATH') ? substitute(vars.get('PATH'), vars, env, []) : env.PATH;
+  const word = substitute(rest, vars, env, []).trim().split(/\s+/)[0] ?? '';
+  const executable = SUBST_RE.test(word) || word.includes('$') ? null : locate(word, effectivePath, cwd, statSync);
+
+  if (resolved === cmd && !executable && !unresolved.length) return null;
+  return {
+    ...(resolved === cmd ? {} : { command: resolved }),
+    ...(executable ? { executable } : {}),
+    ...(unresolved.length ? { unresolved } : {}),
+  };
+}

package/src/guard/report.mjs

@@ -1,11 +1,15 @@
 import { gateMachine } from '../core/api-client.mjs';
 import { breakerOpen, breakerReset, breakerTrip, guardTimeoutMs } from '../core/circuit-breaker.mjs';
 import { detectEnv } from '../gate/environment.mjs';
+import { resolveCommand } from './command-resolve.mjs';
 
 export function buildGuardBody(norm, agent, clientDecision, clientReason) {
+  const command = norm.tool_input?.command ?? norm.tool_input?.cmd ?? norm.tool_input?.script;
+  const resolved = typeof command === 'string' ? resolveCommand(command) : null;
   return {
     tool_name: norm.tool_name,
     tool_input: norm.tool_input,
+    ...(resolved ? { resolved } : {}),
     cwd: norm.cwd,
     session_id: norm.session_id,
     ...(norm.parent_session_id ? { parent_session_id: norm.parent_session_id } : {}),

package/src/guard/tool-guard.mjs

@@ -4,8 +4,11 @@ import path from 'node:path';
 import { resolveAgentIdentityHandle } from '../commands/agent-identity.mjs';
 import { isMemoryPath, reportMemoryWrite } from '../commands/memory-scan.mjs';
 import { breakerOpen, breakerReset, breakerTrip, guardTimeoutMs } from '../core/circuit-breaker.mjs';
+import { CONFIG_DIR } from '../core/config.mjs';
+import { makeLedgerStore } from './ledger.mjs';
+import { VERSION } from '../core/version.mjs';
 import { loadConfig, resolveSettings } from '../core/config.mjs';
-import { downrankCodeContext, grade, localScan } from '../detect/guard-signals.mjs';
+import { classifyConsequence, downrankCodeContext, grade, localScan } from '../detect/guard-signals.mjs';
 import { WRITE_TOOLS, guardNeedsServer, guardTargetPath, guardText } from './classify.mjs';
 import { emitGuardAsk, emitGuardDeny } from './emit.mjs';
 import { guardPathAllowlisted } from './ignore.mjs';
@@ -16,6 +19,99 @@ import { buildGuardBody, reportGuardDecision } from './report.mjs';
 
 const ALLOW_VERDICT = { verdict: 'ALLOW', top: null, findings: [] };
 
+/**
+ * ⚠ FAILING OPEN ON EVERYTHING IS AN ENFORCEMENT BYPASS AN ATTACKER BUYS WITH A
+ * SLOW INPUT. The hook has to fail open - an agent that hard-stops on an
+ * unreachable SaaS backend is one nobody keeps installed - but "open on every
+ * call" means padding a command until the screen times out runs it unscreened,
+ * which is cheaper than any evasion in the corpus.
+ *
+ * So the rung decides. A routine or material call still flows: that is the
+ * promise that keeps the hook installed. A SEVERE one - a recursive delete, a
+ * force push over a shared branch, a write into ~/.ssh - stops and ASKS.
+ *
+ * ⚠ IT ASKS, IT DOES NOT DENY. A deny during an outage is unappealable at 3am
+ * and gets the hook uninstalled, taking every other control with it. An ask
+ * puts the human who is already sitting there in the loop and says plainly
+ * that the call was NOT screened, which is the honest sentence: we do not know
+ * that this is dangerous, we know that we could not check.
+ */
+function failOpenOnSevere() {
+  return envFlag('SHOMRA_GUARD_FAILOPEN_SEVERE');
+}
+
+function unscreenedSevere(normalized, tool, input) {
+  if (failOpenOnSevere()) return false;
+  return classifyConsequence({
+    tool,
+    args: guardText(tool, input),
+    isShell: !WRITE_TOOLS.has(tool) && typeof input?.command === 'string',
+  }) === 'severe';
+}
+
+/**
+ * ⚠⚠ THE LEDGER HAD NO PRODUCER. `guard/ledger.mjs` builds the fail-open window
+ * the backend's EnforcementGap reads - and nothing in this repo ever called
+ * `countCall`, so every client reported ZERO gaps forever. The backend then
+ * asks whether a capable reporter exists, gets silence, and the estate reads
+ * either "no outages" or NOT_ATTEMPTABLE. Both are wrong and one is flattering:
+ * a smoke detector reporting no fire with a dead battery, which is the exact
+ * shape enforcement-availability.ts was written to prevent.
+ *
+ * ⚠ COUNTS ARE LOWER BOUNDS BY DESIGN - concurrent hook processes race this
+ * file, and the backend already treats them as a floor. Do not "fix" that with
+ * a lock on the firewall's hot path.
+ */
+function ledger() {
+  return makeLedgerStore(CONFIG_DIR, { version: VERSION });
+}
+
+/** A call that ran with no server verdict: Tier-0 screened it, or nothing did. */
+function countUnscreened(reason) {
+  try {
+    ledger().count(localTierDisabled() ? 'unscreened' : 'local', reason);
+  } catch {
+    /* The ledger is a record, never a gate: a failure to write one must not
+     * take the firewall down. The count is a floor and this makes it lower. */
+  }
+}
+
+/** Close the open window and hand the backend everything not yet acknowledged. */
+function sendLedger() {
+  try {
+    const store = ledger();
+    store.close();
+    const env = store.envelope();
+    pendingLedger = env.gaps ?? [];
+    return env;
+  } catch {
+    /* No ledger is a lower bound, not a wrong number. */
+    return undefined;
+  }
+}
+
+let pendingLedger = [];
+
+function ackLedger() {
+  if (!pendingLedger.length) return;
+  try {
+    ledger().ack(pendingLedger);
+  } catch {
+    /* Unacknowledged gaps are re-sent next time; a duplicate is a floor read
+     * twice, which is safe. Losing one is not. */
+  }
+  pendingLedger = [];
+}
+
+function askUnscreened(agent, why) {
+  emitGuardAsk(
+    agent,
+    `Shomra could not screen this call (${why}), and it is a destructive one - a delete, a force push, `
+    + 'or a write to a file that survives the session. Nothing has judged it: approve it only if you meant it. '
+    + 'Set SHOMRA_GUARD_FAILOPEN_SEVERE=1 to let these through unscreened.',
+  );
+}
+
 function readHookPayload() {
   try {
     return JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
@@ -78,7 +174,7 @@ function reportUnauthenticated(agent, status, strict) {
   process.exit(0);
 }
 
-async function requestServerDecision({ url, apiKey, agentId, body, agent, strict }) {
+async function requestServerDecision({ url, apiKey, agentId, body, agent, strict, retried, onUnreachable }) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), guardTimeoutMs());
   try {
@@ -97,19 +193,48 @@ async function requestServerDecision({ url, apiKey, agentId, body, agent, strict
 
     if (!response.ok) {
       if (response.status === 401 || response.status === 403) reportUnauthenticated(agent, response.status, strict);
+      /* ⚠ A 429 IS NOT AN OUTAGE, and treating it as one was a silent
+       * enforcement bypass: tripping the breaker skips the server for the whole
+       * cooldown, so one burst past the rate limit switched org policy, agent
+       * identity and flow control off for thirty seconds - on the machine, with
+       * nothing said. It means "we are here, come back", so it is retried once
+       * against Retry-After and never counted against the breaker. */
+      if (response.status === 429) {
+        const wait = retryAfterMs(response);
+        if (wait !== null && !retried) {
+          clearTimeout(timer);
+          await sleep(wait);
+          return requestServerDecision({ url, apiKey, agentId, body, agent, strict, retried: true, onUnreachable });
+        }
+        clearTimeout(timer);
+        return onUnreachable('rate limited', { breaker: false });
+      }
       throw new Error(`HTTP ${response.status}`);
     }
     const decision = await response.json();
     breakerReset();
+    ackLedger();
     return decision;
   } catch (error) {
     clearTimeout(timer);
     breakerTrip();
     if (strict) emitGuardDeny(agent, `Shomra guard could not be reached (${error.message}); blocked by fail-closed policy.`);
-    return process.exit(0);
+    return onUnreachable(error.message, { breaker: true });
   }
 }
 
+/** Honours a seconds or an HTTP-date Retry-After; null when the server named none. */
+function retryAfterMs(response) {
+  const raw = response.headers?.get?.('retry-after');
+  if (!raw) return null;
+  const secs = Number(raw);
+  if (Number.isFinite(secs)) return Math.min(Math.max(secs, 0), 5) * 1000;
+  const when = Date.parse(raw);
+  return Number.isFinite(when) ? Math.min(Math.max(when - Date.now(), 0), 5000) : null;
+}
+
+const sleep = (ms) => new Promise((done) => { setTimeout(done, ms); });
+
 function enforceServerDecision(agent, decision) {
   if (decision?.hold) {
     emitGuardAsk(agent, decision.reason || 'Held for approval by Shomra - waiting on a reviewer. Retry once it’s approved.');
@@ -142,14 +267,37 @@ export async function cmdToolGuard(flags) {
     if (strict) {
       emitGuardDeny(agent, 'Shomra is not configured on this machine (SHOMRA_GUARD_STRICT). Run: shomra init --key shm_…');
     }
+    if (unscreenedSevere(normalized, tool, input)) askUnscreened(agent, 'Shomra is not configured on this machine');
     process.exit(0);
   }
 
   await recordMemoryWrite({ url, apiKey, input, normalized });
 
-  const escalate = alwaysEscalate || local.verdict === 'FLAG' || guardNeedsServer(tool, input, !!agentId);
-  if (!escalate) process.exit(0);
-  if (!strict && breakerOpen()) process.exit(0);
+  /* ⚠ A SEVERE CALL IS ALWAYS WORTH THE ROUND TRIP. `guardNeedsServer` asks
+   * which calls are worth escalating and answered NO for `git push --force
+   * origin main` and `rm -rf` alike - so the most destructive calls in the
+   * estate were graded by the offline tier and NOTHING ELSE: no org policy, no
+   * capability check, no flow control, and no gate event to read afterwards. */
+  const severe = unscreenedSevere(normalized, tool, input);
+  const escalate = alwaysEscalate || severe || local.verdict === 'FLAG' || guardNeedsServer(tool, input, !!agentId);
+  /* ⚠ A call the client CHOSE not to escalate is still a call no server graded,
+   * and the denominator has to carry it or the fail-open rate is measured over
+   * the escalated traffic alone - which flatters it by exactly the calls the
+   * client decided were dull. */
+  if (!escalate) {
+    countUnscreened('not escalated - screened by the local tier only');
+    process.exit(0);
+  }
+
+  /* Every path out of here that did NOT get a server verdict goes through this
+   * one door, so a new way of failing cannot quietly skip the rung check. */
+  const onUnreachable = (why) => {
+    countUnscreened(why);
+    if (severe) askUnscreened(agent, why);
+    return process.exit(0);
+  };
+
+  if (!strict && breakerOpen()) onUnreachable('the guard is in its backoff window after an earlier failure');
 
   const flagged = local.verdict === 'FLAG';
   const decision = await requestServerDecision({
@@ -158,7 +306,14 @@ export async function cmdToolGuard(flags) {
     agentId,
     agent,
     strict,
-    body: buildGuardBody(normalized, agent, flagged ? 'FLAG' : undefined, flagged ? local.top?.label : undefined),
+    onUnreachable,
+    body: {
+      ...buildGuardBody(normalized, agent, flagged ? 'FLAG' : undefined, flagged ? local.top?.label : undefined),
+      /* The window closes the moment a verdict arrives, and rides out on the
+       * SAME request - a separate report would be a second round trip on the
+       * firewall's hot path, and one that fails exactly when the first did. */
+      guard_ledger: sendLedger(),
+    },
   });
 
   enforceServerDecision(agent, decision);