sentinelayer-cli 0.8.0 → 0.8.1

package/src/agents/reliability/tools/index.js

@@ -0,0 +1,87 @@
+// Noah (reliability persona) domain-tool registry (#A18).
+
+import { runBackpressureCheck } from "./backpressure-check.js";
+import { runChaosProbe } from "./chaos-probe.js";
+import { runGracefulDegradationCheck } from "./graceful-degradation-check.js";
+import { runHealthCheckAudit } from "./health-check-audit.js";
+
+export const RELIABILITY_TOOLS = Object.freeze({
+  "chaos-probe": {
+    id: "chaos-probe",
+    description:
+      "Report whether the repo has any chaos-testing / fault-injection signals (chaostoolkit, chaos-monkey-js, LitmusChaos, gremlin). Only advises when the repo has ≥3 outbound-HTTP call sites.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runChaosProbe,
+  },
+  "health-check-audit": {
+    id: "health-check-audit",
+    description:
+      "Flag service directories that declare HTTP routes but don't expose /health /healthz /ready /live / _status.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runHealthCheckAudit,
+  },
+  "graceful-degradation-check": {
+    id: "graceful-degradation-check",
+    description:
+      "Flag files that make outbound HTTP calls without try/catch, cached fallback, feature-flag, or circuit-breaker in scope.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runGracefulDegradationCheck,
+  },
+  "backpressure-check": {
+    id: "backpressure-check",
+    description:
+      "Find queue/worker consumers (Bull, Kafka, SQS, RabbitMQ, Redis pub/sub, Celery) and flag those missing concurrency caps or DLQ / retry-limit configuration.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runBackpressureCheck,
+  },
+});
+
+export const RELIABILITY_TOOL_IDS = Object.freeze(Object.keys(RELIABILITY_TOOLS));
+
+export async function dispatchReliabilityTool(toolId, args = {}) {
+  const tool = RELIABILITY_TOOLS[toolId];
+  if (!tool) {
+    throw new Error(`Unknown reliability tool: ${toolId}`);
+  }
+  return tool.handler(args);
+}
+
+export async function runAllReliabilityTools({ rootPath, files = null } = {}) {
+  const findings = [];
+  for (const toolId of RELIABILITY_TOOL_IDS) {
+    const out = await dispatchReliabilityTool(toolId, { rootPath, files });
+    findings.push(...out);
+  }
+  return findings;
+}
+
+export {
+  runBackpressureCheck,
+  runChaosProbe,
+  runGracefulDegradationCheck,
+  runHealthCheckAudit,
+};

package/src/agents/run-persona.js

