@authtrack/secura 0.1.0

package/src/commands/scan.mjs

@@ -0,0 +1,203 @@
+/**
+ * `secura scan` — drive a static-analysis run against the backend and render it.
+ *
+ * Transport is chosen by target:
+ *   • repo URL / owner/repo  → sent verbatim as target_path; the backend clones it.
+ *   • local path + local backend (default) → the absolute path is scanned in place.
+ *   • local path + remote backend, or --upload → the dir is tar.gz'd and uploaded.
+ *
+ * Exit codes match the Python CLI: 0 clean · 1 --fail-on gate breached ·
+ * 2 bad target / scan failure · 130 interrupted.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { resolveConfig, isLocalBackend } from "../config.mjs";
+import { classifyTarget } from "../target.mjs";
+import { streamStatic, streamStaticUpload } from "../client.mjs";
+import { packDir, MAX_UPLOAD_BYTES } from "../pack.mjs";
+import { ScanMonitor, SEVERITY_RANK } from "../monitor.mjs";
+import { LiveView, renderLive, printReport } from "../render.mjs";
+import { bold, dim, red, green, yellow, cyan } from "../ansi.mjs";
+
+const errline = (s) => process.stderr.write(s + "\n");
+const outline = (s = "") => process.stdout.write(s + "\n");
+
+export async function runScan(values, positionals) {
+  const rawTarget = String(positionals[0] ?? ".").trim() || ".";
+  const includeCodeql = !values.fast;
+  const language = values.language || "";
+  const maxTriage = values["max-triage"] ?? 25;
+  const maxFindings = values["max-findings"] ?? 20;
+  const failOn = String(values["fail-on"] || "").toLowerCase();
+  const jsonOut = values.json || "";
+  const showFixes = Boolean(values["show-fixes"]);
+  const quiet = Boolean(values.quiet);
+  const forceUpload = Boolean(values.upload);
+
+  const { api, token } = resolveConfig(values);
+  const target = classifyTarget(rawTarget);
+
+  // Validate a local path up front (mirrors the Python CLI's exit-2 checks).
+  if (target.kind === "path") {
+    if (!fs.existsSync(target.value)) {
+      errline(`${red("Not found:")} '${rawTarget}' is neither an existing path nor a Git repo URL.`);
+      return 2;
+    }
+    if (!fs.statSync(target.value).isDirectory()) {
+      errline(`${red("Not a directory:")} ${rawTarget}`);
+      return 2;
+    }
+  }
+
+  const remote = !isLocalBackend(api);
+  const transport = target.kind === "url" ? "url" : forceUpload || remote ? "upload" : "path";
+
+  if (!quiet) {
+    outline();
+    outline(`${bold("secura")} scanning ${cyan(target.display)}`);
+    outline(dim(`backend  ${api}`));
+    if (target.kind === "url") outline(dim("remote repo — the backend shallow-clones it, scans, then removes it"));
+    else if (transport === "upload") outline(dim("packaging local code and uploading it to the backend"));
+    else outline(dim("scanning the path in place on the backend host"));
+    if (values.fast) outline(dim("--fast: CodeQL skipped, no taint paths in this run"));
+    outline();
+  }
+
+  const monitor = new ScanMonitor(target.display, includeCodeql);
+  let cleanup = () => {};
+
+  try {
+    let events;
+    if (transport === "upload") {
+      const packed = packDir(target.value);
+      cleanup = packed.cleanup;
+      const { size } = fs.statSync(packed.path);
+      if (size > MAX_UPLOAD_BYTES) {
+        cleanup();
+        errline(
+          `${red("Too large:")} packaged code is ${(size / 1e6).toFixed(0)} MB ` +
+          `(limit ${(MAX_UPLOAD_BYTES / 1e6).toFixed(0)} MB). ` +
+          `Scan a Git URL, or run the backend locally and drop --upload.`
+        );
+        return 2;
+      }
+      if (!quiet) outline(dim(`packaged ${packed.fileCount} file(s) → ${(size / 1e6).toFixed(1)} MB`));
+
+      const buf = fs.readFileSync(packed.path);
+      const form = new FormData();
+      form.append("include_codeql", String(includeCodeql));
+      form.append("codeql_language", language);
+      form.append("max_triage", String(maxTriage));
+      form.append("file", new Blob([buf], { type: "application/gzip" }), "code.tar.gz");
+      events = streamStaticUpload(api, token, form);
+    } else {
+      events = streamStatic(api, token, {
+        target_path: target.value,
+        include_codeql: includeCodeql,
+        codeql_language: language,
+        max_triage: maxTriage,
+      });
+    }
+
+    const streamCode = await consume(events, monitor, quiet);
+    if (streamCode !== 0) return streamCode;
+  } catch (err) {
+    errline(`\n${red("Scan failed:")} ${err && err.message ? err.message : String(err)}`);
+    return 2;
+  } finally {
+    cleanup();
+  }
+
+  printReport(monitor.report, { showFixes, maxFindings });
+
+  if (jsonOut) {
+    try {
+      const dest = path.resolve(jsonOut);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, JSON.stringify(monitor.report, null, 2), "utf8");
+      outline(`\n${green("Report written to")} ${cyan(jsonOut)}`);
+    } catch (err) {
+      outline(`\n${yellow(`Could not write ${jsonOut}: ${err.message}`)}`);
+    }
+  }
+
+  // ── CI gate ──
+  if (failOn) {
+    const threshold = SEVERITY_RANK[failOn];
+    if (threshold === undefined) {
+      outline(yellow(`Unknown --fail-on severity '${failOn}' — ignored.`));
+    } else {
+      const breaching = (monitor.report.confirmed_findings || []).filter(
+        (f) => (SEVERITY_RANK[String(f.final_severity || f.severity || "info").toLowerCase()] ?? 0) >= threshold
+      );
+      if (breaching.length) {
+        outline(`\n${red(`${breaching.length} confirmed finding(s) at or above ${failOn.toUpperCase()}.`)}`);
+        return 1;
+      }
+      outline(`\n${green(`No confirmed findings at or above ${failOn.toUpperCase()}.`)}`);
+    }
+  }
+
+  return 0;
+}
+
+/**
+ * Consume the event stream, driving the live view. Returns 0 on a clean run, or
+ * 2 if the backend emitted an error event. A spinner timer advances the live
+ * frame even while the backend is quiet (e.g. CodeQL building its database).
+ */
+async function consume(events, monitor, quiet) {
+  const live = new LiveView();
+  const useLive = !quiet && live.active;
+  let frame = 0;
+  let timer = null;
+
+  if (useLive) {
+    live.start();
+    timer = setInterval(() => {
+      frame += 1;
+      live.render(renderLive(monitor, frame));
+    }, 120);
+  }
+
+  const onSigint = () => {
+    if (timer) clearInterval(timer);
+    live.stop();
+    errline(`\n${yellow("Interrupted.")}`);
+    process.exit(130);
+  };
+  process.once("SIGINT", onSigint);
+
+  try {
+    for await (const evt of events) {
+      if (!evt || typeof evt !== "object") continue;
+      switch (evt.event) {
+        case "node_update":
+          monitor.ingest(evt.node, evt.state);
+          if (useLive) live.render(renderLive(monitor, frame));
+          break;
+        case "complete":
+          monitor.stage = "done";
+          if (useLive) live.render(renderLive(monitor, frame));
+          break;
+        case "error":
+          if (timer) clearInterval(timer);
+          if (useLive) {
+            live.render(renderLive(monitor, frame));
+            live.stop();
+          }
+          errline(`\n${red("Backend error:")} ${evt.message || "unknown error"}`);
+          return 2;
+        default:
+          break; // "start" and any future events — ignore
+      }
+    }
+    return 0;
+  } finally {
+    if (timer) clearInterval(timer);
+    live.stop();
+    process.removeListener("SIGINT", onSigint);
+  }
+}

