@shomra/agent 0.2.11 → 0.3.1

package/README.md

@@ -1,8 +1,10 @@
 # @shomra/agent
 
-**The firewall for AI agents**, as a local-first CLI. It sits inside your coding
-agent and CI and blocks dangerous tool-calls, shell commands and data
-exfiltration *before they run* — on your machine, even offline. It also vets AI
+**Adversarial assurance for AI agents**, as a local-first CLI. It sits inside
+your coding agent and CI and blocks dangerous tool-calls, shell commands and
+data exfiltration *before they run* — on your machine, even offline. Enrolled,
+it also attacks your org’s own guardrails (`shomra admin redteam`) and turns
+each breach into a false-positive-gated control (`shomra harden`). It also vets AI
 artifacts (MCP configs, Skills, slash commands, hooks, rules files) before they
 install. Start with a free on-machine scan — no signup.
 
@@ -74,7 +76,14 @@ install-lure prose) runs on-machine, so you get a genuine verdict even if the
 backend is unreachable. When enrolled + reachable, your **org policy** is layered
 on top.
 
-**Exit codes:** `0` = allowed · `1` = blocked (or `--strict` + backend outage) · `2` = flagged with `--strict`.
+**Exit codes** (one convention across every command):
+
+| Code | Meaning |
+|------|---------|
+| `0` | clean / pass |
+| `1` | hard fail — BLOCK, vulnerable model, secret found, FAIL verdict, below `--min`, regression (also `--strict` + backend outage) |
+| `2` | soft fail — FLAG under `--strict` (REVIEW when strict) |
+| `3` | usage / config error — not configured, bad flags, unknown command |
 
 **Backend outage:** by default it falls back to the on-machine verdict (org
 policy not applied). `--strict` fails closed (exit 1) because org policy can't be
@@ -153,6 +162,9 @@ runs local-first; with a key, your **org policy** (below) drives the verdict.
         with: { sarif_file: shomra.sarif }
 ```
 
+`shomra pr` accepts it too: bare `--sarif` writes SARIF to stdout,
+`--sarif=shomra.sarif` writes a file alongside the normal check-run output.
+
 ### Org policy + triage on top of CI
 
 When enrolled, the same **org policy** that governs the dashboard decides the CI
@@ -206,6 +218,36 @@ backend, behind a short timeout + circuit breaker — so a slow or down backend
 never freezes the agent. Fail-open by default; `SHOMRA_GUARD_STRICT=1` fails
 closed on the server tier.
 
+## Adopting Shomra on an existing repo
+
+A brand-new gate on a repo with history will flag things. Three layers make
+adoption friction-free — all of them re-grade the artifact, so a fully
+suppressed file drops to ALLOW and never fails the build:
+
+- **`shomra baseline`** records every current finding (line-independent
+  fingerprints) in `.shomra/baseline.json` — commit it so the whole team shares
+  it. From then on only findings introduced *after* the baseline fail; re-run it
+  to refresh after cleanups. Skip it per-run with `--no-baseline`.
+- **`.shomraignore`** — a repo file of `path/glob` lines (skip the file) or
+  `path/glob :: title-substring` lines (skip one finding class in those files).
+  The runtime firewall honors it too, so test fixtures and detection source
+  aren't withheld. Silence a single finding inline with `// shomra-ignore` (or
+  `# shomra-ignore`) on the finding's line or the line above, or opt a whole
+  file out with `shomra-ignore-file` in its first lines (works in JSON as a
+  `"_shomra": "shomra-ignore-file"` key). `--no-suppress` ignores all of this.
+- **`.shomra/policy.yml`** — policy-as-code, reviewed in PRs like any code:
+
+  ```yaml
+  block: high              # min severity that BLOCKS (critical|high|medium|low|none)
+  flag: medium             # min severity that FLAGS
+  allow:                   # finding-title substrings to always downgrade away
+    - "IPv4 address"
+  ```
+
+  For a local verdict the repo policy fully re-grades; when the backend
+  returned an org decision it can only make it *stricter* (worst-wins) — repo
+  config never loosens org enforcement. `--no-policy` skips it.
+
 ## Environment variables
 
 | Var | Purpose |
