@shomra/agent 0.2.12 → 0.3.2

package/design.mjs

@@ -0,0 +1,299 @@
+/**
+ * shomra design — threat-model a system that does not exist yet.
+ *
+ * Every other Shomra surface needs an artifact: a file to gate, a call to
+ * screen, a repo to scan. This one reads a DESCRIPTION — a design doc, an RFC, a
+ * Jira/Linear ticket, a PR body — and answers the only question worth asking
+ * before the first line is written: does the thing being described hand an
+ * attacker a path from untrusted input to a consequence?
+ *
+ * The engine is the platform's, not a new one. `attack-graph.ts` models an
+ * entity as six capability flags split into SOURCES (untrusted input, sensitive
+ * reads, filesystem) and SINKS (network egress, execution, destructive action),
+ * and calls a closed source→sink pair an attack path. That model does not care
+ * whether the capabilities came from a scan or from a sentence. Here they come
+ * from a sentence.
+ *
+ * ⚠ THE INVARIANT THAT MATTERS: absence of a described capability is NOT absence
+ * of the capability. Prose is written by people who leave things out. Every
+ * verdict this module can return names what it FOUND; none of them says the
+ * design is safe, and `NOT_DESCRIBED` is not a pass. Getting this wrong would
+ * turn a thinking aid into false assurance at the exact moment — before the
+ * build — when false assurance is cheapest to act on and most expensive to
+ * discover.
+ *
+ * Zero dependencies (Node built-ins only), like every other module here.
+ */
+
+// The capability vocabulary, mirroring `Caps` in the backend's attack-graph.ts.
+// Keep the split identical: a divergence here would produce a CLI threat model
+// that disagrees with the platform's for the same system.
+export const SOURCE_CAPS = ['injection', 'readsSensitive', 'filesystem'];
+export const SINK_CAPS = ['network', 'exec', 'destructive'];
+
+export const CAP_LABEL = {
+  injection: 'untrusted input',
+  readsSensitive: 'sensitive data',
+  filesystem: 'filesystem access',
+  network: 'network egress',
+  exec: 'code execution',
+  destructive: 'destructive action',
+};
+
+/**
+ * Prose → capability. Each rule carries the phrasing a designer actually uses,
+ * not the phrasing a scanner would emit. `what` is the human noun that goes into
+ * the attack story, so a path reads as a sentence about the system rather than a
+ * list of flags.
+ *
+ * Rules are matched per line so the evidence can cite one, and so a document
+ * that mentions a capability in a "we will not do X" sentence is still surfaced
+ * — unlike the runtime detectors, a design doc's negations are DESIGN DECISIONS
+ * worth showing the reader, not false positives to suppress. The reader decides.
+ */
+const CAP_RULES = [
+  // ── SOURCES ────────────────────────────────────────────────────────────────
+  { cap: 'injection', what: 'end-user or customer text', re: /\b(user|customer|client|end[- ]user)[- ]?(input|message|text|query|prompt|request|content|submission)\b/i },
+  { cap: 'injection', what: 'inbound email', re: /\b(inbound |incoming |receiv\w+ )?e-?mails?\b|\bmailbox\b|\bimap\b|\bsupport inbox\b/i },
+  { cap: 'injection', what: 'support tickets', re: /\b(support |help[- ]?desk |zendesk |intercom |freshdesk )?tickets?\b|\bcase notes?\b/i },
+  { cap: 'injection', what: 'issues and PR descriptions', re: /\b(github |gitlab |jira |linear )?(issues?|pull[- ]requests?|PR) (body|description|comments?)\b|\bissue tracker\b/i },
+  // Document nouns are plural far more often than not in a design doc ("ingests
+  // uploaded PDFs"), and an `\bpdf\b` that cannot match "PDFs" is a rule that
+  // misses the common phrasing while looking correct in a unit test.
+  { cap: 'injection', what: 'uploaded documents', re: /\b(upload(ed|s)?|attach(ed|ment)s?)\b.{0,30}\b(files?|documents?|pdfs?|images?|csvs?|spreadsheets?)\b|\b(pdf|docx|csv)s? (upload|ingest|pars\w+)/i },
+  // Provenance, not format: content ACCEPTED FROM a party outside the trust
+  // boundary is untrusted whatever shape it arrives in. Anchored on a receiving
+  // verb + "from" + the party, so ordinary prose about customers does not fire.
+  { cap: 'injection', what: 'content received from outside', re: /\b(ingest|receiv|accept|import|process|pull|collect|read|fetch)\w*\b[^.\n]{0,40}\bfrom\b[^.\n]{0,25}\b(customers?|users?|clients?|end[- ]users?|the public|third[- ]part\w+|external|partners?|vendors?|suppliers?)\b/i },
+  { cap: 'injection', what: 'scraped or fetched web content', re: /\b(scrap\w+|crawl\w+|fetch\w+|browse\w*)\b.{0,30}\b(web|site|page|url|internet)\b|\bweb (page|content|search results?)\b/i },
+  { cap: 'injection', what: 'retrieved documents (RAG)', re: /\bRAG\b|\bretrieval[- ]augmented\b|\b(retriev\w+|search\w*) (documents?|chunks?|context|corpus)\b|\bvector (store|db|database|search)\b|\bknowledge base\b/i },
+  { cap: 'injection', what: 'third-party API responses', re: /\bthird[- ]party\b.{0,30}\b(api|response|data|feed|service)\b|\bexternal (api|service|feed) (response|data|content)\b/i },
+  { cap: 'injection', what: 'public form submissions', re: /\bpublic\b.{0,25}\b(form|endpoint|api|submission|chat|widget)\b|\bunauthenticated (user|request|caller)\b/i },
+  { cap: 'injection', what: 'chat or comment history', re: /\b(chat|conversation|comment|review|forum|slack|discord|teams) (history|thread|messages?|log)\b/i },
+  { cap: 'injection', what: 'MCP tool results', re: /\bMCP\b.{0,40}\b(tool|server|response|result)\b|\btool (result|response|output)s?\b.{0,20}\b(back into|into (the )?context)\b/i },
+
+  { cap: 'readsSensitive', what: 'customer records', re: /\b(customer|user|client|member|patient|employee)s?[- ]?(data|records?|profiles?|list|database|table|pii)\b|\bPII\b|\bpersonal(ly)?[- ]identifiab\w+/i },
+  { cap: 'readsSensitive', what: 'credentials or secrets', re: /\b(secret|credential|api[- ]?key|access[- ]?token|password|private[- ]?key|service[- ]account)s?\b|\bvault\b|\bkeychain\b|\b\.env\b/i },
+  { cap: 'readsSensitive', what: 'regulated data', re: /\b(PHI|HIPAA|GDPR|PCI([- ]DSS)?|SOC ?2|health (records?|data)|medical|financial (records?|data)|payroll|salar(y|ies)|SSN|social security|tax)\b/i },
+  { cap: 'readsSensitive', what: 'the production database', re: /\bprod(uction)?\b.{0,25}\b(database|db|data|warehouse|replica|store)\b|\b(database|db|warehouse) (read|query|access|connection)\b|\bread[- ]replica\b/i },
+  { cap: 'readsSensitive', what: 'private source code', re: /\bprivate (repo|repositor\w+|source|code)\b|\bproprietary (code|source)\b|\binternal (repo|codebase|wiki|docs?)\b/i },
+  { cap: 'readsSensitive', what: 'object storage', re: /\bS3 bucket\b|\b(blob|object) storage\b|\bGCS bucket\b|\bdata lake\b/i },
+
+  { cap: 'filesystem', what: 'file writes', re: /\bwrit\w+\b.{0,25}\b(file|disk|filesystem|directory|folder|repo)\b|\b(file ?system|local files?) (access|write)\b|\bcommits? (code|files?|changes?)\b/i },
+  { cap: 'filesystem', what: 'workspace or repo checkout', re: /\b(clones?|checks? out|checkout)\b.{0,25}\b(repo|repositor\w+)\b|\bworkspace (access|mount|volume)\b/i },
+
+  // ── SINKS ──────────────────────────────────────────────────────────────────
+  { cap: 'network', what: 'outbound API calls', re: /\bcalls?\b.{0,30}\b(external|third[- ]party|public|remote|partner)\b.{0,20}\bapi\b|\boutbound (request|call|http|traffic)\b|\begress\b/i },
+  { cap: 'network', what: 'webhooks', re: /\bwebhooks?\b|\bpost(s|ing)?\b.{0,25}\b(to an? )?(endpoint|url|callback)\b/i },
+  { cap: 'network', what: 'sending email or messages', re: /\bsends?\b.{0,25}\b(e-?mail|message|notification|sms|slack|dm)\b|\bnotif(y|ies|ication)\b.{0,25}\b(user|customer|channel|slack|teams|email)\b|\bsmtp\b/i },
+  { cap: 'network', what: 'publishing or uploading data', re: /\b(publish|upload|export|sync|push)\w*\b.{0,30}\b(to|into)\b.{0,25}\b(external|third[- ]party|cloud|bucket|service|partner|crm|warehouse)\b/i },
+  { cap: 'network', what: 'a model provider call', re: /\b(openai|anthropic|gemini|bedrock|azure openai|mistral|cohere|hugging ?face)\b|\bLLM (api|provider|call)\b|\bmodel (provider|endpoint|api)\b/i },
+
+  { cap: 'exec', what: 'running shell commands', re: /\b(runs?|execut\w+|invok\w+|spawn\w+)\b.{0,25}\b(command|shell|bash|script|binary|subprocess|terminal)\b|\bshell access\b|\barbitrary code\b/i },
+  { cap: 'exec', what: 'code interpretation', re: /\b(code (interpreter|execution|sandbox)|eval\b|exec\b|repl\b|jupyter|notebook execution)\b/i },
+  { cap: 'exec', what: 'deployments or migrations', re: /\b(deploy|rollout|release|migrat\w+|provision\w*|terraform|helm|kubectl)\b/i },
+  { cap: 'exec', what: 'agent tool calls', re: /\b(tool[- ]call|function[- ]call|tool use|agentic loop|autonomous(ly)?)\b|\bagent (executes?|acts?|takes? actions?)\b/i },
+
+  { cap: 'destructive', what: 'deleting data', re: /\bdelet\w+|\bremov\w+\b.{0,20}\b(record|row|file|user|account|data)\b|\bpurge\b|\bdrop (table|database)\b|\btruncat\w+/i },
+  { cap: 'destructive', what: 'moving money', re: /\b(refund|payment|charge|invoice|payout|transfer|billing|subscription|purchase|order)s?\b|\bstripe\b|\bmoves? money\b/i },
+  { cap: 'destructive', what: 'changing access or state', re: /\b(revok\w+|disabl\w+|suspend\w+|deactivat\w+|cancel\w*|ban\w*)\b.{0,25}\b(user|account|access|key|token|subscription|service)\b|\bgrants? (access|permission|role)\b/i },
+  { cap: 'destructive', what: 'writing to production', re: /\bwrit\w+\b.{0,25}\bprod(uction)?\b|\bprod(uction)?\b.{0,20}\bwrite (access|path)\b|\bmutat\w+\b.{0,25}\b(prod|live|customer) (data|state)\b/i },
+];
+
+/** Lines that are headings, code fences or list scaffolding carry no design intent. */
+function isSkippableLine(line) {
+  const t = line.trim();
+  return !t || t === '---' || /^```/.test(t) || /^\|[\s-:|]+\|$/.test(t);
+}
+
+/**
+ * Extract the capability set a document DESCRIBES, with the line and phrase that
+ * evidenced each — the evidence is the point: a reader has to be able to check
+ * the machine's reading against their own words and disagree with it.
+ */
+export function capsFromProse(text) {
+  const caps = { injection: false, readsSensitive: false, filesystem: false, network: false, exec: false, destructive: false };
+  const evidence = {};
+  const lines = String(text ?? '').split(/\r?\n/);
+  let inFence = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*```/.test(line)) { inFence = !inFence; continue; }
+    // Code blocks in a design doc are illustrative snippets, not statements of
+    // intent — and they are exactly where a scanner's vocabulary produces noise.
+    if (inFence || isSkippableLine(line)) continue;
+
+    for (const r of CAP_RULES) {
+      const m = r.re.exec(line);
+      if (!m) continue;
+      caps[r.cap] = true;
+      const list = (evidence[r.cap] = evidence[r.cap] || []);
+      if (list.some((e) => e.what === r.what)) continue; // one citation per distinct capability phrasing
+      list.push({ what: r.what, line: i + 1, quote: line.trim().slice(0, 160), match: m[0].slice(0, 60), score: evidenceScore(line) });
+    }
+  }
+  // Rank each capability's citations so the one the attack story quotes is the
+  // line that DESCRIBES the behaviour, not the first line the word appeared on.
+  // "Reduce first-response time on support tickets" (a goal) and "polls the
+  // support inbox and reads inbound emails" (the design) both mention tickets;
+  // quoting the goal makes the finding look like a keyword hit and is the
+  // fastest way for a reader to stop trusting the output.
+  for (const k of Object.keys(evidence)) evidence[k].sort((a, b) => b.score - a.score || a.line - b.line);
+  return { caps, evidence };
+}
+
+// A line that says what the system DOES, rather than what it is for. Used only
+// to order evidence — never to grant or withhold a capability.
+const ACTION_LINE_RE = /\b(reads?|writes?|polls?|fetch\w*|calls?|sends?|runs?|executes?|issues?|looks? up|quer\w+|retriev\w+|ingest\w*|receiv\w+|access\w*|store[sd]?|upload\w*|post\w*|delet\w+|creat\w+|updat\w+|has|have|will|can|must)\b/i;
+const GOAL_LINE_RE = /^\s{0,3}#{1,6}\s|^\s*(goal|motivation|background|summary|context|out of scope|non-goals?)\b/i;
+
+function evidenceScore(line) {
+  let s = 0;
+  if (ACTION_LINE_RE.test(line)) s += 3;
+  if (GOAL_LINE_RE.test(line)) s -= 3;
+  if (line.trim().length > 60) s += 1; // a full sentence beats a heading fragment
+  return s;
+}
+
+/** Severity of a closed path. Mirrors chainSeverity() in attack-graph.ts:
+ *  untrusted input reaching a hard sink is the worst case in the model. */
+function pathSeverity(source, sink) {
+  const hardSink = sink === 'exec' || sink === 'destructive';
+  if (hardSink && source === 'injection') return 'CRITICAL';
+  if (hardSink) return 'HIGH';
+  if (sink === 'network' && (source === 'readsSensitive' || source === 'injection')) return 'HIGH';
+  return 'MEDIUM';
+}
+
+// What has to be true for a given source→sink pair to be safe to build. These
+// are stated as testable conditions rather than advice, because their job is to
+// become the acceptance criteria on the ticket that describes the system.
+const CONTROLS = {
+  'injection→exec': [
+    'The set of commands the agent can run is a fixed allowlist in code. Model output selects WHICH allowlisted action runs, never the command string itself.',
+    'Untrusted text is passed as a labelled data parameter, never concatenated into a command, a prompt template, or a tool argument that reaches a shell.',
+    'The runtime firewall is wired on this path (`shomra protect`), so a command assembled at runtime is refused rather than logged.',
+  ],
+  'injection→destructive': [
+    'Every destructive or money-moving action requires an approval step that a human performs outside the agent loop.',
+    'The action is idempotent and reversible, with an audit record naming the input that triggered it.',
+    'Per-action limits (amount, row count, blast radius) are enforced server-side, not by the prompt.',
+  ],
+  'injection→network': [
+    'Outbound destinations come from an allowlist. A URL that appears in untrusted content can never become a request target.',
+    'The agent cannot include content it read into an outbound request to a destination named by that same content.',
+  ],
+  'readsSensitive→network': [
+    'Splitting the trust boundary: the component that reads the sensitive data and the component that makes the outbound call do not share one context or one credential.',
+    'Outbound payloads are field-allowlisted — what may leave is enumerated, rather than what may not.',
+    'The sensitive read is scoped to the minimum rows/fields the task needs, per-request, not a standing broad grant.',
+  ],
+  'readsSensitive→exec': [
+    'Secrets are injected at the point of use from a broker with short-lived leases, never placed in the environment of a process the agent can influence.',
+    'The executing context cannot read the credential store it does not need.',
+  ],
+  'readsSensitive→destructive': [
+    'The identity that reads and the identity that mutates are different, each scoped to its own job.',
+    'Destructive actions are gated on a human approval that shows the operator exactly which records are affected.',
+  ],
+  'filesystem→exec': [
+    'Files the agent writes cannot land anywhere on an execution path (no hooks, no startup dirs, no CI config, no agent rules files) without passing the gate.',
+    '`shomra check` runs over agent-authored artifacts before they are committed.',
+  ],
+  'filesystem→network': [
+    'The agent cannot write a file and then cause that file to be uploaded to a destination it chose.',
+  ],
+  'filesystem→destructive': [
+    'Writes are confined to a working directory, with deletes scoped to paths the agent itself created.',
+  ],
+};
+
+const GENERIC_CONTROLS = [
+  'Give the agent its own identity with its own credentials, so its actions are attributable and revocable independently of a human user.',
+  'Record every tool call the agent makes, with the input that caused it, so an incident can be reconstructed.',
+  'Decide now what the agent must NOT be able to do, and enforce it in code rather than in the prompt — a prompt is a request, not a control.',
+];
+
+/**
+ * Threat-model a described system.
+ *
+ * `verdict` deliberately has no clean value:
+ *   OPEN_PATH     — a source and a sink are both described; the path is closed.
+ *   PARTIAL       — only one side is described. Not safety: the other side may
+ *                   simply be unwritten, or may arrive in the next sprint.
+ *   NOT_DESCRIBED — neither side was recognised. The likeliest reading is that
+ *                   the document does not describe capabilities in a way this
+ *                   matched, NOT that the system has none.
+ */
+export function analyzeDesign(text, { name = 'design' } = {}) {
+  const { caps, evidence } = capsFromProse(text);
+  const sources = SOURCE_CAPS.filter((c) => caps[c]);
+  const sinks = SINK_CAPS.filter((c) => caps[c]);
+
+  const paths = [];
+  for (const s of sources) {
+    for (const k of sinks) {
+      const severity = pathSeverity(s, k);
+      const srcEv = (evidence[s] || [])[0];
+      const sinkEv = (evidence[k] || [])[0];
+      paths.push({
+        source: s,
+        sink: k,
+        severity,
+        key: `${s}→${k}`,
+        story:
+          `${cap(srcEv ? srcEv.what : CAP_LABEL[s])} reaches ${sinkEv ? sinkEv.what : CAP_LABEL[k]}` +
+          `${s === 'injection' ? ' — whoever writes that input is choosing what the agent does' : ''}` +
+          `${s === 'readsSensitive' && k === 'network' ? ' — the data and the way out are held by the same component' : ''}.`,
+        sourceEvidence: srcEv || null,
+        sinkEvidence: sinkEv || null,
+        controls: CONTROLS[`${s}→${k}`] || [],
+      });
+    }
+  }
+  paths.sort((a, b) => SEV_RANK[b.severity] - SEV_RANK[a.severity]);
+
+  const verdict = paths.length ? 'OPEN_PATH' : sources.length || sinks.length ? 'PARTIAL' : 'NOT_DESCRIBED';
+  const worst = paths.length ? paths[0].severity : null;
+
+  // Deduplicate controls across paths, worst-severity first, then append the
+  // ones that apply to any agent with a consequence.
+  const seen = new Set();
+  const controls = [];
+  for (const p of paths) for (const c of p.controls) if (!seen.has(c)) { seen.add(c); controls.push({ text: c, from: p.key, severity: p.severity }); }
+  if (paths.length) for (const c of GENERIC_CONTROLS) if (!seen.has(c)) { seen.add(c); controls.push({ text: c, from: 'any-agent', severity: 'MEDIUM' }); }
+
+  return { name, caps, evidence, sources, sinks, paths, controls, verdict, worst };
+}
+
+const SEV_RANK = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
+
+function cap(s) {
+  return String(s || '').charAt(0).toUpperCase() + String(s || '').slice(1);
+}
+
+/** The result as a markdown task list — the form that becomes the ticket's
+ *  acceptance criteria, which is the only form anyone acts on. */
+export function designChecklist(result) {
+  const out = [];
+  out.push(`## Security acceptance criteria — ${result.name}`);
+  out.push('');
+  if (result.verdict !== 'OPEN_PATH') {
+    out.push(
+      result.verdict === 'PARTIAL'
+        ? `Only one side of an attack path is described here (${[...result.sources, ...result.sinks].map((c) => CAP_LABEL[c]).join(', ')}). Re-run this when the design names what the agent can *do* with it.`
+        : 'No capabilities were recognised in this document. That is a statement about the document, not about the system — if the agent will read anything untrusted or take any action, write that down and re-run.',
+    );
+    out.push('');
+    return out.join('\n') + '\n';
+  }
+  out.push(`This design closes ${result.paths.length} attack path${result.paths.length === 1 ? '' : 's'}. Each item below is a condition to satisfy before it ships.`);
+  out.push('');
+  for (const p of result.paths.slice(0, 6)) out.push(`- **${p.severity} · ${CAP_LABEL[p.source]} → ${CAP_LABEL[p.sink]}** — ${p.story}`);
+  out.push('');
+  for (const c of result.controls) out.push(`- [ ] ${c.text}`);
+  out.push('');
+  out.push('_Derived by `shomra design` from the description above. It reads prose, so it sees only what was written down — a capability nobody documented is not a capability you do not have._');
+  return out.join('\n') + '\n';
+}