package/src/config.mjs

@@ -0,0 +1,33 @@
+/**
+ * Resolve where the CLI talks to and how.
+ *
+ * The backend's scan router has no auth, so the token is optional; it is sent
+ * as a bearer header only when present, so this works unchanged if auth is
+ * added later.
+ */
+
+// Matches frontend/src/lib/api.ts (API_BASE) so the CLI and the web app default
+// to the same backend.
+const DEFAULT_API = "http://localhost:8000/api/v1";
+
+export function resolveConfig(values) {
+  const raw = values.api || process.env.SECURA_API || DEFAULT_API;
+  const api = raw.replace(/\/+$/, ""); // trim trailing slashes
+  const token = values.token || process.env.SECURA_TOKEN || "";
+  return { api, token };
+}
+
+/**
+ * True when the API base points at this machine. A local path target can then
+ * be scanned in place (sent as `target_path`); otherwise it must be uploaded.
+ */
+export function isLocalBackend(api) {
+  try {
+    const { hostname } = new URL(api);
+    return ["localhost", "127.0.0.1", "0.0.0.0", "::1", "[::1]"].includes(hostname);
+  } catch {
+    // An unparseable base is treated as local — the request will fail loudly
+    // either way, and this keeps the default (no upload) for odd inputs.
+    return true;
+  }
+}