@@ -214,9 +256,17 @@ closed on the server tier.
 | `SHOMRA_URL` | Backend URL (overrides config) |
 | `SHOMRA_API_TIMEOUT_MS` | Per-request backend timeout (default 30000) |
 | `SHOMRA_AGENT` | Agent-identity handle presented to `llm-proxy` + firewall |
+| `SHOMRA_GATE_CONCURRENCY` | Parallel backend calls in batch gate / model lookups (default 8, 1–32) |
+| `SHOMRA_GH_TOKEN` | GitHub token for `shomra pr` (falls back to `GITHUB_TOKEN`) |
 | `SHOMRA_GUARD_STRICT` | `1` = firewall fails closed on the server tier |
 | `SHOMRA_GUARD_LOCAL` | `0` = disable the on-machine Tier-0 guard |
+| `SHOMRA_GUARD_IGNORE` | Comma-separated file globs the runtime guard treats as known-safe (adds to `.shomraignore`) |
+| `SHOMRA_GUARD_ALWAYS_ESCALATE` | `1` = send every call to the server (full telemetry, higher overhead) |
 | `SHOMRA_GUARD_TIMEOUT_MS` | Firewall per-call server timeout (default 2000) |
 | `SHOMRA_GUARD_BREAKER_MS` | Skip the server this long after a failure (default 30000; `0` disables) |
+| `SHOMRA_LLM_PROXY_BASE` | Proxy base URL `install-hook` writes for Aider (default `http://127.0.0.1:4141/openai/v1`) |
+| `SHOMRA_MODEL_GUARD` | `0` = disable the model-load screen in the PreToolUse hook |
+| `SHOMRA_MODEL_CACHE` | `0` = disable the on-machine model-index verdict cache |
+| `SHOMRA_MODEL_CACHE_TTL_MS` | Model-cache freshness window (default 7 days) |
 
 Run `shomra help` for the full command reference.

package/code-sast.mjs

