@shomra/agent 0.2.9 → 0.2.11

package/ai-usage.mjs

@@ -0,0 +1,155 @@
+/**
+ * AI-USAGE inventory extractor (CLI port of the backend's checks/ai-usage.ts,
+ * kept in sync so both surfaces detect the same thing). Finds where a repo USES
+ * an LLM/AI provider in its own source — SDK imports + provider-specific call
+ * sites — so `shomra` can inventory "this code talks to OpenAI / a local model"
+ * as plain shadow-AI usage, independent of whether that usage is vulnerable.
+ *
+ * Dependency-free, line-oriented, low-false-positive: a provider is only claimed
+ * when a line either IMPORTS its SDK module or matches a provider-specific CALL
+ * signature — never from a bare mention of the word "openai" in prose.
+ */
+
+/** Human label per category — shared by the report + backend. */
+export const AI_USAGE_CATEGORY_LABEL = {
+  'llm-api': 'hosted LLM API',
+  'llm-framework': 'LLM framework',
+  'local-runtime': 'local model runtime',
+  'inference-gateway': 'inference gateway',
+};
+
+// The provider catalog — every entry is an LLM/AI *usage* surface.
+const PROVIDERS = [
+  { id: 'openai', label: 'OpenAI', category: 'llm-api', npm: ['openai'], npmPrefix: ['@azure/openai'], py: ['openai'],
+    call: [/\b(?:Async)?(?:Azure)?OpenAI\s*\(/, /\bchat\.completions\.create\s*\(/, /\bresponses\.create\s*\(/, /\bembeddings\.create\s*\(/, /\bChatCompletion\.create\s*\(/, /\bopenai\.(?:ChatCompletion|Completion|Embedding)\b/] },
+  { id: 'anthropic', label: 'Anthropic', category: 'llm-api', npm: ['@anthropic-ai/sdk', '@anthropic-ai/bedrock-sdk', '@anthropic-ai/vertex-sdk'], npmPrefix: ['@anthropic-ai/'], py: ['anthropic'],
+    call: [/\b(?:Async)?Anthropic(?:Bedrock|Vertex)?\s*\(/, /\bmessages\.create\s*\(/, /\bmessages\.stream\s*\(/] },
+  { id: 'google-gemini', label: 'Google Gemini', category: 'llm-api', npm: ['@google/generative-ai', '@google/genai'], py: ['google.generativeai', 'google.genai'], pyRoot: ['google.generativeai', 'google.genai'],
+    call: [/\bGenerativeModel\s*\(/, /\bgenerate_content\s*\(/, /\bgetGenerativeModel\s*\(/] },
+  { id: 'google-vertex', label: 'Google Vertex AI', category: 'llm-api', npm: ['@google-cloud/vertexai', '@google-cloud/aiplatform'], py: ['vertexai', 'google.cloud.aiplatform'], pyRoot: ['vertexai', 'google.cloud.aiplatform'],
+    call: [/\bTextGenerationModel\b/, /\bGenerativeModel\.from_pretrained\s*\(/] },
+  { id: 'aws-bedrock', label: 'AWS Bedrock', category: 'llm-api', npm: ['@aws-sdk/client-bedrock-runtime', '@aws-sdk/client-bedrock'],
+    call: [/\bbedrock[-_]?runtime\b/i, /\bBedrockRuntime(?:Client)?\b/, /\binvoke_model(?:_with_response_stream)?\s*\(/, /\bclient\s*\(\s*['"]bedrock/i] },
+  { id: 'cohere', label: 'Cohere', category: 'llm-api', npm: ['cohere-ai'], py: ['cohere'], call: [/\bcohere\.Client\w*\s*\(/, /\bClientV2\s*\(/] },
+  { id: 'mistral', label: 'Mistral', category: 'llm-api', npm: ['@mistralai/mistralai'], py: ['mistralai'], call: [/\bMistral(?:Client|AsyncClient|)\s*\(/, /\bchat\.complete\s*\(/] },
+  { id: 'groq', label: 'Groq', category: 'llm-api', npm: ['groq-sdk'], py: ['groq'], call: [/\bGroq\s*\(/] },
+  { id: 'together', label: 'Together AI', category: 'llm-api', npm: ['together-ai'], py: ['together'], call: [/\bTogether\s*\(/] },
+  { id: 'replicate', label: 'Replicate', category: 'llm-api', npm: ['replicate'], py: ['replicate'], call: [/\breplicate\.run\s*\(/, /\bReplicate\s*\(/] },
+  { id: 'huggingface-inference', label: 'Hugging Face Inference', category: 'llm-api', npm: ['@huggingface/inference'], py: ['huggingface_hub'], call: [/\bInferenceClient\s*\(/] },
+
+  { id: 'litellm', label: 'LiteLLM', category: 'inference-gateway', npm: ['litellm'], py: ['litellm'], call: [/\blitellm\.(?:a?completion|a?embedding)\s*\(/] },
+  { id: 'openrouter', label: 'OpenRouter', category: 'inference-gateway', npm: ['openrouter'], call: [/\bopenrouter\.ai\b/i] },
+  { id: 'vercel-ai', label: 'Vercel AI SDK', category: 'inference-gateway', npm: ['ai'], npmPrefix: ['@ai-sdk/'], call: [/\b(?:generateText|streamText|generateObject|streamObject)\s*\(/] },
+
+  { id: 'langchain', label: 'LangChain', category: 'llm-framework', npmPrefix: ['@langchain/'], npm: ['langchain'], pyRoot: ['langchain'], call: [/\bChat(?:OpenAI|Anthropic|Google\w*|Bedrock|Vertex\w*|Cohere|Mistral\w*)\s*\(/, /\bLLMChain\s*\(/, /\bChatPromptTemplate\b/] },
+  { id: 'langgraph', label: 'LangGraph', category: 'llm-framework', npm: ['@langchain/langgraph'], pyRoot: ['langgraph'], call: [/\bStateGraph\s*\(/] },
+  { id: 'llama-index', label: 'LlamaIndex', category: 'llm-framework', npmPrefix: ['@llamaindex/'], npm: ['llamaindex'], pyRoot: ['llama_index'], call: [/\bVectorStoreIndex\b/, /\bServiceContext\b/] },
+  { id: 'crewai', label: 'CrewAI', category: 'llm-framework', py: ['crewai'], pyRoot: ['crewai'], call: [/\bCrew\s*\(/, /\bAgent\s*\(\s*role\s*=/] },
+  { id: 'autogen', label: 'AutoGen', category: 'llm-framework', py: ['autogen', 'pyautogen'], pyRoot: ['autogen', 'autogen_agentchat'], call: [/\bAssistantAgent\s*\(/, /\bConversableAgent\s*\(/] },
+  { id: 'semantic-kernel', label: 'Semantic Kernel', category: 'llm-framework', py: ['semantic_kernel'], pyRoot: ['semantic_kernel'], npm: ['@microsoft/semantic-kernel'], call: [/\bKernel\.builder\b/] },
+  { id: 'haystack', label: 'Haystack', category: 'llm-framework', py: ['haystack'], pyRoot: ['haystack'], call: [/\bPipeline\s*\(\s*\)/] },
+  { id: 'dspy', label: 'DSPy', category: 'llm-framework', py: ['dspy'], pyRoot: ['dspy'], call: [/\bdspy\.(?:Predict|ChainOfThought|Signature)\b/] },
+  { id: 'guidance', label: 'Guidance', category: 'llm-framework', py: ['guidance'], call: [/\bguidance\.\w+/] },
+  { id: 'instructor', label: 'Instructor', category: 'llm-framework', py: ['instructor'], call: [/\binstructor\.(?:from_openai|patch|from_anthropic)\s*\(/] },
+  { id: 'pydantic-ai', label: 'PydanticAI', category: 'llm-framework', py: ['pydantic_ai'], pyRoot: ['pydantic_ai'], call: [/\bAgent\s*\(\s*['"]/] },
+
+  { id: 'ollama', label: 'Ollama', category: 'local-runtime', npm: ['ollama'], py: ['ollama'], call: [/\bollama\.(?:chat|generate|embeddings)\s*\(/] },
+  { id: 'transformers', label: 'Transformers', category: 'local-runtime', py: ['transformers'], pyRoot: ['transformers'], call: [/\bpipeline\s*\(/, /\bAutoModel\w*\.from_pretrained\s*\(/] },
+  { id: 'sentence-transformers', label: 'Sentence-Transformers', category: 'local-runtime', py: ['sentence_transformers'], call: [/\bSentenceTransformer\s*\(/] },
+  { id: 'vllm', label: 'vLLM', category: 'local-runtime', py: ['vllm'], call: [/\bLLM\s*\(\s*model\s*=/, /\bSamplingParams\s*\(/] },
+  { id: 'llama-cpp', label: 'llama.cpp', category: 'local-runtime', npm: ['node-llama-cpp'], py: ['llama_cpp'], call: [/\bLlama\s*\(\s*model_path\s*=/] },
+];
+
+const MODEL_ON_LINE = /\bmodel(?:_?id|_?name)?\s*[=:]\s*['"]([A-Za-z0-9][\w.:\/-]{1,80})['"]/;
+const MAX_CODE_LEN = 240;
+const clipLine = (s) => (s.length > MAX_CODE_LEN ? s.slice(0, MAX_CODE_LEN) + '…' : s);
+const SCAN_EXT = /\.(py|ipynb|[mc]?[jt]sx?|java|kt|go|rb|php|cs|rs|scala)$/i;
+export function isAiUsageScannable(file) {
+  return SCAN_EXT.test(String(file || ''));
+}
+
+function importSpecifiers(raw) {
+  const out = [];
+  for (const m of raw.matchAll(/(?:\bfrom\s+|\brequire\s*\(\s*|\bimport\s*\(\s*|\bimport\s+)['"]([^'"]+)['"]/g)) out.push(m[1]);
+  let pm = raw.match(/^\s*from\s+([A-Za-z_][\w.]*)\s+import\b/);
+  if (pm) out.push(pm[1]);
+  pm = raw.match(/^\s*import\s+([A-Za-z_][\w.]*(?:\s*,\s*[A-Za-z_][\w.]*)*)/);
+  if (pm) for (const mod of pm[1].split(',')) out.push(mod.trim());
+  return out;
+}
+
+function importMatches(spec, p) {
+  if (!spec) return false;
+  const s = spec.trim();
+  if (p.npm?.includes(s)) return true;
+  if (p.npmPrefix?.some((pre) => s === pre.replace(/\/$/, '') || s.startsWith(pre))) return true;
+  if (p.py?.includes(s)) return true;
+  if (p.pyRoot?.some((root) => s === root || s.startsWith(root + '.') || s.startsWith(root + '_'))) return true;
+  return false;
+}
+
+/** Extract AI-usage sightings from one source file's text. */
+export function scanAiUsage(text, file = '') {
+  if (!text || !isAiUsageScannable(file)) return [];
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const trimmed = raw.trim();
+    if (!trimmed) continue;
+    const ln = i + 1;
+    const isComment = trimmed.startsWith('#') || trimmed.startsWith('//') || trimmed.startsWith('*');
+    const specs = isComment ? [] : importSpecifiers(raw);
+    const modelOnLine = (raw.match(MODEL_ON_LINE) || [])[1];
+    const seenOnLine = new Set();
+    for (const p of PROVIDERS) {
+      const importedSpec = specs.find((s) => importMatches(s, p));
+      if (importedSpec) {
+        const key = `${p.id}:import`;
+        if (!seenOnLine.has(key)) {
+          seenOnLine.add(key);
+          out.push({ provider: p.id, label: p.label, category: p.category, kind: 'import', via: importedSpec, code: clipLine(trimmed), line: ln, file });
+        }
+      }
+      if (!isComment && p.call) {
+        const hit = p.call.find((re) => re.test(raw));
+        if (hit) {
+          const key = `${p.id}:call`;
+          if (!seenOnLine.has(key)) {
+            seenOnLine.add(key);
+            out.push({ provider: p.id, label: p.label, category: p.category, kind: 'call', via: (raw.match(hit) || [])[0] || p.label, code: clipLine(trimmed), ...(modelOnLine ? { model: modelOnLine } : {}), line: ln, file });
+          }
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** Cap on individual sites carried per provider row. */
+const MAX_SITES_PER_PROVIDER = 60;
+
+/** One inventory row per provider, aggregated across all files. */
+export function rollupAiUsage(usages) {
+  const byProvider = new Map();
+  for (const u of usages) {
+    let row = byProvider.get(u.provider);
+    if (!row) {
+      row = { provider: u.provider, label: u.label, category: u.category, files: [], firstSite: null, sites: [], models: [], sightings: 0, hasCallSite: false };
+      byProvider.set(u.provider, row);
+    }
+    row.sightings++;
+    if (!row.files.includes(u.file)) row.files.push(u.file);
+    if (u.model && !row.models.includes(u.model)) row.models.push(u.model);
+    if (u.kind === 'call') row.hasCallSite = true;
+    if (row.sites.length < MAX_SITES_PER_PROVIDER) {
+      row.sites.push({ file: u.file, line: u.line, kind: u.kind, via: u.via, ...(u.code ? { code: u.code } : {}), ...(u.model ? { model: u.model } : {}) });
+    }
+    const better = u.kind === 'call' && (!row.firstSite || row.firstSite.kind !== 'call');
+    if (!row.firstSite || better) row.firstSite = { file: u.file, line: u.line, via: u.via, kind: u.kind };
+  }
+  for (const row of byProvider.values()) {
+    row.sites.sort((a, b) => a.file.localeCompare(b.file) || (b.kind === 'call' ? 1 : 0) - (a.kind === 'call' ? 1 : 0) || a.line - b.line);
+  }
+  return [...byProvider.values()].sort((a, b) => a.label.localeCompare(b.label));
+}

package/code-sast.mjs

@@ -245,6 +245,25 @@ const PY_RULES = [
     remediation: 'Never set allow_dangerous_deserialization=True on an index you did not build. Rebuild the vector store from source documents in your own environment, or use a non-pickle store format.',
     cwe: 'CWE-502',
   },
+  {
+    id: 'python.mcp_client',
+    title: 'MCP client integration (untrusted tool-output ingress)',
+    // LOW capability twin of js.mcp_client: importing the MCP SDK client surface
+    // says this file acts as an MCP host that feeds server tool output to a model.
+    severity: 'LOW',
+    category: 'agentic',
+    confidence: 0.55,
+    // Precise: `mcp.client.*` and `from mcp.client…import` are unambiguous;
+    // `from mcp import` only counts WITH ClientSession (excludes server-authoring
+    // imports); bare ClientSession( is NOT matched (aiohttp.ClientSession FP).
+    re: /\bfrom\s+mcp\.client[\w.]*\s+import\b|\bimport\s+mcp\.client\b|\bmcp\.client\.\w+|\bfrom\s+mcp\s+import\b[^\n]*\bClientSession\b/,
+    codeOnly: true,
+    sink: (m) => m[0].trim(),
+    source: 'MCP server tool output',
+    message: 'Acts as an MCP client/host: opens a ClientSession to MCP servers and passes their tool descriptions and results back to a model. Every server it reaches is an untrusted-input ingress — a poisoned tool description or result can hijack the agent (prompt injection / tool poisoning).',
+    remediation: 'Pin exactly which MCP servers this client may connect to and run each through governance before trusting it. Treat all server output as untrusted data, never instructions, and screen it (runtime firewall) before it reaches the model.',
+    cwe: 'CWE-829',
+  },
   {
     id: 'python.reduce_payload',
     title: 'Custom __reduce__ (pickle RCE gadget)',
@@ -367,6 +386,25 @@ const JS_RULES = [
     remediation: 'Avoid shelling out. If unavoidable, use execFile with a fixed binary and an argument array (never a shell string), and validate every argument.',
     cwe: 'CWE-78',
   },
+  {
+    id: 'js.mcp_client',
+    title: 'MCP client integration (untrusted tool-output ingress)',
+    // LOW capability signal: the /client SDK entrypoint or a *ClientTransport says
+    // this file acts as an MCP host — it connects to servers and feeds their tool
+    // output to a model. That is the toxic-flow ingress; on its own it is a lead.
+    severity: 'LOW',
+    category: 'agentic',
+    confidence: 0.55,
+    // /client subpath + transport class names are unambiguous. `new Client(` is NOT
+    // matched — too many libs export a generic Client. Not codeOnly: the /client
+    // import path lives inside a require()/import string.
+    re: /@modelcontextprotocol\/sdk\/client|\b(StdioClientTransport|SSEClientTransport|StreamableHTTPClientTransport|WebSocketClientTransport)\b/,
+    sink: (m) => m[0].trim(),
+    source: 'MCP server tool output',
+    message: 'Acts as an MCP client/host: connects to MCP servers and passes their tool descriptions and results back to a model. Every server it reaches is an untrusted-input ingress — a poisoned tool description or result can hijack the agent (prompt injection / tool poisoning).',
+    remediation: 'Pin exactly which MCP servers this client may connect to and run each through governance before trusting it. Treat all server output as untrusted data, never instructions, and screen it (runtime firewall) before it reaches the model.',
+    cwe: 'CWE-829',
+  },
   {
     id: 'js.decode_and_run',
     title: 'Encoded payload decode-and-run',

package/discovery.mjs

@@ -20,6 +20,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { execFileSync } from 'node:child_process';
+import { scanAiUsage, rollupAiUsage, isAiUsageScannable, AI_USAGE_CATEGORY_LABEL } from './ai-usage.mjs';
 
 const HOME = os.homedir();
 const APPDATA = process.env.APPDATA || path.join(HOME, 'AppData', 'Roaming');
@@ -142,13 +143,17 @@ const isVectorIndex = (base) =>
   VECTOR_INDEX_BASENAMES.has(base.toLowerCase()) ||
   VECTOR_INDEX_EXTS.has((base.slice(base.lastIndexOf('.') + 1) || '').toLowerCase());
 
+/** Cap on SOURCE files collected for AI-usage-in-code scanning (bounded so a big
+ * monorepo can't turn the sweep into a full read of every .py/.ts on disk). */
+const MAX_SOURCE_FILES = 600;
+
 /**
  * One bounded breadth-first walk per root that collects every file of interest.
- * Returns { mcp:[], rules:[], manifests:[], env:[], vector:[] } absolute-path lists.
+ * Returns { mcp:[], rules:[], manifests:[], env:[], vector:[], source:[] } lists.
  * Depth- and count-limited so it never turns into a full-disk crawl.
  */
 function walkWorkspace(roots) {
-  const found = { mcp: [], rules: [], manifests: [], env: [], vector: [] };
+  const found = { mcp: [], rules: [], manifests: [], env: [], vector: [], source: [] };
   const seenDir = new Set();
   let budget = 40_000; // total directories visited across all roots
   const maxDepth = 6;
@@ -163,6 +168,9 @@ function walkWorkspace(roots) {
     } else if (MANIFEST_NAMES.has(base)) found.manifests.push({ file: full, parentBase });
     else if (isEnvFile(base)) found.env.push({ file: full, parentBase });
     else if (isVectorIndex(base)) found.vector.push({ file: full, parentBase });
+    // Application source — collected (capped) so discoverAiUsageInCode can find
+    // the LLM/AI providers this code actually calls, not just what a manifest declares.
+    else if (found.source.length < MAX_SOURCE_FILES && isAiUsageScannable(base)) found.source.push({ file: full, parentBase });
   };
 
   for (const root of roots) {
@@ -427,6 +435,117 @@ export function discoverAiDependencies(roots = [process.cwd()], files = null) {
   return assets;
 }
 
+// ── AI usage in code (SDK imports + provider call sites) ─────────
+// The dependency scan above sees which AI SDKs a manifest DECLARES; this sees
+// which LLM/AI providers the code actually CALLS (an `openai` import + a
+// `chat.completions.create`, a LangChain chain, `ollama.chat`) — the shadow-AI
+// usage a manifest can miss (a transitive dep, a vendored client) and can't
+// localize (which file, which model). Surfaced regardless of whether it is
+// vulnerable. One AI_TOOL asset per provider, category 'code-usage'.
+export function discoverAiUsageInCode(roots = [process.cwd()], files = null) {
+  const walk = files || walkWorkspace(roots);
+  const usages = [];
+  for (const { file } of walk.source || []) {
+    if (!isAiUsageScannable(path.basename(file))) continue;
+    const text = readText(file, 300_000);
+    if (text == null) continue;
+    for (const u of scanAiUsage(text, file)) usages.push(u);
+  }
+  const assets = [];
+  for (const row of rollupAiUsage(usages)) {
+    const site = row.firstSite;
+    assets.push({
+      type: 'AI_TOOL',
+      name: `${row.label} (in code)`,
+      identifier: `ai-usage:${row.provider}`,
+      vendor: 'ai-sdk',
+      metadata: {
+        category: 'code-usage',
+        provider: row.provider,
+        aiCategory: row.category,
+        aiCategoryLabel: AI_USAGE_CATEGORY_LABEL[row.category],
+        fileCount: row.files.length,
+        files: row.files.slice(0, 10),
+        models: row.models.slice(0, 10),
+        callSites: row.sightings,
+        hasCallSite: row.hasCallSite,
+        firstSite: site ? { file: site.file, line: site.line } : null,
+      },
+    });
+  }
+  return assets;
+}
+
+// ── MCP client / host SDK usage in code ──────────────────────────
+// A repo that depends on the MCP SDK acts as an MCP HOST: it connects out to MCP
+// servers and feeds their (untrusted) tool output back into a model — the
+// toxic-flow / lethal-trifecta ingress. This is distinct from the MCP SERVERS a
+// machine is CONFIGURED to launch (discoverMcpServers, keyed as servers) and from
+// generic AI SDKs (discoverAiDependencies): here the code itself is the client.
+// Manifest-level detection can't prove which SDK surface is used, so the on-disk
+// SAST rules (js.mcp_client / python.mcp_client) confirm the client role from
+// actual imports; this lens surfaces the dependency so shadow MCP hosts are seen.
+const NPM_MCP_CLIENT = new Set(['mcp-use', 'mcp-client']);
+const NPM_MCP_CLIENT_PREFIX = ['@modelcontextprotocol/', '@mastra/mcp', '@langchain/mcp'];
+const PY_MCP_CLIENT = ['mcp', 'fastmcp', 'mcp-use', 'mcpadapt', 'langchain-mcp-adapters'];
+
+function npmMcpClientDeps(pkg) {
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}), ...(pkg.peerDependencies || {}), ...(pkg.optionalDependencies || {}) };
+  const hits = [];
+  for (const name of Object.keys(deps)) {
+    if (NPM_MCP_CLIENT.has(name) || NPM_MCP_CLIENT_PREFIX.some((p) => name.startsWith(p))) hits.push(name);
+  }
+  return hits;
+}
+function pyMcpClientDeps(text) {
+  const hits = [];
+  for (const pkg of PY_MCP_CLIENT) {
+    const re = new RegExp(`(^|[^a-z0-9_.-])${pkg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^a-z0-9_.-]|$)`, 'im');
+    if (re.test(text)) hits.push(pkg);
+  }
+  return hits;
+}
+
+export function discoverMcpClients(roots = [process.cwd()], files = null) {
+  const walk = files || walkWorkspace(roots);
+  const byPkg = new Map(); // `${eco}:${pkg}` -> { pkg, eco, manifests:Set }
+  const add = (eco, pkg, manifest) => {
+    const key = `${eco}:${pkg}`;
+    if (!byPkg.has(key)) byPkg.set(key, { pkg, eco, manifests: new Set() });
+    byPkg.get(key).manifests.add(manifest);
+  };
+  for (const { file } of walk.manifests) {
+    const base = path.basename(file);
+    if (base === 'package.json') {
+      const json = readJson(file);
+      if (!json) continue;
+      for (const pkg of npmMcpClientDeps(json)) add('npm', pkg, file);
+    } else {
+      const text = readText(file, 100_000);
+      if (text == null) continue;
+      for (const pkg of pyMcpClientDeps(text)) add('pip', pkg, file);
+    }
+  }
+  const assets = [];
+  for (const { pkg, eco, manifests } of byPkg.values()) {
+    const list = [...manifests];
+    assets.push({
+      type: 'AI_TOOL',
+      name: `${pkg} (${eco})`,
+      identifier: `mcp-client:${eco}:${pkg}`,
+      vendor: 'mcp-client',
+      metadata: {
+        category: 'mcp-client',
+        ecosystem: eco,
+        package: pkg,
+        usedInProjects: list.length,
+        manifests: list.slice(0, 10),
+      },
+    });
+  }
+  return assets;
+}
+
 // ── API keys sitting in .env files ───────────────────────────────
 
 const KEY_NAME_VENDOR = {
@@ -792,6 +911,8 @@ export function discoverAll(roots = [process.cwd()], opts = {}) {
     ...discoverMcpServers(scanRoots, files),
     ...discoverRulesFiles(scanRoots, files),
     ...discoverAiDependencies(scanRoots, files),
+    ...discoverAiUsageInCode(scanRoots, files),
+    ...discoverMcpClients(scanRoots, files),
     ...discoverVectorStores(scanRoots, files),
     ...discoverDotenvKeys(scanRoots, files),
     ...discoverAiTools(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shomra/agent",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "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.",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "guard-signals.mjs",
     "code-sast.mjs",
     "model-refs.mjs",
+    "ai-usage.mjs",
     "README.md",
     "LICENSE",
     "NOTICE"

package/shomra.mjs

@@ -1656,6 +1656,108 @@ function printWhy(res) {
   console.log('');
 }
 
+// ── shomra provenance: which of these changed files did an AI agent write? ──
+//
+//   shomra provenance [--staged | --base main] [--trailer] [--fail-on-blocked] [--json]
+//
+// Every mutating tool call the runtime firewall screened was recorded with its
+// target path and ALLOW/FLAG/BLOCK decision. This joins a real git diff against
+// that record, so a commit can carry an EVIDENCE-BACKED statement of authorship
+// instead of a "Co-Authored-By" line anyone can type.
+//
+// ⚠ "Unattributed" means the firewall has no record — NOT that a human wrote it.
+// With the hook uninstalled every file is unattributed, so the output always
+// states its coverage and never claims human authorship. Don't rewrite that copy.
+
+/** All changed paths (not just AI artifacts) for provenance. */
+function gitChangedPaths(root, { staged, base }) {
+  const run = (args) => {
+    try {
+      return execSync(`git ${args}`, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).toString();
+    } catch {
+      return null;
+    }
+  };
+  let out = null;
+  if (staged) {
+    out = run('diff --cached --name-only --relative --diff-filter=ACM');
+  } else if (base) {
+    for (const b of [`origin/${base}`, base]) {
+      out = run(`diff --name-only --relative --diff-filter=ACM ${b}...HEAD`);
+      if (out !== null) break;
+    }
+  }
+  if (out === null) out = run('diff HEAD~1 --name-only --relative --diff-filter=ACM');
+  if (out === null) return null;
+  return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+async function cmdProvenance(flags, positional) {
+  const root = path.resolve(flags.path || positional[0] || '.');
+  const staged = !!flags.staged;
+  const base = flags.base || (staged ? null : process.env.GITHUB_BASE_REF || 'main');
+
+  const paths = gitChangedPaths(root, { staged, base });
+  if (paths === null) {
+    console.error(red('✗') + ' Not a git repository (or no diff available). Run inside a repo, or pass --base <ref>.');
+    process.exit(1);
+  }
+  if (!paths.length) {
+    if (flags.json) console.log(JSON.stringify({ files: [], agentAuthored: 0, coverage: 'NO_TELEMETRY', summary: 'no changed files' }, null, 2));
+    else console.log(green('\n  ✓ No changed files to attribute.\n'));
+    return;
+  }
+
+  const cfg = loadConfig();
+  const { apiKey, url } = resolveSettings(cfg);
+  let res;
+  try {
+    res = await api(url, apiKey, '/gate/provenance', {
+      paths,
+      repo: flags.repo || process.env.GITHUB_REPOSITORY || undefined,
+      sessionId: flags.session || undefined,
+      sinceHours: flags.since ? Number(flags.since) : undefined,
+    });
+  } catch (e) {
+    // Provenance is an evidence lookup, not a guard — a backend outage must not
+    // block a commit. Say so plainly instead of silently reporting "no agents".
+    console.error(yellow('!') + ` Provenance unavailable (${e.message}). Authorship not established.`);
+    process.exit(flags['fail-on-blocked'] ? 1 : 0);
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(res, null, 2));
+  } else if (flags.trailer) {
+    for (const t of res.trailers || []) console.log(t);
+  } else {
+    const noTel = res.coverage === 'NO_TELEMETRY';
+    console.log('');
+    console.log(`  ${bold('Commit provenance')} ${dim(`· ${res.files.length} changed file(s)`)}`);
+    console.log(`  ${noTel ? yellow('⚠ ' + res.summary) : res.summary}`);
+    if (noTel) {
+      console.log(dim('    No firewall telemetry for this range — this is NOT a claim that a human wrote them.'));
+      console.log(dim('    Install the runtime hook with ') + bold('shomra protect') + dim(' to attribute future work.'));
+    }
+    console.log('');
+    for (const f of res.files.slice(0, 40)) {
+      const tag =
+        f.authorship === 'AGENT' ? cyan('agent') : f.authorship === 'BLOCKED_ATTEMPT' ? red('blocked') : dim('unattributed');
+      const who = f.agents?.length ? dim(` ${f.agents.join(', ')}`) : '';
+      const amb = f.ambiguous ? yellow(' ~ambiguous') : '';
+      console.log(`    ${tag.padEnd(22)} ${f.path}${who}${amb}`);
+    }
+    if (res.files.length > 40) console.log(dim(`    …and ${res.files.length - 40} more`));
+    console.log('');
+  }
+
+  // A path the firewall BLOCKED that changed anyway is the signal worth failing
+  // on: either the guard was bypassed, or something wrote it outside the agent.
+  if (flags['fail-on-blocked'] && res.blockedAttempts > 0) {
+    console.error(red('✗') + ` ${res.blockedAttempts} file(s) the firewall blocked were modified anyway.`);
+    process.exit(1);
+  }
+}
+
 // ── shomra install-precommit: gate staged AI artifacts at commit time ──
 //
 //   shomra install-precommit [dir] [--force]
@@ -3951,6 +4053,7 @@ ${bold('COMMANDS')}
   ${cyan('init')}          Configure + enroll this machine       ${dim('--key shm_live_… [--url <backend>]')}
   ${cyan('protect')}       Wire the runtime firewall for every coding agent ${dim('[--local] [--force]')}
   ${cyan('install-hook')}  Wire the runtime firewall into ONE agent ${dim('[--agent claude|cursor|windsurf|gemini|codex|copilot|cline|aider|all] [--global]')}
+  ${cyan('provenance')}    Which changed files an AI agent wrote   ${dim('[--staged | --base main] [--trailer] [--fail-on-blocked] [--json]')}
   ${cyan('install-precommit')} Gate staged AI artifacts on git commit ${dim('[dir] [--force]')}
   ${cyan('doctor')}        ${bold('Am I safe?')} Posture of this machine's AI setup ${dim('[--json]')}
 
@@ -4163,6 +4266,7 @@ const COMMANDS = {
   baseline: (f, p) => cmdBaseline(f, p),
   fix: (f, p) => cmdFix(f, p),
   why: (f, p) => cmdWhy(f, p),
+  provenance: (f, p) => cmdProvenance(f, p),
   'install-precommit': (f, p) => cmdInstallPrecommit(f, p),
   'scan-zip': (f, p) => cmdScanZip(f, p),
   'model-scan': (f, p) => cmdModelScan(f, p),