@shomra/agent 0.3.19 → 0.3.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shomra/agent",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "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/cli/registry.mjs

@@ -9,6 +9,7 @@ import { cmdGate } from '../commands/gate.mjs';
 import { cmdInstallPrecommit } from '../commands/git-hooks.mjs';
 import { cmdInit } from '../commands/init.mjs';
 import { cmdInstallHook } from '../commands/install-hook.mjs';
+import { cmdLedger } from '../commands/ledger.mjs';
 import { cmdLlmProxy } from '../commands/llm-proxy.mjs';
 import { cmdMcp, cmdMcpGuard } from '../commands/mcp.mjs';
 import { cmdMemoryScan } from '../commands/memory-scan.mjs';
@@ -66,6 +67,7 @@ export const COMMANDS = {
   add: (f, p) => cmdAdd(f, p),
   'install-hook': (f) => cmdInstallHook(f),
   protect: (f) => cmdProtect(f),
+  ledger: (f) => cmdLedger(f),
   doctor: (f) => cmdDoctor(f),
   new: (f, p) => cmdNew(f, p),
   mcp: (f, p) => cmdMcp(f, p),

package/src/commands/ledger.mjs

@@ -0,0 +1,157 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { agentHookInstalled } from '../agents/hook-files.mjs';
+import { AGENT_KEYS } from '../agents/installers.mjs';
+import { mcpConfigCandidates } from '../mcp/config-wrapping.mjs';
+import { loadConfig, resolveSettings } from '../core/config.mjs';
+import { bold, cyan, dim, gray, green, red, yellow } from '../core/terminal.mjs';
+import { VERSION } from '../core/version.mjs';
+import { RUNG_LABEL, buildReport, isBeliefGap } from '../ledger/ladder.mjs';
+
+const UNMEASURED = { discrimination: 'UNKNOWN', prevention: 'UNPROVEN', preventionBasis: null };
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+
+function mcpReach() {
+  let total = 0;
+  let mediated = 0;
+  let files = 0;
+  const selfHints = ['mcp-guard', 'shomra'];
+
+  for (const file of mcpConfigCandidates()) {
+    const config = readJson(file);
+    const servers = config?.mcpServers || config?.servers;
+    if (!servers || typeof servers !== 'object') continue;
+    files++;
+    for (const entry of Object.values(servers)) {
+      if (!entry || typeof entry !== 'object') continue;
+      total++;
+      const argv = [entry.command, ...(entry.args ?? [])].map((x) => String(x ?? '')).join(' ');
+      const guarded = selfHints.some((h) => argv.includes(h));
+      const routed = typeof entry.url === 'string' && /\/mcp\//.test(entry.url);
+      if (guarded || routed) mediated++;
+    }
+  }
+  return { total, mediated, files };
+}
+
+function precommitInstalled() {
+  for (const dir of ['.git/hooks', path.join(process.cwd(), '.git', 'hooks')]) {
+    const file = path.join(dir, 'pre-commit');
+    try {
+      if (fs.existsSync(file) && /shomra/i.test(fs.readFileSync(file, 'utf8'))) return true;
+    } catch {
+      /* unreadable is not installed */
+    }
+  }
+  return false;
+}
+
+function subjects() {
+  const hooked = AGENT_KEYS.filter((a) => agentHookInstalled(a).length);
+  const mcp = mcpReach();
+  const precommit = precommitInstalled();
+  const enrolled = !!resolveSettings(loadConfig()).apiKey;
+
+  const out = [];
+
+  out.push({
+    id: 'runtime-gate',
+    label: 'the runtime firewall',
+    plane: 'tool-call',
+    chokepoint: 'every tool call this machine’s agents make',
+    mode: hooked.length ? 'ENFORCE' : 'ABSENT',
+    axes: { presence: hooked.length ? 'DEPLOYED' : 'NOT_DEPLOYED', reach: null, ...UNMEASURED },
+    statement: hooked.length
+      ? `The tool-call hook is installed for ${hooked.length} agent(s) on this machine. Nothing here has fired an attack at it, so what it does under one is untested.`
+      : 'No tool-call hook is installed on this machine, so nothing screens what its agents run.',
+  });
+
+  out.push({
+    id: 'mcp-gateway',
+    label: 'MCP call mediation',
+    plane: 'mcp-call',
+    chokepoint: 'the tool-call path between an agent and the servers it uses',
+    mode: mcp.mediated ? 'ENFORCE' : 'ABSENT',
+    axes: {
+      presence: mcp.total ? (mcp.mediated ? 'DEPLOYED' : 'NOT_DEPLOYED') : 'UNKNOWN',
+      reach: mcp.total
+        ? {
+            state: mcp.mediated === 0 ? 'BYPASSING' : mcp.mediated < mcp.total ? 'PARTIAL' : 'ENFORCED_UNQUANTIFIED',
+            observed: mcp.total,
+            controlled: mcp.mediated,
+            bypassRate: mcp.total ? (mcp.total - mcp.mediated) / mcp.total : null,
+          }
+        : null,
+      ...UNMEASURED,
+    },
+    statement: mcp.total
+      ? `${mcp.mediated} of ${mcp.total} MCP server(s) across ${mcp.files} local config(s) run through something that screens their calls.`
+      : 'No MCP server is configured in any config this machine can read, so nothing is claimed about call-time mediation here.',
+  });
+
+  out.push({
+    id: 'install-gate',
+    label: 'the install-time gate',
+    plane: 'mcp-install',
+    chokepoint: 'the commit that brings an AI artifact into this repo',
+    mode: precommit ? 'ENFORCE' : 'ABSENT',
+    axes: { presence: precommit ? 'DEPLOYED' : 'NOT_DEPLOYED', reach: null, ...UNMEASURED },
+    statement: precommit
+      ? 'A Shomra pre-commit hook is installed in this repository.'
+      : 'No install-time check runs in this repository, so an artifact reaches it without passing one.',
+  });
+
+  out.push({
+    id: 'llm-guard',
+    label: 'the LLM guard',
+    plane: 'llm-egress',
+    chokepoint: 'the model proxy every prompt and completion passes through',
+    mode: 'ABSENT',
+    axes: { presence: 'UNKNOWN', reach: null, ...UNMEASURED },
+    statement:
+      'Nothing on this machine can see where its prompts actually go, so whether a guard is in that path has not been established here. This is a limit of a local read, not a finding.',
+  });
+
+  return { rows: out, enrolled };
+}
+
+export function cmdLedger(flags = {}) {
+  const { rows, enrolled } = subjects();
+  const report = buildReport(rows, VERSION);
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    return 0;
+  }
+
+  console.log(bold(cyan('\n  Control ledger')) + dim(` · ${report.controls.length} controls · local read, no account`));
+  console.log(dim('  What has actually been shown about the controls on this machine.\n'));
+
+  for (const c of report.controls) {
+    const gap = isBeliefGap(c.rung);
+    const paint = gap ? red : c.rung === 'HOLDING' ? green : c.rung === 'ABSENT' ? yellow : gray;
+    console.log(`  ${paint('●')} ${bold(c.label.padEnd(24))} ${paint(RUNG_LABEL[c.rung])}`);
+    console.log(`    ${dim(c.statement)}`);
+    if (c.unmeasured.length) console.log(`    ${dim('unmeasured: ' + c.unmeasured.join(', '))}`);
+    console.log('');
+  }
+
+  console.log(`  ${dim(report.statement)}`);
+  console.log('');
+  console.log(dim('  Discrimination and prevention need an attack. Nothing here fired one, so no row'));
+  console.log(dim('  can reach "held under test" - and this report says so rather than rounding up.'));
+  console.log('');
+  console.log(`  ${dim('Publish it:')} shomra ledger --json > ledger.json`);
+  console.log(`  ${dim('Check it:  ')} npx controlledger-verify ledger.json`);
+  if (!enrolled) console.log(`  ${dim('Prove it:  ')} shomra init --key shm_…  ${dim('- to attack these controls and fill the last two axes')}`);
+  console.log('');
+  return 0;
+}