package/src/help.mjs

@@ -0,0 +1,66 @@
+/** Help / usage text for the `secura` CLI. */
+
+import { bold, dim, cyan } from "./ansi.mjs";
+
+export function printHelp() {
+  const p = (s = "") => process.stdout.write(s + "\n");
+  p();
+  p(`${bold("secura")} — AuthTrack static analysis (SAST) from the command line`);
+  p();
+  p("Streams a five-scanner scan (Semgrep, Bearer, OSV-Scanner, Gitleaks, CodeQL)");
+  p("from the AuthTrack backend and renders it live in your terminal.");
+  p();
+  p(bold("USAGE"));
+  p(`  secura scan [target] [options]`);
+  p(`  secura version`);
+  p(`  secura --help`);
+  p();
+  p(bold("TARGETS"));
+  p(`  ${cyan(".")}                        the current directory (default)`);
+  p(`  ${cyan("./path/to/repo")}           a local folder`);
+  p(`  ${cyan("owner/repo")}               a public GitHub repo (shorthand)`);
+  p(`  ${cyan("https://github.com/o/r")}   any public Git URL (cloned by the backend)`);
+  p();
+  p(bold("COMMON"));
+  p(`  secura scan .`);
+  p(`  secura scan owner/repo --fast`);
+  p(`  secura scan . --fail-on high            ${dim("# CI gate")}`);
+  p(`  secura scan . --json report.json`);
+  p();
+  p(`Run ${cyan("secura scan --help")} for every flag.`);
+  p();
+}
+
+export function printScanHelp() {
+  const p = (s = "") => process.stdout.write(s + "\n");
+  p();
+  p(`${bold("secura scan")} [target] [options]`);
+  p();
+  p("Fans out to five scanners at once, merges and deduplicates their findings,");
+  p("retrieves similar known-vulnerable patterns, then has an LLM confirm or rule");
+  p("out each finding and write a patch for the confirmed ones.");
+  p();
+  p(bold("OPTIONS"));
+  p(`  -f, --fast                 Skip CodeQL (its DB build dominates the run).`);
+  p(`  -l, --language <lang>      CodeQL language (javascript, python, java, go,`);
+  p(`                             ruby, csharp, cpp). Auto-detected when omitted.`);
+  p(`  -t, --max-triage <n>       Cap findings sent to LLM triage (default 25).`);
+  p(`      --fail-on <sev>        Exit 1 if a confirmed finding is ≥ this severity`);
+  p(`                             (critical|high|medium|low). For CI gates.`);
+  p(`  -o, --json <path>          Write the full report as JSON to <path>.`);
+  p(`      --max-findings <n>     How many confirmed findings to print (default 20).`);
+  p(`      --show-fixes           Print the generated fix diffs in full.`);
+  p(`  -q, --quiet                Suppress the live view; print only the report.`);
+  p();
+  p(bold("BACKEND"));
+  p(`      --api <url>            Backend base URL`);
+  p(`                             (default $SECURA_API or http://localhost:8000/api/v1).`);
+  p(`      --token <token>        Bearer token, if the backend requires one`);
+  p(`                             (default $SECURA_TOKEN).`);
+  p(`      --upload               Package the local dir and upload it, even for a`);
+  p(`                             local backend. Automatic for a remote --api.`);
+  p();
+  p(bold("EXIT CODES"));
+  p(`  0  clean      1  --fail-on breached      2  bad target / failure      130  interrupted`);
+  p();
+}

package/src/monitor.mjs

