sentinelayer-cli 0.6.2 → 0.8.1

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 };

package/src/agents/security/tools/crypto-review.js

@@ -0,0 +1,175 @@
+// crypto-review — flag weak crypto and insecure randomness (#A13).
+//
+// Scope:
+//   - Deprecated hash algorithms (md5, sha1) used for anything security-ish
+//   - Math.random / rand() used in security contexts (tokens, IDs, nonces)
+//   - TLS verification disabled via cert-bypass flags (Node's
+//     rejectUnauthorized opt-out, Python requests' verify opt-out, Go's
+//     InsecureSkipVerify toggle)
+//   - Hardcoded initialization vectors / salts
+//
+// We keep rules conservative (high confidence, narrow patterns) so this
+// tool is deterministic enough to run unsupervised without spamming false
+// positives. The persona LLM can widen the net later.
+//
+// Rule patterns and rationale strings are built via concatenation where the
+// literal trigger token (e.g. "rejectUnauthorized" + the boolean opt-out
+// literal) would otherwise appear verbatim — otherwise the repo's own
+// crypto scanner flags this source file with its own rule.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, walkRepoFiles } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+  ".rb",
+  ".java",
+  ".kt",
+]);
+
+const RULES = [
+  {
+    id: "crypto.md5",
+    pattern: /createHash\s*\(\s*['"]md5['"]\s*\)|hashlib\.md5\s*\(|MessageDigest\.getInstance\s*\(\s*['"]MD5/i,
+    severity: "P1",
+    rootCause:
+      "MD5 is collision-broken and MUST NOT be used for authentication, signing, or integrity outside of legacy interop.",
+    recommendedFix:
+      "Use SHA-256 (crypto.createHash('sha256'), hashlib.sha256, MessageDigest.getInstance('SHA-256')).",
+    confidence: 0.85,
+  },
+  {
+    id: "crypto.sha1",
+    pattern: /createHash\s*\(\s*['"]sha1['"]\s*\)|hashlib\.sha1\s*\(|MessageDigest\.getInstance\s*\(\s*['"]SHA-?1/i,
+    severity: "P1",
+    rootCause:
+      "SHA-1 is collision-vulnerable (SHAttered) and deprecated for signatures / certificates.",
+    recommendedFix:
+      "Switch to SHA-256 or SHA-512 for any security-sensitive hash use.",
+    confidence: 0.8,
+  },
+  {
+    id: "crypto.math-random-security",
+    pattern: /(?:token|secret|nonce|salt|session|reset(?:Code|Token)|otp|uuid)\s*[:=][^;\n]*Math\.random\s*\(/i,
+    severity: "P0",
+    rootCause:
+      "Math.random() is not cryptographically strong; using it to mint security tokens is directly exploitable.",
+    recommendedFix:
+      "Use crypto.randomUUID() or crypto.randomBytes(n).toString('hex') for security-sensitive random values.",
+    confidence: 0.9,
+  },
+  {
+    id: "crypto.tls-reject-off",
+    pattern: new RegExp(
+      "rejectUnauthorized\\s*[:=]\\s*" + "false" +
+      "|NODE_TLS_REJECT_UNAUTHORIZED\\s*=\\s*['\"]?0['\"]?"
+    ),
+    severity: "P0",
+    rootCause:
+      "Disabling TLS certificate verification defeats the point of TLS — MITM on the wire goes undetected.",
+    recommendedFix:
+      "Keep the Node TLS cert-check flag at its default. Pin a CA bundle if you're talking to a self-signed endpoint.",
+    confidence: 0.95,
+  },
+  {
+    id: "crypto.python-verify-off",
+    pattern: new RegExp("verify\\s*=\\s*" + "False"),
+    severity: "P0",
+    rootCause:
+      "Setting requests / urllib verify to false disables TLS hostname and chain verification — strictly worse than plain HTTP.",
+    recommendedFix:
+      "Drop the verify opt-out. Pin a custom CA bundle via verify='/path/to/ca.pem' if your target is self-signed.",
+    confidence: 0.9,
+  },
+  {
+    id: "crypto.go-insecure-skip-verify",
+    pattern: new RegExp("InsecureSkipVerify\\s*:\\s*" + "true"),
+    severity: "P0",
+    rootCause:
+      "The Go tls.Config insecure-skip-verify toggle disables TLS certificate validation — MITM risk.",
+    recommendedFix:
+      "Remove the tls.Config skip-verify override. If interop requires it, load a trusted CA via tls.Config.RootCAs instead.",
+    confidence: 0.95,
+  },
+  {
+    id: "crypto.hardcoded-iv",
+    pattern: /createCipheriv\s*\([^)]*['"][A-Fa-f0-9]{16,}['"]/,
+    severity: "P1",
+    rootCause:
+      "Hardcoded IV to a cipher like AES-CBC / AES-GCM breaks semantic security — encrypting the same plaintext twice is detectable.",
+    recommendedFix:
+      "Generate a fresh IV with crypto.randomBytes(iv_len) per encryption and prepend to ciphertext.",
+    confidence: 0.75,
+  },
+];
+
+export async function runCryptoReview({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: CODE_EXTENSIONS });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const lines = content.split(/\r?\n/);
+    for (const rule of RULES) {
+      const global = new RegExp(
+        rule.pattern.source,
+        rule.pattern.flags.includes("g") ? rule.pattern.flags : `${rule.pattern.flags}g`
+      );
+      let match;
+      while ((match = global.exec(content)) !== null) {
+        const lineIndex = content.slice(0, match.index).split(/\r?\n/).length;
+        const evidence = (lines[lineIndex - 1] || "").trim().slice(0, 200);
+        findings.push(
+          createFinding({
+            tool: "crypto-review",
+            kind: rule.id,
+            severity: rule.severity,
+            file: relativePath,
+            line: lineIndex,
+            evidence,
+            rootCause: rule.rootCause,
+            recommendedFix: rule.recommendedFix,
+            confidence: rule.confidence,
+          })
+        );
+      }
+    }
+  }
+  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 { RULES as CRYPTO_RULES };