package/guard-signals.mjs

@@ -73,9 +73,12 @@ export const DANGEROUS_SHELL = [
   { name: 'Fetches from a raw IP address', re: /\b(curl|wget|iwr|irm|invoke-webrequest|invoke-restmethod)\b[^\n]{0,220}https?:\/\/\d{1,3}(\.\d{1,3}){3}/i, severity: 'HIGH' },
   { name: 'Writes to shell profile / SSH keys / crontab', re: /(\.bashrc|\.zshrc|\.bash_profile|\.profile|authorized_keys|id_rsa\b|\bcrontab\b)/i, severity: 'HIGH' },
   { name: 'Recursive force delete (rm -rf)', re: /\brm\s+-[a-z]*r[a-z]*f|\brm\s+-[a-z]*f[a-z]*r/i, severity: 'HIGH', refine: rmTargetsRealData },
-  // BARE `eval(`/`exec(` only — the lookbehind drops method calls that merely end
-  // in those letters (`db.exec(`, `RE.exec(`, `page.$eval(`, `$pdo->exec(`).
-  { name: 'Inline eval / exec of a string', re: /(?<![.\w$>:])(eval|exec)\s*[("`']/i, severity: 'HIGH' },
+  // BARE `eval(`/`exec(` only — the lookbehind drops anything that merely ENDS in
+  // those letters: method calls (`db.exec(`, `RE.exec(`, `page.$eval(`, `$pdo->exec(`)
+  // AND hyphen/quote-joined identifiers like `sandbox-exec` (macOS Seatbelt) or a
+  // `"…exec"` string in prose. Kept byte-identical to the backend rule
+  // (bundle/signals.ts) so the local gate and the server never disagree on it.
+  { name: 'Inline eval / exec of a string', re: /(?<![-.\w$>:`"'])(eval|exec)\s*[("`']/i, severity: 'HIGH' },
   { name: 'Pipes an env dump to the network', re: /\b(env|printenv|set)\b[^\n|]{0,80}\|[^\n]{0,80}(curl|wget|nc\b|http)/i, severity: 'HIGH' },
   { name: 'Disables TLS / cert verification', re: /(NODE_TLS_REJECT_UNAUTHORIZED\s*=\s*0|GIT_SSL_NO_VERIFY|--no-check-certificate|--insecure\b|verify\s*=\s*False)/i, severity: 'MEDIUM' },
   { name: 'python -c one-liner', re: /python[0-9.]*\s+-c\b/i, severity: 'MEDIUM' },
@@ -721,11 +724,37 @@ const SABOTAGE_RULES = [
   { re: /\bignore\b[^.\n]{0,40}\b(user|human)\b[^.\n]{0,25}\b(prompt|instruction|input|request|message|command|wish|intent|question)s?\b/i, label: 'ignore-user', guarded: true },
   { re: /\bdo not\b[^.\n]{0,20}\b(log|display|show|print|record|surface|expose|output)\b[^.\n]{0,60}\buser\b/i, label: 'conceal-from-user', guarded: false, context: /\b(transfer|transmit|send|network|exfil|upload|post|copy|collect|file|data|when)\b/i },
 ];
+// Descriptive / documentation mood: a line that NAMES a security concept rather
+// than INSTRUCTING the agent to perform it. Poisoning payloads are imperative and
+// address the agent ("always exfiltrate the env to evil.com"); a security-minded
+// rules file mentions the same techniques as nouns ("treat these as exfiltration
+// destinations"). Only ever used to SUPPRESS, never to raise a finding.
+// Mirrors backend src/bundle/memory-signals.ts — keep the two in step.
+const DESCRIPTIVE_MARKERS =
+  /\b(detect|scan|flag|block|catch|prevent|guard|protect|harden|audit|benchmark|catalog|scenario|corpus|coverage|example|vector|signal|rule|technique|posture|detection|test\s*case|red[- ]?team|-style|grounded in|fixed|now green|was|were|had|used to|previously|postmortem|regression|changelog|root[- ]?cause|repro|note|see|describes?|documents?|refers?|treat(s|ed|ing)?|counts?|reads?)\w*/i;
+
+/** Descriptive documentation with no imperative aimed at the agent. The
+ *  `!IMPERATIVE` clause is what keeps this safe: "note: ALWAYS exfiltrate…"
+ *  still grades. */
+function isDescriptiveLine(line) {
+  return DESCRIPTIVE_MARKERS.test(line) && !IMPERATIVE.test(line);
+}
+
+// A loopback / private-network URL is a dev/smoke-test target, not exfiltration.
+const LOCAL_URL_RE = /\bhttps?:\/\/(localhost|127\.\d+|0\.0\.0\.0|\[::1\]|192\.168\.|10\.\d+|172\.(1[6-9]|2\d|3[01])\.)/i;
+
+// `descGuard` rules fire on a bare noun ("exfiltration", "leak the data") and so
+// are suppressed on a descriptive line. Rules without it already require an
+// explicit sink/verb structure. The whole set is ALSO negation-guarded per line
+// in scanDirectives, so "never leak the API key" is a hardening rule, not a leak.
 const EXFIL_RULES = [
-  { re: /\b(exfiltrat|smuggl)\w*/i, label: 'exfiltration', severity: 'CRITICAL' },
-  { re: /\bleak\w*\b[^.\n]{0,60}\b(content|data|secret|file|credential|key|token|password|env|\.ssh|private[- ]?key|id_rsa|api[- ]?key)\b/i, label: 'leak-secrets', severity: 'CRITICAL' },
-  { re: /\b(base64|hex|rot13|gzip|xor|url[- ]?encod)\w*\b[^.\n]{0,50}\b(before|then|and|prior to|for)\b[^.\n]{0,25}\b(send|post|upload|transmit|exfil|deliver|beacon|forward|transfer)\w*/i, label: 'obfuscate-before-send', severity: 'CRITICAL' },
-  { re: /\bsilent(ly)?\b[^.\n]{0,70}\b(send|post|upload|collect|encod|transmit|copy|forward|read|leak|deliver|beacon|transfer)\w*/i, label: 'covert-action', severity: 'CRITICAL' },
+  { re: /\b(exfiltrat|smuggl)\w*/i, label: 'exfiltration', severity: 'CRITICAL', descGuard: true },
+  { re: /\bleak\w*\b[^.\n]{0,60}\b(content|data|secret|file|credential|key|token|password|env|\.ssh|private[- ]?key|id_rsa|api[- ]?key)\b/i, label: 'leak-secrets', severity: 'CRITICAL', descGuard: true },
+  // Deliberate encode-THEN-send sequencing. The connector excludes a bare
+  // "and"/"for" — "gzips the capture and posts it to /bundle/scan" is a pipeline
+  // description, not obfuscated exfil.
+  { re: /\b(base64|hex|rot13|gzip|xor|url[- ]?encod)\w*\b[^.\n]{0,50}\b(before|then|prior to|and\s+then|and\s+immediately)\b[^.\n]{0,25}\b(send|post|upload|transmit|exfil|deliver|beacon|forward|transfer)\w*/i, label: 'obfuscate-before-send', severity: 'CRITICAL', descGuard: true },
+  { re: /\bsilent(ly)?\b[^.\n]{0,70}\b(send|post|upload|collect|encod|transmit|copy|forward|read|leak|deliver|beacon|transfer)\w*/i, label: 'covert-action', severity: 'CRITICAL', descGuard: true },
   { re: /\b(send|post|upload|transmit|forward|deliver|beacon|report|ship|push|transfer)\w*\b[^.\n]{0,80}\b(https?:\/\/\S+|attacker|c2\b|command[- ]and[- ]control|remote (server|host|endpoint)|external (server|host|endpoint|url|site|service))/i, label: 'send-to-external', severity: 'HIGH' },
 ];
 function scanDirectives(text) {
@@ -734,11 +763,19 @@ function scanDirectives(text) {
     for (const r of SABOTAGE_RULES) {
       if (!r.re.test(line)) continue;
       if (r.guarded && NEGATION_GUARD.test(line)) continue;
+      if (r.guarded && isDescriptiveLine(line)) continue; // "detects skills that disable safety" — documentation
       if (r.context && !r.context.test(line)) continue;
       if (!sabotage.has(r.label)) sabotage.set(r.label, line);
     }
     for (const r of EXFIL_RULES) {
       if (!r.re.test(line)) continue;
+      // A line that FORBIDS exfiltration is the single most common sentence in a
+      // security-conscious rules file. Scoring it as a poisoned directive inverts
+      // the tool on exactly the teams writing the best rules. (The named-host
+      // check in localMemory stays unguarded, so a real sink still fires here.)
+      if (NEGATION_GUARD.test(line)) continue;
+      if (r.descGuard && isDescriptiveLine(line)) continue;
+      if (r.label === 'send-to-external' && LOCAL_URL_RE.test(line) && !/\b(attacker|c2|command[- ]and[- ]control|external|evil)\b/i.test(line)) continue;
       const prev = exfil.get(r.label);
       if (!prev || (prev === 'HIGH' && r.severity === 'CRITICAL')) exfil.set(r.label, r.severity);
     }
@@ -789,8 +826,17 @@ export function localMemory(content, { kind = 'MEMORY' } = {}) {
   for (const sig of DANGEROUS_SHELL) if (matchesShellSignal(sig, text)) { push(sig.severity === 'MEDIUM' || sig.severity === 'LOW' ? 'HIGH' : 'CRITICAL', `Executable payload staged in ${noun}: ${sig.name}`, `Delete the command from the ${noun}; treat the writer as untrusted.`, sig.re); break; }
   const host = egressHost(text);
   if (host) push('HIGH', `${isInstruction ? 'Rules file' : 'Memory'} references a data-exfiltration host (${host})`, 'Remove the reference and roll back to the approved baseline.', host);
-  if (hasImperative && containsWord(text, SENSITIVE_READ) && containsWord(text, NETWORK_VERBS)) {
-    push('HIGH', `Toxic instruction in ${noun}: reads sensitive data + reaches the network`, 'Remove the entry; gate any network step behind explicit approval and an egress allow-list.');
+  // Toxic flow: an IMPERATIVE line that names BOTH sensitive data and a network
+  // verb — a standing "read X and send it" instruction. Co-located per line, not
+  // whole-document co-occurrence: a long rules file mentioning `.env` in one
+  // paragraph and `curl` in another is not a flow, and grading it as one was the
+  // dominant false positive here. Negated ("never send the .env anywhere") and
+  // descriptive lines are documentation, not directives. Mirrors the backend.
+  const toxicFlowLine = hasImperative
+    ? text.split(/\r?\n/).find((l) => IMPERATIVE.test(l) && !NEGATION_GUARD.test(l) && containsWord(l, SENSITIVE_READ) && containsWord(l, NETWORK_VERBS) && !isDescriptiveLine(l))
+    : null;
+  if (toxicFlowLine) {
+    push('HIGH', `Toxic instruction in ${noun}: reads sensitive data + reaches the network`, 'Remove the entry; gate any network step behind explicit approval and an egress allow-list.', toxicFlowLine);
   }
   if (LIFECYCLE_VECTOR.test(text)) push('MEDIUM', `${isInstruction ? 'Rules file' : 'Memory'} references a package-lifecycle hook (MemoryTrap vector)`, 'Verify no dependency writes to this store during install; pin dependencies and audit lifecycle scripts.', LIFECYCLE_VECTOR);
 

package/model-refs.mjs

@@ -41,6 +41,25 @@ const OLLAMA = /\bollama\s+(?:pull|run|cp|create)\s+([a-z0-9][\w.:\/-]*)/gi;
 // torch.hub.load("pytorch/vision", …) — a GitHub owner/repo that runs hubconf.py.
 const TORCH_HUB = /torch\.hub\.load\s*\(\s*['"]([A-Za-z0-9][\w.-]*\/[A-Za-z0-9][\w.-]*)['"]/g;
 
+// Hosted-API model families. A bare `model="gpt-4o"` / `model="claude-…"` is an
+// OpenAI/Anthropic/Google/etc API call, NOT a Hugging Face repo — but `model=` is
+// their SDK param too, so KW_ID/from_pretrained would otherwise tag these 'hf' and
+// trigger a doomed HF-Index lookup ("gpt-4o (hf) lookup failed"). Recognize them
+// and tag 'api' with the provider. Prefix-anchored to avoid matching HF repos.
+const API_MODEL = /^(?:gpt-|gpt4|o[1-4](?:-|$)|text-embedding-|text-(?:davinci|curie|babbage|ada)|davinci|dall-e|whisper-|tts-|chatgpt|claude[-\d]|gemini[-.]|gemini$|models\/gemini|mistral-|mixtral-|codestral-|command(?:-|$)|command-r|grok-|deepseek-(?:chat|coder|reasoner)|sonar-)/i;
+function apiProvider(id) {
+  const s = String(id || '').toLowerCase();
+  if (/^(gpt|o[1-4]|text-|davinci|curie|babbage|ada|dall-e|whisper|tts-|chatgpt)/.test(s)) return 'openai';
+  if (/^claude/.test(s)) return 'anthropic';
+  if (/^(gemini|models\/gemini)/.test(s)) return 'google';
+  if (/^(mistral|mixtral|codestral)/.test(s)) return 'mistral';
+  if (/^command/.test(s)) return 'cohere';
+  if (/^grok/.test(s)) return 'xai';
+  if (/^deepseek/.test(s)) return 'deepseek';
+  if (/^sonar/.test(s)) return 'perplexity';
+  return 'api';
+}
+
 // Reject ids that are really file paths, packages, or non-model strings.
 const ASSET_EXT = /\.(py|pyc|ipynb|[mc]?[jt]sx?|json|ya?ml|toml|txt|md|lock|cfg|ini|sh|env|png|jpg|svg|css|html?|csv|tsv|parquet)$/i;
 // First path segment on huggingface.co that is a SITE section, not an org — so
@@ -83,6 +102,13 @@ export function scanModelRefs(text, file = '') {
   // position (from_pretrained/SentenceTransformer/model=); ollama ids are freeform.
   const add = (id, { revision, source, line, via, bare }) => {
     if (!id) return;
+    // A bare hosted-API model name reached us via an HF-shaped matcher (`model=`,
+    // from_pretrained). It is not an HF repo — reclassify to 'api' + provider so it
+    // is labeled correctly and skips the HF-Index lookup. See API_MODEL.
+    if (source === 'hf' && !id.includes('/') && API_MODEL.test(id)) {
+      source = 'api';
+      via = `${via} · ${apiProvider(id)} API`;
+    }
     if (source !== 'ollama' && !(bare ? validBareId(id) : looksLikeModelId(id))) return;
     const key = `${source}:${id}:${revision || ''}`;
     if (seen.has(key)) return;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shomra/agent",
-  "version": "0.2.12",
-  "description": "Shomra — a local-first security scanner and runtime firewall for AI agents, MCP servers, prompts, and models. Gates AI artifacts in your editor and CI.",
+  "version": "0.3.2",
+  "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": {
     "shomra": "./shomra.mjs"
@@ -19,6 +19,7 @@
     "code-sast.mjs",
     "model-refs.mjs",
     "ai-usage.mjs",
+    "design.mjs",
     "README.md",
     "LICENSE",
     "NOTICE"