brainblast 0.4.2 → 0.5.0

package/README.md

@@ -99,7 +99,8 @@ the applied changes.
 | Rule | What's wrong | Consequence |
 |------|--------------|-------------|
 | `env-secrets-committed` | A `.env*` file (not `.env.example`/`.sample`/`.template`) is tracked by git and contains a secret-shaped key (`SECRET`, `*_PRIVATE_KEY`, `*_API_KEY`, `*_TOKEN`, `*_PASSWORD`, etc.) with a real-looking (non-placeholder) value | Anyone with read access to the repo — including forks of a public repo — can read the live credential |
-| `env-secret-leaked-to-sink` | A secret-shaped `process.env.X` value (directly, via a local variable, or one hop through a same-file helper) is passed to `console.log`/`res.json`/`res.send`/etc. | Credentials end up in logs, error trackers, or API responses — readable by anyone with log/response access |
+| `env-secret-leaked-to-sink` | A secret-shaped `process.env.X` value flows — directly, via a local variable, forward through helper functions (same-file or imported from another file), or backward into a function that's called elsewhere in the project with a tainted argument — into `console.log`/`res.json`/`res.send`/etc., up to 2 hops across the whole project | Credentials end up in logs, error trackers, or API responses — readable by anyone with log/response access |
+| `request-input-command-injection` | Untrusted `req.body`/`req.query`/`req.params`/`req.headers` data flows — directly or across files — into `exec`/`execSync`/`spawn`/`spawnSync`/`execFile`/`execFileSync` | A malicious request can run arbitrary shell commands on the server |
 
 Each finding lands in `.agent-research/report.json` (stable `schemaVersion: "1.0"`)
 with a `checks[]` array a CI gate can read. Each confirmed FAIL ships a
@@ -183,7 +184,7 @@ All types are exported: `Rule`, `CheckResult`, `CostReport`, `AccountFlow`,
 
 ```sh
 npm install
-npm test         # unit suite (173 tests)
+npm test         # unit suite (214 tests)
 npm run prove    # end-to-end: generated tests RED on vulnerable, GREEN on fixed
 npm run build    # produce dist/ (the published artifact)
 ```

package/dist/{chunk-Q72MTJXQ.js → chunk-5LJXC66F.js}

@@ -487,7 +487,7 @@ var envSecretsCommitted = (c, p) => {
   return { result: "pass", detail: p.passDetail ?? "No committed secret-looking values found." };
 };
 
-// src/checkers/envTaintToSink.ts
+// src/checkers/taintToSink.ts
 import { SyntaxKind as SyntaxKind7 } from "ts-morph";
 function calleeName(call) {
   const exp = call.getExpression();
@@ -497,59 +497,65 @@ function calleeName(call) {
   }
   return "";
 }