package/src/detect/signals/injection.mjs

@@ -11,7 +11,7 @@ export const INJECTION_PHRASES = [
 ];
 
 export const INJECTION_REGEXES = [
-  { label: 'Instruction-override phrasing', re: /\b(ignore|disregard|override|bypass|circumvent)\b[\s\w,'"()-]{0,40}?\b(instruction|instructions|directive|directives|safety|safeguards?|guardrails?|system\s+prompt|content\s+polic\w+)\b/i },
+  { label: 'Instruction-override phrasing', re: /\b(?:ignore|disregard|override|bypass|circumvent|discard|nullify|revoke|rescind|supersede[sd]?|abandon|set\s+aside|put\s+aside|cast\s+aside|pay\s+no\s+(?:attention|heed)\s+to|take\s+no\s+notice\s+of|stop\s+(?:following|obeying|adhering\s+to)|cease\s+(?:following|obeying)|no\s+longer\s+(?:follow|obey|adhere\s+to))\b[\s\w,'"()-]{0,40}?\b(instruction|instructions|directive|directives|safety|safeguards?|guardrails?|guidelines?|safety\s+(?:rules?|filters?|checks?)|system\s+prompt|content\s+polic\w+)\b/i },
   { label: 'Instructs the agent to conceal an action from the user', re: /\b(?:do\s*n['o]?t|never|without)\s+(?:tell|telling|inform|informing|notify|notifying|alert|alerting|mention|mentioning|disclos\w+|reveal\w*)\s+(?:it\s+|this\s+|them\s+)?(?:to\s+)?(?:the\s+)?(?:user|users|human|operator|owner)\b(?!['']s)(?!\s+(?:to\b|how\s+to\b|when\s+to\b|that\s+they\b|about\b))/i },
   { label: 'Bulk destructive command', re: /\b(delete|remove|wipe|erase|destroy|drop|purge|nuke|truncate)\b[\s\w,'"()-]{0,20}?\b(all|every|each|entire|whole)\b[\s\w,'"()-]{0,15}?\b(folder|folders|file|files|directory|directories|table|tables|database|databases|record|records|repo|repos|repositor\w*|account|accounts|user|users|row|rows|document|documents|data)\b/i },
   { label: 'Destructive SQL statement', re: /\b(drop|truncate)\s+(table|database|schema)\b/i },

package/src/ledger/ladder.mjs

@@ -0,0 +1,126 @@
+
+export const RUNGS = ['DEFEATED', 'INDISCRIMINATE', 'POROUS', 'ABSENT', 'UNEXERCISED', 'REFUSING', 'HOLDING'];
+export const RUNG_RANK = Object.fromEntries(RUNGS.map((r, i) => [r, i]));
+
+export const RUNG_LABEL = {
+  DEFEATED: 'Defeated under test',
+  INDISCRIMINATE: 'Refuses everything',
+  POROUS: 'Traffic goes around it',
+  ABSENT: 'No enforcement here',
+  UNEXERCISED: 'Never met an attack',
+  REFUSING: 'Refused an attack',
+  HOLDING: 'Held under test',
+};
+
+const GAP_RUNGS = new Set(['DEFEATED', 'INDISCRIMINATE', 'POROUS', 'ABSENT']);
+const BELIEF_GAPS = new Set(['DEFEATED', 'INDISCRIMINATE', 'POROUS']);
+const POROUS_REACH = new Set(['PARTIAL', 'BYPASSING', 'UNSUPPORTED']);
+
+export function isBeliefGap(rung) {
+  return BELIEF_GAPS.has(rung);
+}
+
+export function deriveRung(axes) {
+  const presence = axes?.presence;
+  const reach = axes?.reach ?? null;
+  const discrimination = axes?.discrimination;
+  const prevention = axes?.prevention;
+  const replayed = prevention === 'PREVENTED' && axes?.preventionBasis !== 'executed';
+
+  if (prevention === 'BYPASSED') return 'DEFEATED';
+  if (discrimination === 'INVERTED') return 'DEFEATED';
+  if (discrimination === 'INDISCRIMINATE') return 'INDISCRIMINATE';
+  if (reach && POROUS_REACH.has(reach.state)) return 'POROUS';
+  if (discrimination === 'UNGUARDED') return 'ABSENT';
+  if (presence === 'NOT_DEPLOYED') return 'ABSENT';
+  if (prevention !== 'PREVENTED' && (discrimination === 'UNEXERCISED' || discrimination === 'UNKNOWN')) return 'UNEXERCISED';
+  if (prevention === 'PREVENTED' && (replayed || discrimination !== 'DISCRIMINATING')) return 'REFUSING';
+  if (prevention !== 'PREVENTED' && discrimination === 'DISCRIMINATING') return 'REFUSING';
+  return 'HOLDING';
+}
+
+export function deriveUnmeasured(axes) {
+  const out = [];
+  const reach = axes?.reach ?? null;
+  if (!reach || reach.state === 'UNOBSERVED') out.push('reach');
+  if (axes?.discrimination === 'UNKNOWN' || axes?.discrimination === 'UNEXERCISED') out.push('discrimination');
+  if (axes?.prevention === 'UNPROVEN' || axes?.prevention === 'NOT_ATTEMPTABLE') out.push('prevention');
+  return out;
+}
+
+export function deriveBasis(axes, rung) {
+  if (GAP_RUNGS.has(rung)) return 'conclusive';
+  const replayed = axes?.prevention === 'PREVENTED' && axes?.preventionBasis !== 'executed';
+  const floor =
+    replayed ||
+    deriveUnmeasured(axes).length > 0 ||
+    !!axes?.truncated ||
+    Number(axes?.silentSubjects ?? 0) > 0 ||
+    axes?.reach?.state === 'ENFORCED_UNQUANTIFIED';
+  return floor ? 'floor' : 'conclusive';
+}
+
+export function summarize(rows) {
+  if (!rows.length) {
+    return (
+      'No control on this machine has been measured. That is not a clean result - it is the absence of any result, ' +
+      'and it is the state every machine is in until something is fired at it.'
+    );
+  }
+  const totals = Object.fromEntries(RUNGS.map((r) => [r, rows.filter((x) => x.rung === r).length]));
+  const gaps = rows.filter((x) => isBeliefGap(x.rung)).length;
+  const parts = [`${rows.length} control(s) on the ledger`];
+  parts.push(
+    gaps
+      ? `${gaps} measured weaker than they would be assumed to be (${totals.DEFEATED} defeated, ${totals.INDISCRIMINATE} refusing everything, ${totals.POROUS} with traffic going around them)`
+      : 'none measured weaker than assumed',
+  );
+  if (totals.ABSENT) parts.push(`${totals.ABSENT} path(s) with no enforcement on them`);
+  parts.push(
+    totals.HOLDING
+      ? `${totals.HOLDING} held under a reproduced exploit with ordinary traffic still passing`
+      : 'none has been shown to hold under a reproduced exploit',
+  );
+  if (totals.UNEXERCISED) parts.push(`${totals.UNEXERCISED} never met an attack (neither a pass nor a failure)`);
+  return parts.join(' · ');
+}
+
+export function buildReport(subjects, version) {
+  const controls = subjects.map((s) => {
+    const rung = deriveRung(s.axes);
+    return {
+      id: s.id,
+      label: s.label,
+      plane: s.plane,
+      chokepoint: s.chokepoint,
+      mode: s.mode ?? 'ABSENT',
+      rung,
+      basis: deriveBasis(s.axes, rung),
+      axes: {
+        presence: s.axes.presence,
+        reach: s.axes.reach ?? null,
+        discrimination: s.axes.discrimination,
+        prevention: s.axes.prevention,
+        preventionBasis: s.axes.preventionBasis ?? null,
+        truncated: false,
+        silentSubjects: s.axes.silentSubjects ?? 0,
+      },
+      unmeasured: deriveUnmeasured(s.axes),
+      statement: s.statement,
+    };
+  });
+
+  const totals = Object.fromEntries(RUNGS.map((r) => [r, controls.filter((c) => c.rung === r).length]));
+  return {
+    format: 'controlledger/1',
+    specVersion: '1.0',
+    producer: { name: 'shomra-cli', version: String(version ?? '') },
+    generatedAt: new Date().toISOString(),
+    basis: controls.length && controls.every((c) => c.basis === 'conclusive') ? 'conclusive' : 'floor',
+    controls,
+    totals,
+    beliefGaps: controls.filter((c) => isBeliefGap(c.rung)).length,
+    unmeasured: controls.filter((c) => c.unmeasured.length > 0).length,
+    statement: summarize(controls),
+  };
+}