@@ -0,0 +1,109 @@
+// runPersona — single-persona execution driver (#A27 runtime integration).
+//
+// Takes a persona id + mode and runs that persona's domain-tool sweep over
+// the given repo root / file list. Today this is what's wired to the CLI
+// `persona run <id>` and to omargate.persona_dispatch.
+//
+// - Audit mode (default): invokes the persona's `runAll<X>Tools` and
+//   returns the resulting Finding[]. No LLM call, no file writes.
+// - Codegen mode: runs the same tool sweep AND attaches the mode config
+//   from `agents/mode.js` (allowed-tools + prompt suffix) to the result.
+//   The actual LLM spawn + edit loop happens in the caller — this driver
+//   only produces the deterministic baseline + plan envelope.
+
+import {
+  buildPersonaConfigForMode,
+  listKnownPersonaIds,
+  normalizePersonaMode,
+} from "./mode.js";
+
+// Lazy-load each persona's module to avoid paying the import cost for
+// every persona on every invocation. Each entry is a thunk that returns
+// the persona's runAll* function.
+const PERSONA_LOADERS = Object.freeze({
+  "ai-governance": async () =>
+    (await import("./ai-governance/index.js")).runAllAiGovernanceTools,
+  "backend": async () =>
+    (await import("./backend/index.js")).runAllBackendTools,
+  "code-quality": async () =>
+    (await import("./code-quality/index.js")).runAllCodeQualityTools,
+  "data-layer": async () =>
+    (await import("./data-layer/index.js")).runAllDataLayerTools,
+  "documentation": async () =>
+    (await import("./documentation/index.js")).runAllDocumentationTools,
+  "infrastructure": async () =>
+    (await import("./infrastructure/index.js")).runAllInfrastructureTools,
+  "observability": async () =>
+    (await import("./observability/index.js")).runAllObservabilityTools,
+  "release": async () =>
+    (await import("./release/index.js")).runAllReleaseTools,
+  "reliability": async () =>
+    (await import("./reliability/index.js")).runAllReliabilityTools,
+  "security": async () =>
+    (await import("./security/index.js")).runAllSecurityTools,
+  "supply-chain": async () =>
+    (await import("./supply-chain/index.js")).runAllSupplyChainTools,
+  "testing": async () =>
+    (await import("./testing/index.js")).runAllTestingTools,
+});
+
+export const SUPPORTED_PERSONA_IDS = Object.freeze(
+  Object.keys(PERSONA_LOADERS).sort()
+);
+
+function normalizePersonaId(personaId) {
+  return String(personaId || "").trim().toLowerCase();
+}
+
+function normalizeFiles(files) {
+  if (!files) return [];
+  if (Array.isArray(files)) {
+    return files.map((f) => String(f || "").trim()).filter(Boolean);
+  }
+  return String(files)
+    .split(",")
+    .map((f) => f.trim())
+    .filter(Boolean);
+}
+
+export async function runPersona({
+  personaId,
+  mode = "audit",
+  rootPath,
+  files = null,
+} = {}) {
+  const id = normalizePersonaId(personaId);
+  if (!id) {
+    throw new Error("personaId is required.");
+  }
+  if (!PERSONA_LOADERS[id]) {
+    throw new Error(
+      `Unknown persona id: ${personaId}. Supported: ${SUPPORTED_PERSONA_IDS.join(", ")}`
+    );
+  }
+  const normalizedMode = normalizePersonaMode(mode);
+  const normalizedFiles = normalizeFiles(files);
+  const loader = PERSONA_LOADERS[id];
+  const runAllTools = await loader();
+
+  const toolFiles = normalizedFiles.length > 0 ? normalizedFiles : null;
+  const findings = await runAllTools({
+    rootPath: String(rootPath || "."),
+    files: toolFiles,
+  });
+
+  const modeConfig = buildPersonaConfigForMode(id, normalizedMode);
+  return {
+    personaId: id,
+    mode: normalizedMode,
+    rootPath: String(rootPath || "."),
+    files: normalizedFiles,
+    findings: Array.isArray(findings) ? findings : [],
+    mode_config: {
+      allowedTools: modeConfig.allowedTools,
+      promptSuffix: modeConfig.promptSuffix,
+    },
+  };
+}
+
+export { listKnownPersonaIds };

package/src/agents/security/index.js

@@ -0,0 +1,12 @@
+// Nina (security persona) — barrel export (#A13).
+
+export {
+  SECURITY_TOOLS,
+  SECURITY_TOOL_IDS,
+  dispatchSecurityTool,
+  runAllSecurityTools,
+  runAuthzAudit,
+  runCryptoReview,
+  runSastScan,
+  runSecretsScan,
+} from "./tools/index.js";

package/src/agents/security/tools/authz-audit.js