-function envVarIn(text) {
-  const m = text.match(/process\.env\.([A-Za-z0-9_]+)/);
-  return m?.[1];
+function calleeIdentifierName(call) {
+  const exp = call.getExpression();
+  return exp.getKind() === SyntaxKind7.Identifier ? exp.getText() : void 0;
 }
 function wordIn(text, name) {
   return new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(text);
 }
-function findDirectLeak(fn, sinkCalls, secretKeyRe, taintedNames) {
+function matchesSource(text, sourceRes) {
+  return sourceRes.some((re) => re.test(text));
+}
+function localTaintedNames(fn, sourceRes) {
+  const names = /* @__PURE__ */ new Set();
+  for (const decl of fn.getDescendantsOfKind(SyntaxKind7.VariableDeclaration)) {
+    const init = decl.getInitializer();
+    if (init && matchesSource(init.getText(), sourceRes)) names.add(decl.getName());
+  }
+  return names;
+}
+function findDirectLeak(fn, sinkCalls, sourceRes, taintedNames) {
   for (const call of fn.getDescendantsOfKind(SyntaxKind7.CallExpression)) {
     const name = calleeName(call);
     if (!sinkCalls.has(name)) continue;
     for (const arg of call.getArguments()) {
       const text = arg.getText();
-      const envVar = envVarIn(text);
-      if (envVar && secretKeyRe.test(envVar)) {
-        return `process.env.${envVar} is passed directly to ${name}(...) \u2014 secret values must not be logged or returned to clients.`;
+      if (matchesSource(text, sourceRes)) {
+        return `'${text}' is passed directly to ${name}(...) \u2014 tainted values must not reach this sink.`;
       }
       for (const tv of taintedNames) {
         if (wordIn(text, tv)) {
-          return `'${tv}' (holding a secret-shaped process.env value) is passed to ${name}(...) \u2014 secret values must not be logged or returned to clients.`;
+          return `'${tv}' (a tainted value) is passed to ${name}(...) \u2014 tainted values must not reach this sink.`;
         }
       }
     }
   }
   return void 0;
 }
-var envTaintToSink = (c, p) => {
-  const sinkCalls = new Set(p.sinkCalls ?? []);
-  const secretKeyRe = new RegExp(p.secretKeyPattern, "i");
-  const fn = c.fn;
-  const taintedNames = /* @__PURE__ */ new Set();
-  for (const decl of fn.getDescendantsOfKind(SyntaxKind7.VariableDeclaration)) {
-    const init = decl.getInitializer();
-    if (!init) continue;
-    const envVar = envVarIn(init.getText());
-    if (envVar && secretKeyRe.test(envVar)) {
-      taintedNames.add(decl.getName());
-    }
+function resolveFunction(sourceFile, name) {
+  const local = sourceFile.getFunction(name);
+  if (local) return { fn: local, sf: sourceFile };
+  for (const imp of sourceFile.getImportDeclarations()) {
+    const named2 = imp.getNamedImports().find((ni) => (ni.getAliasNode()?.getText() ?? ni.getName()) === name);
+    if (!named2) continue;
+    const targetSf = imp.getModuleSpecifierSourceFile();
+    if (!targetSf) continue;
+    const targetFn = targetSf.getFunction(named2.getName());
+    if (targetFn) return { fn: targetFn, sf: targetSf };
   }
-  const direct = findDirectLeak(fn, sinkCalls, secretKeyRe, taintedNames);
-  if (direct) return { result: "fail", detail: direct };
-  const sourceFile = fn.getSourceFile();
+  return void 0;
+}
+function findForwardLeak(fn, rootName, sinkCalls, sourceRes, taintedNames, hopsLeft, visited) {
+  if (hopsLeft <= 0) return void 0;
   for (const call of fn.getDescendantsOfKind(SyntaxKind7.CallExpression)) {
-    const calleeExp = call.getExpression();
-    if (calleeExp.getKind() !== SyntaxKind7.Identifier) continue;
-    const calleeFnName = calleeExp.getText();
-    if (calleeFnName === (c.fnName ?? "")) continue;
+    const name = calleeIdentifierName(call);
+    if (!name || name === rootName) continue;
     const args = call.getArguments();
     const taintedArgIndices = [];
     args.forEach((arg, i) => {
       const text = arg.getText();
-      const envVar = envVarIn(text);
-      if (envVar && secretKeyRe.test(envVar)) {
+      if (matchesSource(text, sourceRes)) {
         taintedArgIndices.push(i);
         return;
       }
@@ -561,20 +567,99 @@ var envTaintToSink = (c, p) => {
       }
     });
     if (taintedArgIndices.length === 0) continue;
-    const calleeFn = sourceFile.getFunction(calleeFnName);
-    if (!calleeFn) continue;
-    const params = calleeFn.getParameters().map((pr) => pr.getName());
-    const calleeTainted = new Set(taintedArgIndices.map((i) => params[i]).filter((x) => !!x));
+    const resolved = resolveFunction(fn.getSourceFile(), name);
+    if (!resolved) continue;
+    const key = `${resolved.sf.getFilePath()}::${name}`;
+    if (visited.has(key)) continue;
+    visited.add(key);
+    const params = resolved.fn.getParameters().map((pr) => pr.getName());
+    const calleeTainted = new Set(
+      taintedArgIndices.map((i) => params[i]).filter((x) => !!x)
+    );
     if (calleeTainted.size === 0) continue;
-    const hop = findDirectLeak(calleeFn, sinkCalls, secretKeyRe, calleeTainted);
-    if (hop) {
-      return {
-        result: "fail",
-        detail: `A secret-shaped process.env value flows into '${calleeFnName}(...)' (called from '${c.fnName}'), where ${hop}`
-      };
+    const direct = findDirectLeak(resolved.fn, sinkCalls, sourceRes, calleeTainted);
+    if (direct) {
+      const where = resolved.sf === fn.getSourceFile() ? "" : ` (in ${resolved.sf.getFilePath()})`;
+      return `A tainted value flows into '${name}(...)'${where}, where ${direct}`;
+    }
+    const deeper = findForwardLeak(resolved.fn, rootName, sinkCalls, sourceRes, calleeTainted, hopsLeft - 1, visited);
+    if (deeper) return `via '${name}(...)': ${deeper}`;
+  }
+  return void 0;
+}
+function paramsUsedInSink(fn, sinkCalls) {
+  const params = new Set(fn.getParameters().map((p) => p.getName()));
+  const sinked = /* @__PURE__ */ new Set();
+  for (const call of fn.getDescendantsOfKind(SyntaxKind7.CallExpression)) {
+    if (!sinkCalls.has(calleeName(call))) continue;
+    for (const arg of call.getArguments()) {
+      const text = arg.getText();
+      for (const p of params) {
+        if (wordIn(text, p)) sinked.add(p);
+      }
+    }
+  }
+  return sinked;
+}
+function enclosingFunction(node) {
+  return node.getFirstAncestor(
+    (a) => a.getKind() === SyntaxKind7.FunctionDeclaration || a.getKind() === SyntaxKind7.ArrowFunction
+  );
+}
+function findBackwardLeak(candidateFn, fnName, candidateFile, params, sinkedParams, sourceRes) {
+  const project = candidateFn.getProject();
+  for (const sf of project.getSourceFiles()) {
+    for (const call of sf.getDescendantsOfKind(SyntaxKind7.CallExpression)) {
+      if (calleeIdentifierName(call) !== fnName) continue;
+      if (call.getFirstAncestor((a) => a === candidateFn)) continue;
+      const args = call.getArguments();
+      for (const pname of sinkedParams) {
+        const idx = params.indexOf(pname);
+        const arg = args[idx];
+        if (!arg) continue;
+        const text = arg.getText();
+        if (matchesSource(text, sourceRes)) {
+          return `'${fnName}' is called from ${sf.getFilePath()}:${call.getStartLineNumber()} with '${text}' as '${pname}', which this function passes to a sink.`;
+        }
+        if (arg.getKind() === SyntaxKind7.Identifier) {
+          const callerFn = enclosingFunction(arg);
+          if (callerFn) {
+            const callerTainted = localTaintedNames(callerFn, sourceRes);
+            if (callerTainted.has(text)) {
+              return `'${fnName}' is called from ${sf.getFilePath()}:${call.getStartLineNumber()} with '${text}' (a tainted value) as '${pname}', which this function passes to a sink.`;
+            }
+          }
+        }
+      }
     }
   }
-  return { result: "pass", detail: "No secret-shaped process.env value flows to a logging/response sink." };
+  return void 0;
+}
+var taintToSink = (c, p) => {
+  const sourceRes = p.sources.map((s) => new RegExp(s.pattern));
+  const sinkCalls = new Set(p.sinkCalls ?? []);
+  const maxHops = p.maxHops ?? 2;
+  const fn = c.fn;
+  const taintedNames = localTaintedNames(fn, sourceRes);
+  const direct = findDirectLeak(fn, sinkCalls, sourceRes, taintedNames);
+  if (direct) return { result: "fail", detail: direct };
+  const forward = findForwardLeak(fn, c.fnName, sinkCalls, sourceRes, taintedNames, maxHops, /* @__PURE__ */ new Set([
+    `${fn.getSourceFile().getFilePath()}::${c.fnName}`
+  ]));
+  if (forward) return { result: "fail", detail: forward };
+  const sinkedParams = paramsUsedInSink(fn, sinkCalls);
+  if (sinkedParams.size > 0) {
+    const backward = findBackwardLeak(
+      fn,
+      c.fnName,
+      c.filePath,
+      fn.getParameters().map((pr) => pr.getName()),
+      sinkedParams,
+      sourceRes
+    );
+    if (backward) return { result: "fail", detail: backward };
+  }
+  return { result: "pass", detail: "No tracked source value flows to a sink within the analyzed call graph." };
 };
 
 // src/checkers/index.ts
@@ -586,7 +671,7 @@ var registry = {
   "object-arg-property-literal-equals": objectArgPropertyLiteralEquals,
   "anchor-init-if-needed-guarded": anchorInitIfNeededGuarded,
   "env-secrets-committed": envSecretsCommitted,
-  "env-taint-to-sink": envTaintToSink
+  "taint-to-sink": taintToSink
 };
 function runChecker(kind, c, params) {
   const fn = registry[kind];
@@ -1401,63 +1486,113 @@ function loadRules(dir) {
   return rules2;
 }
 
+// src/packs.ts
+import { existsSync, readdirSync as readdirSync4, readFileSync as readFileSync5, statSync as statSync3 } from "fs";
+import { join as join5 } from "path";
+import { parse as parse2 } from "yaml";
+var PACK_MANIFEST_FILE = "brainblast-pack.yaml";
+function validatePackManifest(m, file) {
+  const errs = [];
+  if (!m || typeof m !== "object") {
+    throw new Error(`invalid pack manifest in ${file}: not a mapping`);
+  }
+  if (!m.id || typeof m.id !== "string") errs.push("missing id");
+  if (!m.name || typeof m.name !== "string") errs.push("missing name");
+  if (!m.version || typeof m.version !== "string") errs.push("missing version");
+  if (!m.author || typeof m.author !== "string") errs.push("missing author");
+  if (errs.length) throw new Error(`invalid pack manifest in ${file}: ${errs.join("; ")}`);
+}
+function loadPack(dir) {
+  const manifestPath = join5(dir, PACK_MANIFEST_FILE);
+  const raw = parse2(readFileSync5(manifestPath, "utf8"));
+  validatePackManifest(raw, manifestPath);
+  const manifest = raw;
+  const rulesDir = join5(dir, "rules");
+  const rules2 = existsSync(rulesDir) ? loadRules(rulesDir).map((r) => ({
+    ...r,
+    pack: { id: manifest.id, version: manifest.version, author: manifest.author }
+  })) : [];
+  return { manifest, rules: rules2 };
+}
+function loadPacksFromDir(packsDir) {
+  if (!existsSync(packsDir)) return [];
+  const out = [];
+  for (const entry of readdirSync4(packsDir).sort()) {
+    const dir = join5(packsDir, entry);
+    if (!statSync3(dir).isDirectory()) continue;
+    if (!existsSync(join5(dir, PACK_MANIFEST_FILE))) continue;
+    out.push(loadPack(dir));
+  }
+  return out;
+}
+
 // rules/index.ts
-import { existsSync } from "fs";
-import { dirname, join as join5 } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { dirname, join as join6 } from "path";
 import { fileURLToPath } from "url";
 function bundledRulesDir() {
   const here = dirname(fileURLToPath(import.meta.url));
-  if (existsSync(join5(here, "stripe-webhook-raw-body.yaml"))) return here;
-  const sub = join5(here, "rules");
-  if (existsSync(join5(sub, "stripe-webhook-raw-body.yaml"))) return sub;
+  if (existsSync2(join6(here, "stripe-webhook-raw-body.yaml"))) return here;
+  const sub = join6(here, "rules");
+  if (existsSync2(join6(sub, "stripe-webhook-raw-body.yaml"))) return sub;
   return here;
 }
 var rules = loadRules(bundledRulesDir());
 
 // src/resolveRules.ts
-import { existsSync as existsSync2 } from "fs";
-import { join as join6 } from "path";
-function resolveRules(targetDir) {
+import { existsSync as existsSync3 } from "fs";
+import { join as join7 } from "path";
+function resolveRules(targetDir, extraPackDirs = []) {
   const all = [...rules];
-  const projDir = join6(targetDir, ".agent-research", "rules");
-  if (existsSync2(projDir)) {
-    const seen = new Set(all.map((r) => r.id));
-    for (const r of loadRules(projDir)) {
+  const seen = new Set(all.map((r) => r.id));
+  const addRules = (rules2, sourceLabel) => {
+    for (const r of rules2) {
       if (seen.has(r.id)) {
-        console.warn(`brainblast: project rule '${r.id}' shadows a bundled rule; keeping bundled.`);
+        console.warn(`brainblast: rule '${r.id}' from ${sourceLabel} shadows an existing rule; keeping the first one loaded.`);
         continue;
       }
       all.push(r);
       seen.add(r.id);
     }
+  };
+  const projDir = join7(targetDir, ".agent-research", "rules");
+  if (existsSync3(projDir)) {
+    addRules(loadRules(projDir), "project rules");
+  }
+  for (const { manifest, rules: rules2 } of loadPacksFromDir(join7(targetDir, ".agent-research", "packs"))) {
+    addRules(rules2, `pack '${manifest.id}'`);
+  }
+  for (const dir of extraPackDirs) {
+    const { manifest, rules: rules2 } = loadPack(dir);
+    addRules(rules2, `pack '${manifest.id}' (${dir})`);
   }
   return all;
 }
 
 // src/trustGraph/directory.ts
-import { readFileSync as readFileSync5, existsSync as existsSync3 } from "fs";
+import { readFileSync as readFileSync6, existsSync as existsSync4 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { join as join7 } from "path";
-import { parse as parse2 } from "yaml";
+import { join as join8 } from "path";
+import { parse as parse3 } from "yaml";
 var cache = null;
 function bundledPath() {
   const here = fileURLToPath2(new URL(".", import.meta.url));
   const candidates = [
-    join7(here, "programs", "directory.yaml"),
+    join8(here, "programs", "directory.yaml"),
     // dist/programs/directory.yaml
-    join7(here, "..", "..", "programs", "directory.yaml"),
+    join8(here, "..", "..", "programs", "directory.yaml"),
     // src/../../programs/
-    join7(here, "..", "programs", "directory.yaml")
+    join8(here, "..", "programs", "directory.yaml")
     // fallback
   ];
   for (const c of candidates) {
-    if (existsSync3(c)) return c;
+    if (existsSync4(c)) return c;
   }
   return candidates[0];
 }
 function loadDirectory(path = bundledPath()) {
   if (cache && path === bundledPath()) return cache;
-  const raw = parse2(readFileSync5(path, "utf8"));
+  const raw = parse3(readFileSync6(path, "utf8"));
   if (!raw || !Array.isArray(raw.programs)) {
     throw new Error(`invalid program directory at ${path}: missing 'programs' array`);
   }
@@ -1528,23 +1663,23 @@ function isValidSolanaAddress(s) {
 }
 
 // src/trustGraph/programCache.ts
-import { readFileSync as readFileSync6, writeFileSync, mkdirSync, existsSync as existsSync4 } from "fs";
-import { join as join8, dirname as dirname2 } from "path";
+import { readFileSync as readFileSync7, writeFileSync, mkdirSync, existsSync as existsSync5 } from "fs";
+import { join as join9, dirname as dirname2 } from "path";
 import { homedir } from "os";
 var DEFAULT_TTL_HOURS = 168;
 var SCHEMA_VERSION = "1.0";
 function defaultCachePath() {
   const envOverride = process.env["BRAINBLAST_CACHE_PATH"];
-  return envOverride ?? join8(homedir(), ".brainblast", "program-cache.json");
+  return envOverride ?? join9(homedir(), ".brainblast", "program-cache.json");
 }
 function emptyCache() {
   return { schemaVersion: SCHEMA_VERSION, entries: {} };
 }
 function loadProgramCache(cachePath) {
   const path = cachePath ?? defaultCachePath();
-  if (!existsSync4(path)) return emptyCache();
+  if (!existsSync5(path)) return emptyCache();
   try {
-    const raw = JSON.parse(readFileSync6(path, "utf8"));
+    const raw = JSON.parse(readFileSync7(path, "utf8"));
     if (raw?.schemaVersion !== SCHEMA_VERSION) {
       return emptyCache();
     }
@@ -2121,7 +2256,7 @@ function startWatch(targetDir, opts = {}) {
 }
 
 // src/fixers/applyDiff.ts
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync2 } from "fs";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync2 } from "fs";
 function parseDiff(diff) {
   const lines = diff.split("\n");
   const fileLine = lines.find((l) => l.startsWith("+++ b"));
@@ -2138,7 +2273,7 @@ function parseDiff(diff) {
 }
 function applyDiffToFile(diff) {
   const { filePath, oldStart, oldCount, newLines } = parseDiff(diff);
-  const content = readFileSync7(filePath, "utf8");
+  const content = readFileSync8(filePath, "utf8");
   const fileLines = content.split("\n");
   const removedLines = diff.split("\n").filter((l) => l.startsWith("-") && !l.startsWith("---")).map((l) => l.slice(1));
   const actual = fileLines.slice(oldStart - 1, oldStart - 1 + oldCount);
@@ -2148,6 +2283,156 @@ function applyDiffToFile(diff) {
   return true;
 }
 
+// src/pack.ts
+import { existsSync as existsSync6, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
+import { join as join10 } from "path";
+function initPack(dir, opts) {
+  if (existsSync6(join10(dir, PACK_MANIFEST_FILE))) {
+    throw new Error(`${dir} already contains a ${PACK_MANIFEST_FILE}`);
+  }
+  const manifest = {
+    id: opts.id,
+    name: opts.name ?? opts.id,
+    version: opts.version ?? "0.1.0",
+    author: opts.author ?? "unknown",
+    ...opts.description ? { description: opts.description } : {}
+  };
+  mkdirSync2(dir, { recursive: true });
+  mkdirSync2(join10(dir, "rules"), { recursive: true });
+  mkdirSync2(join10(dir, "fixtures"), { recursive: true });
+  const manifestYaml = [
+    `id: ${manifest.id}`,
+    `name: ${manifest.name}`,
+    `version: ${manifest.version}`,
+    `author: ${manifest.author}`,
+    ...manifest.description ? [`description: ${manifest.description}`] : [],
+    ""
+  ].join("\n");
+  const manifestFile = join10(dir, PACK_MANIFEST_FILE);
+  writeFileSync3(manifestFile, manifestYaml, "utf8");
+  return manifestFile;
+}
+function validatePack(dir) {
+  const { manifest, rules: rules2 } = loadPack(dir);
+  const fixturesRoot = join10(dir, "fixtures");
+  const ruleResults = rules2.map((rule) => {
+    const ruleFixturesDir = join10(fixturesRoot, rule.id);
+    const vulnerableDir = join10(ruleFixturesDir, "vulnerable");
+    const fixedDir = join10(ruleFixturesDir, "fixed");
+    if (!existsSync6(vulnerableDir) || !existsSync6(fixedDir)) {
+      return {
+        ruleId: rule.id,
+        status: "missing-fixtures",
+        detail: `no fixtures/${rule.id}/{vulnerable,fixed}/ directory \u2014 prove gate skipped`
+      };
+    }
+    const redChecks = auditWithRule(vulnerableDir, rule);
+    const redFails = redChecks.filter((c) => c.result === "fail");
+    if (redFails.length === 0) {
+      return {
+        ruleId: rule.id,
+        status: "red-failed",
+        detail: `expected at least one FAIL against fixtures/${rule.id}/vulnerable/, got none`
+      };
+    }
+    const greenChecks = auditWithRule(fixedDir, rule);
+    const greenFails = greenChecks.filter((c) => c.result === "fail");
+    if (greenFails.length > 0) {
+      return {
+        ruleId: rule.id,
+        status: "green-failed",
+        detail: `expected no FAIL against fixtures/${rule.id}/fixed/, got ${greenFails.length}`
+      };
+    }
+    return { ruleId: rule.id, status: "ok", detail: "RED -> GREEN proven" };
+  });
+  const ok = ruleResults.every((r) => r.status === "ok" || r.status === "missing-fixtures");
+  return { manifest, rules: rules2, ruleResults, ok };
+}
+
+// src/telemetry.ts
+import { createHash, randomUUID } from "crypto";
+import { appendFileSync, existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
+import { execFileSync as execFileSync3 } from "child_process";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname3, join as join11, resolve } from "path";
+function sha256Hex(s) {
+  return createHash("sha256").update(s).digest("hex");
+}
+function isTelemetryEnabled(targetDir) {
+  const env = process.env.BRAINBLAST_TELEMETRY;
+  if (env === "1" || env === "true") return true;
+  if (env === "0" || env === "false") return false;
+  const configPath = join11(targetDir, ".agent-research", "config.json");
+  if (!existsSync7(configPath)) return false;
+  try {
+    const cfg = JSON.parse(readFileSync9(configPath, "utf8"));
+    return cfg?.telemetry === true;
+  } catch {
+    return false;
+  }
+}
+function getUserHash() {
+  const idPath = join11(homedir2(), ".brainblast", "telemetry-id");
+  let id;
+  if (existsSync7(idPath)) {
+    id = readFileSync9(idPath, "utf8").trim();
+  } else {
+    id = randomUUID();
+    mkdirSync3(dirname3(idPath), { recursive: true });
+    writeFileSync4(idPath, id, "utf8");
+  }
+  return sha256Hex(id).slice(0, 16);
+}
+function getRepoHash(targetDir) {
+  let key = "";
+  try {
+    key = execFileSync3("git", ["config", "--get", "remote.origin.url"], {
+      cwd: targetDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+  }
+  if (!key) key = resolve(targetDir);
+  return sha256Hex(key).slice(0, 16);
+}
+function telemetryFilePath(targetDir) {
+  return join11(targetDir, ".agent-research", "telemetry.ndjson");
+}
+var DEFAULT_REGISTRY_URL = "https://registry.brainblast.tech";
+async function submitTelemetry(targetDir, registryUrl = process.env.BRAINBLAST_REGISTRY_URL || DEFAULT_REGISTRY_URL) {
+  const file = telemetryFilePath(targetDir);
+  if (!existsSync7(file)) {
+    return { submitted: 0, accepted: 0, rejected: 0, graduations: [] };
+  }
+  const events = readFileSync9(file, "utf8").trim().split("\n").filter(Boolean).map((line) => JSON.parse(line));
+  if (events.length === 0) {
+    return { submitted: 0, accepted: 0, rejected: 0, graduations: [] };
+  }
+  const res = await fetch(`${registryUrl.replace(/\/$/, "")}/api/telemetry`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ events })
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`telemetry submit failed: ${res.status} ${res.statusText} ${body}`.trim());
+  }
+  const json = await res.json();
+  return { submitted: events.length, ...json };
+}
+function recordGraduationEvents(targetDir, events) {
+  if (events.length === 0) return;
+  const file = telemetryFilePath(targetDir);
+  mkdirSync3(dirname3(file), { recursive: true });
+  const repo_hash = getRepoHash(targetDir);
+  const user_hash = getUserHash();
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const lines = events.map((e) => JSON.stringify({ ...e, repo_hash, user_hash, timestamp })).join("\n");
+  appendFileSync(file, lines + "\n", "utf8");
+}
+
 export {
   findCandidates,
   findConfigCandidates,
@@ -2162,6 +2447,10 @@ export {
   renderTest,
   testKinds,
   loadRules,
+  PACK_MANIFEST_FILE,
+  validatePackManifest,
+  loadPack,
+  loadPacksFromDir,
   rules,
   resolveRules,
   loadDirectory,
@@ -2186,5 +2475,14 @@ export {
   runIncrementalScan,
   startWatch,
   parseDiff,
-  applyDiffToFile
+  applyDiffToFile,
+  initPack,
+  validatePack,
+  isTelemetryEnabled,
+  getUserHash,
+  getRepoHash,
+  telemetryFilePath,
+  DEFAULT_REGISTRY_URL,
+  submitTelemetry,
+  recordGraduationEvents
 };

package/dist/cli.js

@@ -7,14 +7,20 @@ import {
   cacheSize,
   defaultCachePath,
   getChangedRanges,
+  initPack,
+  isTelemetryEnabled,
   isValidSolanaAddress,
   loadProgramCache,
   parseDiff,
+  recordGraduationEvents,
   renderCostReportMd,
   renderTrustGraphMd,
   resolveRules,
-  startWatch
-} from "./chunk-Q72MTJXQ.js";
+  startWatch,
+  submitTelemetry,
+  telemetryFilePath,
+  validatePack
+} from "./chunk-5LJXC66F.js";
 
 // src/cli.ts
 import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
@@ -94,10 +100,25 @@ function updateMemory(memory, checks2, now = /* @__PURE__ */ new Date()) {
 // src/cli.ts
 import { execFileSync } from "child_process";
 var args = process.argv.slice(2);
+function parsePackDirs(argv) {
+  const idx = argv.indexOf("--packs");
+  if (idx < 0) return [];
+  const value = argv[idx + 1];
+  if (!value || value.startsWith("--")) return [];
+  return value.split(",").map((s) => s.trim()).filter(Boolean);
+}
 if (args[0] === "trust-graph") {
   await runTrustGraph(args.slice(1));
   process.exit(0);
 }
+if (args[0] === "pack") {
+  runPack(args.slice(1));
+  process.exit(0);
+}
+if (args[0] === "telemetry") {
+  await runTelemetry(args.slice(1));
+  process.exit(0);
+}
 if (args[0] === "watch") {
   const watchDir = args.find((a, i) => i > 0 && !a.startsWith("--")) ?? process.cwd();
   startWatch(watchDir);
@@ -119,7 +140,7 @@ if (sinceIdx >= 0 && !since) {
   console.error("error: --since requires a <ref> argument, e.g. --since origin/main");
   process.exit(2);
 }
-var rules = resolveRules(targetDir);
+var rules = resolveRules(targetDir, parsePackDirs(args));
 var changedRanges;
 if (since) {
   try {
@@ -211,6 +232,75 @@ if (ci) {
   const gateFail = fails > 0 || strict && cantTell > 0;
   process.exit(gateFail ? 1 : 0);
 }
+function runPack(argv) {
+  const sub = argv[0];
+  if (sub === "init") {
+    const dir = argv.find((a, i) => i > 0 && !a.startsWith("--") && argv[i - 1] !== "--id" && argv[i - 1] !== "--name" && argv[i - 1] !== "--author" && argv[i - 1] !== "--version" && argv[i - 1] !== "--description");
+    const flag = (name) => {
+      const idx = argv.indexOf(`--${name}`);
+      return idx >= 0 ? argv[idx + 1] : void 0;
+    };
+    const id = flag("id");
+    if (!dir || !id) {
+      console.error("usage: brainblast pack init <dir> --id <pack-id> [--name <name>] [--author <author>] [--version <semver>] [--description <text>]");
+      process.exit(2);
+    }
+    const manifestFile = initPack(dir, {
+      id,
+      name: flag("name"),
+      author: flag("author"),
+      version: flag("version"),
+      description: flag("description")
+    });
+    console.log(`brainblast pack init: wrote ${manifestFile}`);
+    console.log(`  rules:    ${join2(dir, "rules")}/`);
+    console.log(`  fixtures: ${join2(dir, "fixtures")}/`);
+    return;
+  }
+  if (sub === "validate") {
+    const dir = argv.find((a, i) => i > 0 && !a.startsWith("--"));
+    if (!dir) {
+      console.error("usage: brainblast pack validate <dir>");
+      process.exit(2);
+    }
+    const result = validatePack(dir);
+    console.log(`pack: ${result.manifest.id} v${result.manifest.version} (${result.manifest.author})`);
+    console.log(`  ${result.rules.length} rule(s)`);
+    for (const r of result.ruleResults) {
+      const marker = r.status === "ok" ? "OK" : r.status === "missing-fixtures" ? "WARN" : "FAIL";
+      console.log(`  [${marker}] ${r.ruleId}: ${r.detail}`);
+    }
+    process.exit(result.ok ? 0 : 1);
+  }
+  console.error("usage: brainblast pack <init|validate> ...");
+  process.exit(2);
+}
+async function runTelemetry(argv) {
+  const sub = argv[0];
+  if (sub !== "submit") {
+    console.error("usage: brainblast telemetry submit [targetDir]");
+    process.exit(2);
+  }
+  const targetDir2 = argv.find((a, i) => i > 0 && !a.startsWith("--")) ?? process.cwd();
+  try {
+    const result = await submitTelemetry(targetDir2);
+    if (result.submitted === 0) {
+      console.log(`brainblast telemetry submit: no events to submit (${telemetryFilePath(targetDir2)} is empty or missing)`);
+      return;
+    }
+    console.log(`brainblast telemetry submit: sent ${result.submitted} event(s) \u2014 ${result.accepted} accepted, ${result.rejected} rate-limited`);
+    for (const g of result.graduations) {
+      if (g.graduated) {
+        console.log(`  [GRADUATED] ${g.pack_id}/${g.rule_id}  (${g.distinct_pairs} distinct repo/user pairs)`);
+      } else {
+        console.log(`  [PROGRESS]  ${g.pack_id}/${g.rule_id}  ${g.distinct_pairs}/5 distinct repo/user pairs`);
+      }
+    }
+  } catch (e) {
+    console.error(`brainblast telemetry submit: ${e.message ?? String(e)}`);
+    process.exit(1);
+  }
+}
 async function runTrustGraph(argv) {
   const rpcIdx = argv.indexOf("--rpc");
   const rpcUrl = rpcIdx >= 0 ? argv[rpcIdx + 1] : void 0;
@@ -248,7 +338,7 @@ async function runFix(argv) {
   const apply = argv.includes("--apply");
   const branch = argv.includes("--branch");
   const targetDir2 = argv.find((a) => !a.startsWith("--")) ?? process.cwd();
-  const rules2 = resolveRules(targetDir2);
+  const rules2 = resolveRules(targetDir2, parsePackDirs(argv));
   const { checks: before } = audit(targetDir2, rules2);
   const fixable = before.filter((c) => c.result === "fail" && c.fix?.diff);
   if (fixable.length === 0) {
@@ -300,6 +390,15 @@ Warning: ${stillFailing.length} fix(es) applied but the rule still fails:`);
   } else if (applied > 0) {
     console.log("All applied fixes now pass (or cant_tell) on re-audit. \u2713");
   }
+  if (isTelemetryEnabled(targetDir2)) {
+    const graduated = fixable.filter((c) => !stillFailing.includes(c));
+    const events = graduated.map((c) => rules2.find((r) => r.id === c.ruleId)).filter((r) => !!r?.pack).map((r) => ({ pack_id: r.pack.id, rule_id: r.id }));
+    if (events.length > 0) {
+      recordGraduationEvents(targetDir2, events);
+      console.log(`
+Telemetry: recorded ${events.length} graduation event(s) to ${telemetryFilePath(targetDir2)}`);
+    }
+  }
   if (branch && applied > 0) {
     const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
     const branchName = `brainblast/auto-fix-${ts}`;

package/dist/index.d.ts

@@ -156,6 +156,23 @@ interface Rule {
         kind: string;
         params?: Record<string, any>;
     };
+    /**
+     * Provenance for rules loaded from a third-party rule pack (see
+     * src/packs.ts). Absent for bundled rules. Stamped by the pack loader from
+     * the pack's brainblast-pack.yaml manifest, not set by the rule author.
+     */
+    pack?: {
+        id: string;
+        version: string;
+        author?: string;
+    };
+}
+interface PackManifest {
+    id: string;
+    name: string;
+    version: string;
+    author: string;
+    description?: string;
 }
 type Checker = (candidate: Candidate, params: any) => CheckOutcome;
 type RustChecker = (candidate: RustCandidate, params: any) => CheckOutcome;
@@ -224,7 +241,7 @@ declare function audit(targetDir: string, rules: Rule[], changedRanges?: Changed
     };
 };
 
-declare function resolveRules(targetDir: string): Rule[];
+declare function resolveRules(targetDir: string, extraPackDirs?: string[]): Rule[];
 
 declare function loadRules(dir: string): Rule[];
 
@@ -285,6 +302,70 @@ interface ParsedDiff {
 declare function parseDiff(diff: string): ParsedDiff;
 declare function applyDiffToFile(diff: string): boolean;
 
+declare const PACK_MANIFEST_FILE = "brainblast-pack.yaml";
+declare function validatePackManifest(m: any, file: string): void;
+declare function loadPack(dir: string): {
+    manifest: PackManifest;
+    rules: Rule[];
+};
+declare function loadPacksFromDir(packsDir: string): {
+    manifest: PackManifest;
+    rules: Rule[];
+}[];
+
+interface PackInitOptions {
+    id: string;
+    name?: string;
+    author?: string;
+    version?: string;
+    description?: string;
+}
+declare function initPack(dir: string, opts: PackInitOptions): string;
+interface PackValidateResult {
+    manifest: PackManifest;
+    rules: Rule[];
+    /** Per-rule prove-gate results. */
+    ruleResults: PackRuleValidation[];
+    /** True if the manifest is valid, every rule loaded cleanly, and every rule with fixtures passed RED->GREEN. */
+    ok: boolean;
+}
+interface PackRuleValidation {
+    ruleId: string;
+    /** "ok" | "missing-fixtures" | "red-failed" | "green-failed" */
+    status: "ok" | "missing-fixtures" | "red-failed" | "green-failed";
+    detail: string;
+}
+declare function validatePack(dir: string): PackValidateResult;
+
+interface GraduationEvent {
+    pack_id: string;
+    rule_id: string;
+    repo_hash: string;
+    user_hash: string;
+    timestamp: string;
+}
+declare function isTelemetryEnabled(targetDir: string): boolean;
+declare function getUserHash(): string;
+declare function getRepoHash(targetDir: string): string;
+declare function telemetryFilePath(targetDir: string): string;
+declare const DEFAULT_REGISTRY_URL = "https://registry.brainblast.tech";
+interface TelemetrySubmitResult {
+    submitted: number;
+    accepted: number;
+    rejected: number;
+    graduations: {
+        pack_id: string;
+        rule_id: string;
+        distinct_pairs: number;
+        graduated: boolean;
+    }[];
+}
+declare function submitTelemetry(targetDir: string, registryUrl?: string): Promise<TelemetrySubmitResult>;
+declare function recordGraduationEvents(targetDir: string, events: {
+    pack_id: string;
+    rule_id: string;
+}[]): void;
+
 type UpgradeAuthorityKind = "renounced" | "single-key" | "multisig" | "dao" | "unknown";
 type UpgradeAuthoritySource = "directory" | "rpc" | "research";
 interface UpgradeAuthority {
@@ -414,4 +495,4 @@ declare function isEntryExpired(entry: ProgramCacheEntry, ttlHoursOverride?: num
  */
 declare function cacheSize(cache: ProgramCache, ttlHoursOverride?: number): number;
 
-export { type AccountFlow, type AuditRef, type BuildOpts, type Candidate, type ChangedRanges, type CheckOutcome, type CheckResult, type CheckResultKind, type Checker, type ConfigCandidate, type ConfigChecker, type CostReport, DEFAULT_TTL_HOURS, type OnChainProgram, type ParityNote, type ParsedDiff, type PriorityFeePosture, type ProgramCache, type ProgramCacheEntry, type Recoverability, type Rule, type RustAccountField, type RustCandidate, type RustChecker, type Severity, type TrustGraph, type UpgradeAuthority, type UpgradeAuthorityKind, type UpgradeAuthoritySource, type VerifiedBuildState, type WatchEvent, type WatchOptions, analyzeCosts, applyDiffToFile, audit, auditWithRule, base58Decode, base58Encode, buildTrustGraph, rules as bundledRules, cacheSize, checkerKinds, defaultCachePath, fileChanged, findCandidates, findConfigCandidates, generateTestForResult, getCacheEntry, getCacheEntryMeta, getChangedRanges, getWorkingTreeChanges, isEntryExpired, isValidSolanaAddress, lamportsToSol, loadDirectory, loadProgramCache, loadRules, parseDiff, putCacheEntry, rangeChanged, renderCostReportMd, renderTest, renderTrustGraphMd, rentExemptMinimum, resolveRules, runChecker, runIncrementalScan, saveProgramCache, startWatch, testKinds };
+export { type AccountFlow, type AuditRef, type BuildOpts, type Candidate, type ChangedRanges, type CheckOutcome, type CheckResult, type CheckResultKind, type Checker, type ConfigCandidate, type ConfigChecker, type CostReport, DEFAULT_REGISTRY_URL, DEFAULT_TTL_HOURS, type GraduationEvent, type OnChainProgram, PACK_MANIFEST_FILE, type PackInitOptions, type PackManifest, type PackRuleValidation, type PackValidateResult, type ParityNote, type ParsedDiff, type PriorityFeePosture, type ProgramCache, type ProgramCacheEntry, type Recoverability, type Rule, type RustAccountField, type RustCandidate, type RustChecker, type Severity, type TelemetrySubmitResult, type TrustGraph, type UpgradeAuthority, type UpgradeAuthorityKind, type UpgradeAuthoritySource, type VerifiedBuildState, type WatchEvent, type WatchOptions, analyzeCosts, applyDiffToFile, audit, auditWithRule, base58Decode, base58Encode, buildTrustGraph, rules as bundledRules, cacheSize, checkerKinds, defaultCachePath, fileChanged, findCandidates, findConfigCandidates, generateTestForResult, getCacheEntry, getCacheEntryMeta, getChangedRanges, getRepoHash, getUserHash, getWorkingTreeChanges, initPack, isEntryExpired, isTelemetryEnabled, isValidSolanaAddress, lamportsToSol, loadDirectory, loadPack, loadPacksFromDir, loadProgramCache, loadRules, parseDiff, putCacheEntry, rangeChanged, recordGraduationEvents, renderCostReportMd, renderTest, renderTrustGraphMd, rentExemptMinimum, resolveRules, runChecker, runIncrementalScan, saveProgramCache, startWatch, submitTelemetry, telemetryFilePath, testKinds, validatePack, validatePackManifest };

package/dist/index.js

@@ -1,5 +1,7 @@
 import {
+  DEFAULT_REGISTRY_URL,
   DEFAULT_TTL_HOURS,
+  PACK_MANIFEST_FILE,
   analyzeCosts,
   applyDiffToFile,
   audit,
@@ -16,16 +18,23 @@ import {
   getCacheEntry,
   getCacheEntryMeta,
   getChangedRanges,
+  getRepoHash,
+  getUserHash,
   getWorkingTreeChanges,
+  initPack,
   isEntryExpired,
+  isTelemetryEnabled,
   isValidSolanaAddress,
   lamportsToSol,
   loadDirectory,
+  loadPack,
+  loadPacksFromDir,
   loadProgramCache,
   loadRules,
   parseDiff,
   putCacheEntry,
   rangeChanged,
+  recordGraduationEvents,
   renderCostReportMd,
   renderTest,
   renderTrustGraphMd,
@@ -36,8 +45,12 @@ import {
   runIncrementalScan,
   saveProgramCache,
   startWatch,
-  testKinds
-} from "./chunk-Q72MTJXQ.js";
+  submitTelemetry,
+  telemetryFilePath,
+  testKinds,
+  validatePack,
+  validatePackManifest
+} from "./chunk-5LJXC66F.js";
 
 // src/generate.ts
 import { writeFileSync, mkdirSync } from "fs";
@@ -53,7 +66,9 @@ function generateTestForResult(result, rule, outPath) {
   return outPath;
 }
 export {
+  DEFAULT_REGISTRY_URL,
   DEFAULT_TTL_HOURS,
+  PACK_MANIFEST_FILE,
   analyzeCosts,
   applyDiffToFile,
   audit,
@@ -72,16 +87,23 @@ export {
   getCacheEntry,
   getCacheEntryMeta,
   getChangedRanges,
+  getRepoHash,
+  getUserHash,
   getWorkingTreeChanges,
+  initPack,
   isEntryExpired,
+  isTelemetryEnabled,
   isValidSolanaAddress,
   lamportsToSol,
   loadDirectory,
+  loadPack,
+  loadPacksFromDir,
   loadProgramCache,
   loadRules,
   parseDiff,
   putCacheEntry,
   rangeChanged,
+  recordGraduationEvents,
   renderCostReportMd,
   renderTest,
   renderTrustGraphMd,
@@ -91,5 +113,9 @@ export {
   runIncrementalScan,
   saveProgramCache,
   startWatch,
-  testKinds
+  submitTelemetry,
+  telemetryFilePath,
+  testKinds,
+  validatePack,
+  validatePackManifest
 };

package/dist/rules/env-secret-leaked-to-sink.yaml

@@ -25,8 +25,12 @@ detect:
     - end
   requiresImport: false
 check:
-  kind: env-taint-to-sink
+  kind: taint-to-sink
   params:
+    sources:
+      - name: env-secret
+        # Secret-shaped process.env.X reads.
+        pattern: "process\\.env\\.[A-Za-z0-9_]*(SECRET|PRIVATE_KEY|API_KEY|ACCESS_KEY|TOKEN|PASSWORD|CREDENTIAL)[A-Za-z0-9_]*"
     sinkCalls:
       - log
       - error
@@ -37,7 +41,7 @@ check:
       - send
       - write
       - end
-    # Key names that typically hold credentials/secrets.
-    secretKeyPattern: "(SECRET|PRIVATE_KEY|API_KEY|ACCESS_KEY|TOKEN|PASSWORD|CREDENTIAL)"
+    # Same-file or imported-module hops to follow before/after the candidate.
+    maxHops: 2
 test:
   kind: none

package/dist/rules/request-input-command-injection.yaml

@@ -0,0 +1,42 @@
+# Pure-data rule (facts). Binds to vetted templates by `check.kind`/`test.kind`.
+id: request-input-command-injection
+severity: critical
+title: Untrusted request input flows into a shell command
+component:
+  name: Node.js child_process
+  type: API
+  version: unversioned
+  sourceUrl: https://nodejs.org/api/child_process.html
+detect:
+  lang: typescript
+  modules: []
+  # Never matches by name alone — only the triggerCalls (sink calls) below
+  # select candidates.
+  nameRegex: "(?!)"
+  triggerCalls:
+    - exec
+    - execSync
+    - spawn
+    - spawnSync
+    - execFile
+    - execFileSync
+  requiresImport: false
+check:
+  kind: taint-to-sink
+  params:
+    sources:
+      - name: request-input
+        # req.body / req.query / req.params / req.headers (any object named
+        # req/request) — the canonical "untrusted user input" surface for an
+        # HTTP handler.
+        pattern: "\\b(req|request)\\.(body|query|params|headers)\\b"
+    sinkCalls:
+      - exec
+      - execSync
+      - spawn
+      - spawnSync
+      - execFile
+      - execFileSync
+    maxHops: 2
+test:
+  kind: none

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainblast",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "type": "module",
   "description": "Deterministic auditor for catastrophic AI-integration bugs: scan a repo, find the silent money/auth traps, and generate the behavioral test that proves they're fixed.",
   "keywords": [