@@ -0,0 +1,157 @@
+/**
+ * Port of ScanMonitor (backend/app/cli/main.py): fold each `node_update` event
+ * into the running totals the terminal view needs.
+ *
+ * The graph streams one update per completed node, and the triage loop streams
+ * one per finding, so state is accumulated here rather than re-derived from any
+ * single partial snapshot — identical semantics to the Python monitor.
+ */
+
+// Mirrors frontend/src/lib/static-analysis.ts and main.py so the CLI and the
+// web UI describe the same five engines in the same words.
+export const TOOL_ORDER = ["semgrep", "bearer", "osv-scanner", "gitleaks", "codeql"];
+
+export const TOOL_KIND = {
+  semgrep: "SAST",
+  bearer: "SAST + privacy",
+  "osv-scanner": "SCA",
+  gitleaks: "Secrets",
+  codeql: "Taint analysis",
+};
+
+// Backend graph node name → the tool whose row it fills in.
+const NODE_TO_TOOL = {
+  run_semgrep: "semgrep",
+  run_bearer: "bearer",
+  run_osv_scanner: "osv-scanner",
+  run_gitleaks: "gitleaks",
+  run_codeql: "codeql",
+};
+
+export const SEVERITY_RANK = { critical: 4, high: 3, medium: 2, low: 1, info: 0 };
+
+export const STAGE_LABELS = {
+  dispatch: "Resolving target",
+  scan: "Running 5 scanners in parallel",
+  merge: "Merging and deduplicating",
+  rag: "Retrieving similar known-vulnerable patterns",
+  triage: "AI triage",
+  fixes: "Generating fixes",
+  report: "Building report",
+  done: "Complete",
+};
+
+export class ScanMonitor {
+  constructor(target, includeCodeql) {
+    this.target = target;
+    this.includeCodeql = includeCodeql;
+    this.started = Date.now();
+    this.stage = "dispatch";
+    this.language = "detecting…";
+
+    this.tools = {};
+    for (const name of TOOL_ORDER) {
+      this.tools[name] = { state: "pending", count: 0, duration: 0, note: "", sample: false };
+    }
+    if (!includeCodeql) {
+      this.tools.codeql = {
+        state: "skipped", count: 0, duration: 0, note: "skipped (--fast)", sample: false,
+      };
+    }
+
+    this.mergeStats = {};
+    this.safePatterns = 0;
+    this.ragMatched = null;
+    this.ragTotal = 0;
+
+    this.triageDone = 0;
+    this.triageTotal = 0;
+    this.confirmed = 0;
+    this.discarded = 0;
+
+    this.fixes = 0;
+    this.report = {};
+    this.errors = [];
+  }
+
+  startScanners() {
+    for (const row of Object.values(this.tools)) {
+      if (row.state === "pending") row.state = "running";
+    }
+  }
+
+  elapsedSeconds() {
+    return (Date.now() - this.started) / 1000;
+  }
+
+  /** Fold one `node_update` into the running totals. */
+  ingest(node, state) {
+    const s = state || {};
+
+    if (node === "dispatch") {
+      this.language = s.codeql_language || "auto";
+      this.stage = "scan";
+      this.startScanners();
+      return;
+    }
+
+    if (node in NODE_TO_TOOL) {
+      const tool = NODE_TO_TOOL[node];
+      const status = (s.tool_status || {})[tool] || {};
+      const skipped = String(status.note || "").toLowerCase().includes("skipped");
+      this.tools[tool] = {
+        state: skipped ? "skipped" : status.ok ? "ok" : "failed",
+        count: status.finding_count || 0,
+        duration: status.duration_s || 0,
+        note: status.note || "",
+        sample: Boolean(status.used_sample),
+      };
+      return;
+    }
+
+    if (node === "merge_findings") {
+      this.stage = "merge";
+      this.mergeStats = s.merge_stats || {};
+      this.safePatterns = (s.safe_patterns || []).length;
+      return;
+    }
+
+    if (node === "retrieve_context") {
+      this.stage = "rag";
+      const findings = s.merged_findings || [];
+      this.ragTotal = findings.length;
+      this.ragMatched = findings.filter((f) => (f.context || []).length).length;
+      return;
+    }
+
+    if (node === "triage") {
+      this.stage = "triage";
+      const progress = s.triage_progress || {};
+      if (progress.done !== undefined && progress.done !== null) this.triageDone = progress.done;
+      if (progress.total !== undefined && progress.total !== null) this.triageTotal = progress.total;
+      return;
+    }
+
+    if (node === "confirm_finding") {
+      this.confirmed += (s.triaged_findings || []).length || 1;
+      return;
+    }
+
+    if (node === "discard_finding") {
+      this.discarded += (s.false_positives || []).length || 1;
+      return;
+    }
+
+    if (node === "fix_generator") {
+      this.stage = "fixes";
+      this.fixes = (s.fixes || []).length;
+      this.errors.push(...(s.errors || []));
+      return;
+    }
+
+    if (node === "report_builder") {
+      this.stage = "report";
+      this.report = s.static_report || {};
+    }
+  }
+}

package/src/pack.mjs