@@ -0,0 +1,134 @@
+// authz-audit — look for route handlers that forget to call auth middleware (#A13).
+//
+// This is a lightweight static pass. We don't try to model every framework —
+// we focus on the three routing styles the DevTestBot substrate actually
+// uses (Express, Fastify, Next.js app-router route handlers) plus a Python
+// FastAPI pass.
+//
+// Strategy: for each detected route declaration, look at the 6-line window
+// above for an auth/session guard. If none is present, emit a P1 finding
+// with moderate confidence — the persona LLM layer (or a human reviewer)
+// decides whether it's a real gap.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, walkRepoFiles } from "./base.js";
+
+const JS_TS_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+]);
+const PY_EXTENSIONS = new Set([".py"]);
+
+// Patterns that make us comfortable that the route IS guarded.
+const AUTH_GUARD_PATTERNS = [
+  /requireAuth|requireSession|requireUser|requireLogin|auth\.\w+|authenticate|isAuthenticated|ensureAuthenticated|protect\(/,
+  /@login_required|@require_auth|@protected|HTTPBearer|Depends\(get_current_user/,
+  /middleware:\s*\[[^\]]*auth/i,
+];
+
+// Route declaration patterns we consider "mutation-ish" (POST/PUT/PATCH/DELETE).
+const JS_ROUTE_PATTERNS = [
+  /\b(?:app|router|route|server)\.(post|put|patch|delete)\s*\(/,
+  /\bfastify\.(post|put|patch|delete)\s*\(/,
+];
+
+// Next.js app-router POST / PUT / DELETE / PATCH handler declarations.
+const NEXT_APP_ROUTER_PATTERNS = [
+  /^export\s+async\s+function\s+(POST|PUT|PATCH|DELETE)\s*\(/m,
+];
+
+const PY_ROUTE_PATTERNS = [
+  /@(?:app|router)\.(post|put|patch|delete)\s*\(/,
+];
+
+function hasGuardAbove(lines, idx, window = 6) {
+  const start = Math.max(0, idx - window);
+  const snippet = lines.slice(start, idx + 1).join("\n");
+  return AUTH_GUARD_PATTERNS.some((pattern) => pattern.test(snippet));
+}
+
+function evidenceForRoute(lines, idx) {
+  const start = Math.max(0, idx - 1);
+  const end = Math.min(lines.length - 1, idx + 2);
+  return lines.slice(start, end + 1).join("\n").trim().slice(0, 300);
+}
+
+export async function runAuthzAudit({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const extensions = new Set([...JS_TS_EXTENSIONS, ...PY_EXTENSIONS]);
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const ext = path.extname(fullPath).toLowerCase();
+    const lines = content.split(/\r?\n/);
+    const routePatterns =
+      PY_EXTENSIONS.has(ext) ? PY_ROUTE_PATTERNS : [...JS_ROUTE_PATTERNS, ...NEXT_APP_ROUTER_PATTERNS];
+
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+      let matchedRoute = null;
+      for (const pattern of routePatterns) {
+        if (pattern.test(line)) {
+          matchedRoute = line;
+          break;
+        }
+      }
+      if (!matchedRoute) {
+        continue;
+      }
+      if (hasGuardAbove(lines, i)) {
+        continue;
+      }
+      findings.push(
+        createFinding({
+          tool: "authz-audit",
+          kind: "authz.missing-guard",
+          severity: "P1",
+          file: relativePath,
+          line: i + 1,
+          evidence: evidenceForRoute(lines, i),
+          rootCause:
+            "A mutation-style route handler was declared without a recognizable auth guard in the 6 lines above it.",
+          recommendedFix:
+            "Add a middleware / decorator that validates the caller's session (requireAuth, @login_required, Depends(get_current_user), …) before the handler body runs.",
+          confidence: 0.55,
+        })
+      );
+    }
+  }
+  return findings;
+}
+
+async function* iterateExplicitFiles(resolvedRoot, files) {
+  for (const file of files) {
+    const trimmed = String(file || "").trim();
+    if (!trimmed) {
+      continue;
+    }
+    const fullPath = path.isAbsolute(trimmed)
+      ? trimmed
+      : path.join(resolvedRoot, trimmed);
+    const relativePath = path
+      .relative(resolvedRoot, fullPath)
+      .replace(/\\/g, "/");
+    yield { fullPath, relativePath };
+  }
+}
+
+export { AUTH_GUARD_PATTERNS };

package/src/agents/security/tools/base.js

@@ -0,0 +1,190 @@
+// Shared helpers for Nina's (security) domain tools (#A13).
+//
+// Every security tool returns the same Finding shape so the orchestrator can
+// bin / merge results without case analysis. We also centralize the file
+// walker and scope filter here so no tool re-invents the ignore logic.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import ignore from "ignore";
+
+const DEFAULT_IGNORED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  ".venv",
+  ".next",
+  "dist",
+  "build",
+  "coverage",
+  ".sentinelayer",
+  ".sentinel",
+  ".turbo",
+  ".idea",
+  ".vscode",
+  "__pycache__",
+  ".cache",
+]);
+const MAX_FILE_SIZE_BYTES = 1024 * 1024;
+const SEVERITIES = Object.freeze(["P0", "P1", "P2", "P3"]);
+
+export function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+export function normalizeSeverity(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (SEVERITIES.includes(normalized)) {
+    return normalized;
+  }
+  return "P2";
+}
+
+// Canonical Finding shape — every security tool returns objects matching
+// this schema.
+export function createFinding({
+  severity,
+  kind,
+  file,
+  line = 0,
+  evidence = "",
+  rootCause = "",
+  recommendedFix = "",
+  confidence = null,
+  tool = "",
+  persona = "security",
+} = {}) {
+  return {
+    persona,
+    tool: String(tool || "").trim(),
+    kind: String(kind || "").trim() || "security",
+    severity: normalizeSeverity(severity),
+    file: toPosix(file || ""),
+    line: Number.isFinite(Number(line)) ? Math.max(0, Math.floor(Number(line))) : 0,
+    evidence: String(evidence || "").trim().slice(0, 400),
+    rootCause: String(rootCause || "").trim(),
+    recommendedFix: String(recommendedFix || "").trim(),
+    confidence:
+      confidence === null || confidence === undefined
+        ? null
+        : Math.max(0, Math.min(1, Number(confidence) || 0)),
+  };
+}
+
+async function readIgnorePatterns(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    return String(raw || "")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"));
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+async function createIgnoreMatcher(rootPath) {
+  const matcher = ignore();
+  const gitignore = await readIgnorePatterns(path.join(rootPath, ".gitignore"));
+  const sentinel = await readIgnorePatterns(
+    path.join(rootPath, ".sentinelayerignore")
+  );
+  matcher.add([...gitignore, ...sentinel]);
+  return (relativePath, isDirectory) => {
+    const normalized = toPosix(relativePath);
+    if (!normalized) {
+      return false;
+    }
+    const candidate = isDirectory ? `${normalized}/` : normalized;
+    return matcher.ignores(candidate);
+  };
+}
+
+// Walk the target repo, yielding files whose extension is in `extensions`
+// (or all files when `extensions` is empty). Respects .gitignore +
+// .sentinelayerignore + DEFAULT_IGNORED_DIRS.
+export async function* walkRepoFiles({
+  rootPath = process.cwd(),
+  extensions = new Set(),
+  maxFileSize = MAX_FILE_SIZE_BYTES,
+} = {}) {
+  const resolvedRoot = path.resolve(rootPath);
+  const ignoreMatcher = await createIgnoreMatcher(resolvedRoot);
+  const wantedExtensions =
+    extensions instanceof Set
+      ? extensions
+      : new Set(Array.isArray(extensions) ? extensions : []);
+  const stack = [resolvedRoot];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = await fsp.readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      const relativePath = toPosix(path.relative(resolvedRoot, fullPath));
+      if (entry.isDirectory()) {
+        if (!relativePath || DEFAULT_IGNORED_DIRS.has(entry.name)) {
+          continue;
+        }
+        if (ignoreMatcher(relativePath, true)) {
+          continue;
+        }
+        stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (ignoreMatcher(relativePath, false)) {
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (wantedExtensions.size > 0 && !wantedExtensions.has(ext) && !wantedExtensions.has("")) {
+        continue;
+      }
+      let stat = null;
+      try {
+        stat = await fsp.stat(fullPath);
+      } catch {
+        stat = null;
+      }
+      if (!stat || stat.size > maxFileSize) {
+        continue;
+      }
+      yield { fullPath, relativePath };
+    }
+  }
+}
+
+// Find line number of the first occurrence of a pattern in `content`.
+// Returns 0 when not found.
+export function lineNumberOf(content, pattern) {
+  const text = String(content || "");
+  if (!pattern) {
+    return 0;
+  }
+  const idx = text.search(pattern);
+  if (idx < 0) {
+    return 0;
+  }
+  const before = text.slice(0, idx);
+  return before.split(/\r?\n/).length;
+}
+
+// Capture one matching line (trimmed) for evidence.
+export function evidenceAroundMatch(content, line) {
+  const lines = String(content || "").split(/\r?\n/);
+  const idx = Math.max(0, (Number(line) || 1) - 1);
+  return (lines[idx] || "").trim();
+}
+
+export { DEFAULT_IGNORED_DIRS, MAX_FILE_SIZE_BYTES, SEVERITIES };