@@ -424,6 +424,14 @@ const JS_RULES = [
     category: 'obfuscation',
     confidence: 0.6,
     re: /(?<![.\w])require\s*\(\s*[^'"\s)]|(?<![.\w])import\s*\(\s*[^'"\s)]/,
+    // …but a path BUILT from literals and __dirname is a literal spelled across
+    // path.join — it conceals nothing. `require(path.join(__dirname,'..','generated','prisma'))`
+    // (a Prisma client import) was the shape that made this rule noisy. The CLI has
+    // no AST tier, so without this veto that FP lands at HIGH — a blocking severity.
+    suppress: (m, unitText, ctx) => {
+      const arg = callArgText(unitText, m.index);
+      return isNotAModuleLoad(m, unitText, arg) || isStaticPathExpr(arg, ctx.pathNs, ctx.constPaths);
+    },
     sink: (m) => m[0].trim(),
     message: 'Loads a module chosen at runtime rather than a string literal, often to conceal which dangerous module is imported.',
     remediation: 'Import modules by string literal so the dependency is statically reviewable; remove runtime-computed requires.',
@@ -632,6 +640,141 @@ function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/**
+ * The argument text of the call whose `(` follows `from`, read with balanced
+ * brackets and string-aware so a `)` inside a literal doesn't end it early.
+ * Empty string when the call is unterminated inside the logical line.
+ */
+function callArgText(text, from) {
+  const open = text.indexOf('(', from);
+  if (open < 0) return '';
+  let depth = 0;
+  let quote = '';
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === '\\') i++;
+      else if (ch === quote) quote = '';
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') quote = ch;
+    else if (ch === '(') depth++;
+    else if (ch === ')') {
+      depth--;
+      if (depth === 0) return text.slice(open + 1, i);
+    }
+  }
+  return '';
+}
+
+/**
+ * True when the `require(`/`import(` the regex matched is not Node's module
+ * loader at all. Two shapes, both found in first-party code at HIGH severity:
+ *
+ *  • A DECLARATION of something named `require` — `private async require(orgId, id)`
+ *    is a repository helper, not a module load. The Python rules already carry the
+ *    equivalent `(?<!def )` guard; the JS rule never got one.
+ *  • A call with more than one top-level argument. `require()` takes exactly one.
+ *    (NOT applied to `import()`, which legitimately takes import attributes as a
+ *    second argument.)
+ */
+const DECL_PREFIX_RE = /\b(?:function|async|get|set|static|private|public|protected|readonly)\s*\*?\s*$/;
+function isNotAModuleLoad(m, unitText, argText) {
+  if (DECL_PREFIX_RE.test(unitText.slice(Math.max(0, m.index - 24), m.index))) return true;
+  if (/^\s*import\b/.test(m[0])) return false; // import attributes are a real 2nd arg
+  let depth = 0;
+  let quote = '';
+  for (let i = 0; i < argText.length; i++) {
+    const ch = argText[i];
+    if (quote) {
+      if (ch === '\\') i++;
+      else if (ch === quote) quote = '';
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') quote = ch;
+    else if ('([{'.includes(ch)) depth++;
+    else if (')]}'.includes(ch)) depth--;
+    else if (ch === ',' && depth === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Local names bound to the `path` module in this file. The builder call is
+ * `path.join` only by convention — `const p = require('node:path')` is just as
+ * common, and keying the constant-folder off the literal name "path" missed it.
+ */
+const PATH_BIND_RE =
+  /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*require\(\s*['"](?:node:)?path(?:\/(?:posix|win32))?['"]\s*\)|import\s+(?:\*\s+as\s+)?([A-Za-z_$][\w$]*)\s+from\s*['"](?:node:)?path(?:\/(?:posix|win32))?['"]/g;
+
+function pathBindings(text) {
+  const ns = new Set(['path']);
+  PATH_BIND_RE.lastIndex = 0;
+  for (let m = PATH_BIND_RE.exec(text); m; m = PATH_BIND_RE.exec(text)) ns.add(m[1] || m[2]);
+  return ns;
+}
+
+/**
+ * Identifiers whose declaration folds to a constant path. Requires the RHS to
+ * mention a path-shaped token — a bare `const m = 'child_process'` must stay
+ * unfolded so `require(m)` still reads as a hidden dangerous import. Two rounds,
+ * so `const ROOT = …; const SRC = `${ROOT}/src`` both land.
+ */
+const CONST_DECL_RE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*([^\n;]+)/g;
+const PATHISH_RE = /__dirname|__filename|import\.meta\.url|process\.cwd|os\.(?:homedir|tmpdir)|fileURLToPath|new\s+URL|\.(?:join|resolve|normalize)\s*\(/;
+
+function constPathBindings(text, pathNs) {
+  const found = new Set();
+  for (let round = 0; round < 2; round++) {
+    CONST_DECL_RE.lastIndex = 0;
+    for (let m = CONST_DECL_RE.exec(text); m; m = CONST_DECL_RE.exec(text)) {
+      const [, name, rhsRaw] = m;
+      if (found.has(name)) continue;
+      const rhs = rhsRaw.replace(/[,;]\s*$/, '').trim();
+      // Must be path-shaped, OR built on a constant this pass already proved —
+      // `const SRC = `${ROOT}src/`` inherits ROOT's provenance. Anything else
+      // (a plain string constant) stays unfolded on purpose.
+      const buildsOnKnown = [...found].some((n) => new RegExp(`\\b${escapeRe(n)}\\b`).test(rhs));
+      if (!PATHISH_RE.test(rhs) && !buildsOnKnown) continue;
+      if (isStaticPathExpr(rhs, pathNs, found)) found.add(name);
+    }
+  }
+  return found;
+}
+
+/** Pure path builders: constant arguments in ⇒ one constant path out. */
+const PATH_FNS = 'join|resolve|normalize|relative|dirname|basename|extname';
+
+/**
+ * True when `argText` provably evaluates to one fixed path: nothing survives
+ * after removing string literals and the build-time tokens (pure `path.*`
+ * builders, `__dirname`, `import.meta.url`, …). Conservative — any identifier it
+ * does not recognise (a parameter, a config value, a model result) leaves a
+ * residue and the hit stands. Mirrors `isStaticPathExpr` in the backend's
+ * code-sast.ts, and the structural `isStaticModulePath` in code-ast.ts.
+ */
+export function isStaticPathExpr(argText, pathNs = new Set(['path']), constPaths = new Set()) {
+  if (!argText.trim()) return false;
+  const ns = [...pathNs].map(escapeRe).join('|');
+  const consts = constPaths.size ? `|${[...constPaths].map(escapeRe).join('|')}` : '';
+  const staticTokens = new RegExp(
+    `\\b(?:(?:${ns})(?:\\.(?:posix|win32))?\\.(?:${PATH_FNS})|__dirname|__filename|import\\.meta\\.url|process\\.cwd|os\\.(?:homedir|tmpdir)|fileURLToPath|require\\.resolve|new\\s+URL|String\\.raw${consts})\\b`,
+    'g',
+  );
+  // A member read off whatever remains — `new URL(…).href`, `.toString()`. Applied
+  // as a token strip, so `cfg.modulePath` still leaves `cfg` behind and reports.
+  const pureMembers = /\.(?:href|pathname|toString|toLowerCase|toUpperCase|trim|normalize|valueOf)\b/g;
+  // A template literal reduces to its ${…} expressions — those must be constant
+  // too; its fixed text is just a literal. Plain literals collapse away entirely.
+  let t = argText
+    .replace(/`(?:[^`\\]|\\.)*`/g, (lit) => ` ${[...lit.matchAll(/\$\{([^{}]*)\}/g)].map((x) => x[1]).join(' , ')} `)
+    .replace(/'(?:[^'\\]|\\.)*'/g, ' ')
+    .replace(/"(?:[^"\\]|\\.)*"/g, ' ');
+  t = t.replace(pureMembers, ' ').replace(staticTokens, ' ');
+  // Structure-only residue (separators, concatenation, empty call parens) is fine.
+  return !/[A-Za-z0-9_$]/.test(t.replace(/[\s(),.+[\]/\\:-]/g, ''));
+}
+
 /**
  * Whether byte `offset` in `text` falls inside a string literal — tracks single/
  * double/backtick + triple quotes, honouring escapes. Drops `codeOnly` rule
@@ -802,6 +945,9 @@ function scanLines(text, file, rules, taintCfg) {
   const units = logicalLines(lines);
   const out = [];
   const seen = new Set(); // dedupe by ruleId@line
+  // Whole-file facts a `suppress` predicate may consult; computed once per scan.
+  const pathNs = pathBindings(text);
+  const ctx = { pathNs, constPaths: constPathBindings(text, pathNs) };
   for (const unit of units) {
     for (const rule of rules) {
       rule.re.lastIndex = 0;
@@ -810,6 +956,10 @@ function scanLines(text, file, rules, taintCfg) {
       // Drop code-construct rules whose match lands inside a string literal
       // (docstring / log message / usage example) — the Falcon-class FP.
       if (rule.codeOnly && isInsideString(unit.text, m.index)) continue;
+      // Last-word veto on a match the regex accepted: the signal is real code but
+      // the ARGUMENT proves it benign — needs balanced-bracket reading a regex
+      // cannot express. Returning true drops the hit.
+      if (rule.suppress && rule.suppress(m, unit.text, ctx)) continue;
       const idx = physicalIdx(unit, m.index);
       const trimmed = (lines[idx] ?? '').trim();
       if (!trimmed || isCommentLine(trimmed)) continue;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shomra/agent",
-  "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.",
+  "version": "0.3.1",
+  "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"