@@ -0,0 +1,119 @@
+/**
+ * Package a local directory as a gzipped tarball for upload to a remote backend.
+ *
+ * The tree is walked in Node — skipping the same directories/files the scanners
+ * ignore, and never following symlinks — and the resulting relative file list is
+ * handed to the system `tar` via `-T`. Walking ourselves (rather than leaning on
+ * tar's `--exclude` globbing, which differs between GNU tar and bsdtar) keeps the
+ * archive contents identical on Windows, macOS and Linux, and guarantees only
+ * regular files under the root make it in.
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// CLI-side cap on the packaged archive; the backend enforces its own uncompressed
+// limits on extraction. A repo bigger than this should be scanned as a Git URL.
+export const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100 MB
+
+// Mirrors EXCLUDE_DIRS / EXCLUDE_GLOBS in
+// backend/app/agents/static_analysis/tools.py.
+const EXCLUDE_DIRS = new Set([
+  "node_modules", ".git", ".venv", "venv", "__pycache__", "dist", "build",
+  ".next", "out", "coverage", "vendor", "site-packages", "target",
+  ".mypy_cache", ".pytest_cache", ".ruff_cache", ".turbo", ".cache",
+]);
+const EXCLUDE_SUFFIXES = [".min.js", ".min.css", ".map", ".lock", ".bundle.js"];
+
+const isExcludedFile = (name) => EXCLUDE_SUFFIXES.some((s) => name.endsWith(s));
+
+export function hasTar() {
+  try {
+    const r = spawnSync("tar", ["--version"], { stdio: "ignore" });
+    return !r.error && r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function walk(root) {
+  const files = [];
+  const stack = [""]; // relative paths, "" = root
+  while (stack.length) {
+    const rel = stack.pop();
+    const abs = rel ? path.join(root, rel) : root;
+    let entries;
+    try {
+      entries = fs.readdirSync(abs, { withFileTypes: true });
+    } catch {
+      continue; // unreadable directory — skip it
+    }
+    for (const ent of entries) {
+      if (ent.isSymbolicLink()) continue; // never archive links
+      const childRel = rel ? `${rel}/${ent.name}` : ent.name;
+      if (ent.isDirectory()) {
+        if (!EXCLUDE_DIRS.has(ent.name)) stack.push(childRel);
+      } else if (ent.isFile() && !isExcludedFile(ent.name)) {
+        files.push(childRel); // forward-slashed; tar accepts these on Windows too
+      }
+    }
+  }
+  return files;
+}
+
+function safeUnlink(p) {
+  try {
+    fs.unlinkSync(p);
+  } catch {
+    /* already gone */
+  }
+}
+
+/**
+ * Build the tarball. Returns { path, fileCount, cleanup }. `cleanup()` removes
+ * the archive and must be called by the caller once the upload finishes.
+ */
+export function packDir(dir) {
+  if (!hasTar()) {
+    throw new Error(
+      "`tar` was not found on your PATH, so local code can't be packaged for a remote backend.\n" +
+      "  Fixes: install tar (bundled with Windows 10 1803+, macOS and Linux),\n" +
+      "         scan a public Git repo URL instead (the backend clones it),\n" +
+      "         or run the backend on this machine and drop --upload."
+    );
+  }
+
+  const files = walk(dir);
+  if (files.length === 0) {
+    throw new Error(`Nothing to scan under ${dir} (it's empty, or every file is excluded).`);
+  }
+
+  const stamp = `${process.pid}-${Date.now()}`;
+  const listPath = path.join(os.tmpdir(), `secura-files-${stamp}.txt`);
+  const archivePath = path.join(os.tmpdir(), `secura-upload-${stamp}.tar.gz`);
+
+  try {
+    fs.writeFileSync(listPath, files.join("\n") + "\n", "utf8");
+    // -C dir + relative names → the paths archive at the tarball root.
+    const r = spawnSync("tar", ["-czf", archivePath, "-C", dir, "-T", listPath], {
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+    if (r.error) throw r.error;
+    if (r.status !== 0) {
+      const stderr = r.stderr ? r.stderr.toString().trim() : "";
+      throw new Error(`tar exited ${r.status}${stderr ? `: ${stderr}` : ""}`);
+    }
+    return {
+      path: archivePath,
+      fileCount: files.length,
+      cleanup: () => safeUnlink(archivePath),
+    };
+  } catch (err) {
+    safeUnlink(archivePath);
+    throw new Error(`Failed to package ${dir}: ${err.message}`);
+  } finally {
+    safeUnlink(listPath); // the list is consumed by tar; drop it either way
+  }
+}