secura-cli 0.1.4

package/bin/secura.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * secura — AuthTrack static analysis CLI (npm distribution).
+ *
+ * A dependency-free Node client for the backend's static-analysis SSE endpoints.
+ * The heavy scanning runs on the backend; this renders the streamed run and the
+ * final report in your terminal. See ../README.md.
+ */
+
+import { parseArgs } from "../src/args.mjs";
+import { runScan } from "../src/commands/scan.mjs";
+import { printHelp, printScanHelp } from "../src/help.mjs";
+import { red, showCursor } from "../src/ansi.mjs";
+
+const VERSION = "0.1.0";
+
+// Canonical long name → { type, alias }. Mirrors the Python `scan` command's
+// flags, plus the API-client-only --api / --token / --upload.
+const SCAN_SPEC = {
+  fast: { type: "boolean", alias: "f" },
+  language: { type: "string", alias: "l" },
+  "max-triage": { type: "number", alias: "t" },
+  "fail-on": { type: "string" },
+  json: { type: "string", alias: "o" },
+  "max-findings": { type: "number" },
+  "show-fixes": { type: "boolean" },
+  quiet: { type: "boolean", alias: "q" },
+  api: { type: "string" },
+  token: { type: "string" },
+  upload: { type: "boolean" },
+  help: { type: "boolean", alias: "h" },
+};
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    printHelp();
+    return 0;
+  }
+  if (cmd === "version" || cmd === "--version" || cmd === "-v") {
+    process.stdout.write(`secura ${VERSION} — AuthTrack static analysis CLI (npm)\n`);
+    return 0;
+  }
+  if (cmd === "scan") {
+    const { values, positionals, errors } = parseArgs(argv.slice(1), SCAN_SPEC);
+    if (values.help) {
+      printScanHelp();
+      return 0;
+    }
+    if (errors.length) {
+      for (const e of errors) process.stderr.write(`${red("error:")} ${e}\n`);
+      process.stderr.write("Run `secura scan --help` for usage.\n");
+      return 2;
+    }
+    return runScan(values, positionals);
+  }
+
+  process.stderr.write(`${red(`Unknown command '${cmd}'.`)} Try \`secura --help\`.\n`);
+  return 2;
+}
+
+main()
+  .then((code) => process.exit(code ?? 0))
+  .catch((err) => {
+    showCursor(); // never leave the terminal cursor hidden after a crash
+    process.stderr.write(`${red("Fatal:")} ${err && err.stack ? err.stack : String(err)}\n`);
+    process.exit(2);
+  });

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "secura-cli",
+  "version": "0.1.4",
+  "description": "SecuraAI security scanner CLI and MCP server — static analysis, recon, header audit and injection testing via AI agents.",
+  "type": "module",
+  "bin": {
+    "secura": "bin/secura.mjs",
+    "secura-mcp": "bin/secura-mcp.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "keywords": [
+    "sast",
+    "static-analysis",
+    "security",
+    "semgrep",
+    "codeql",
+    "gitleaks",
+    "osv-scanner",
+    "bearer",
+    "cli",
+    "vulnerability",
+    "mcp",
+    "model-context-protocol",
+    "securai",
+    "securaai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashleyalmeida07/Authtrack-Major-Project.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/ashleyalmeida07/Authtrack-Major-Project#readme",
+  "bugs": {
+    "url": "https://github.com/ashleyalmeida07/Authtrack-Major-Project/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "secura": "node bin/secura.mjs",
+    "secura-mcp": "node bin/secura-mcp.mjs"
+  }
+}

package/src/ansi.mjs

@@ -0,0 +1,93 @@
+/**
+ * Zero-dependency ANSI styling.
+ *
+ * Colour is enabled only when stdout is a TTY and `NO_COLOR` is unset (honouring
+ * https://no-color.org), or forced on with `FORCE_COLOR`. When disabled every
+ * helper is the identity function, so the same render code produces clean text
+ * for pipes, CI logs and `--json` redirects.
+ */
+
+const enabled =
+  !process.env.NO_COLOR &&
+  (Boolean(process.env.FORCE_COLOR) || Boolean(process.stdout.isTTY));
+
+function wrap(open, close) {
+  const prefix = `\x1b[${open}m`;
+  const suffix = `\x1b[${close}m`;
+  return (s) => (enabled ? prefix + String(s) + suffix : String(s));
+}
+
+export const colorEnabled = enabled;
+
+export const bold = wrap(1, 22);
+export const dim = wrap(2, 22);
+
+export const red = wrap(31, 39);
+export const green = wrap(32, 39);
+export const yellow = wrap(33, 39);
+export const blue = wrap(34, 39);
+export const magenta = wrap(35, 39);
+export const cyan = wrap(36, 39);
+export const gray = wrap(90, 39); // bright_black
+export const brightRed = wrap(91, 39);
+export const white = wrap(37, 39);
+
+// Mirrors SEVERITY_COLOR in backend/app/cli/main.py.
+const SEVERITY_FN = {
+  critical: brightRed,
+  high: red,
+  medium: yellow,
+  low: cyan,
+  info: gray,
+};
+
+/** Uppercase, severity-coloured label — e.g. a red "HIGH". */
+export function severityText(name) {
+  const key = String(name || "info").toLowerCase();
+  const fn = SEVERITY_FN[key] || white;
+  return fn(key.toUpperCase());
+}
+
+// ── Cursor control (live view) ──
+
+export const hideCursor = () => {
+  if (enabled) process.stdout.write("\x1b[?25l");
+};
+export const showCursor = () => {
+  if (enabled) process.stdout.write("\x1b[?25h");
+};
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/** Visible length of a string, ignoring ANSI escape sequences. */
+export function visibleLength(s) {
+  return s.replace(ANSI_RE, "").length;
+}
+
+/**
+ * Truncate to `width` visible columns, preserving ANSI codes and appending an
+ * ellipsis when clipped. Keeps the live view from wrapping in a narrow terminal
+ * (which would break the cursor-up redraw).
+ */
+export function clip(s, width) {
+  if (width <= 0 || visibleLength(s) <= width) return s;
+  let out = "";
+  let vis = 0;
+  for (let i = 0; i < s.length; ) {
+    const rest = s.slice(i);
+    const m = rest.match(/^\x1b\[[0-9;]*m/);
+    if (m) {
+      out += m[0];
+      i += m[0].length;
+      continue;
+    }
+    if (vis >= width - 1) {
+      out += "…";
+      break;
+    }
+    out += s[i];
+    vis += 1;
+    i += 1;
+  }
+  return out + (enabled ? "\x1b[0m" : "");
+}

package/src/args.mjs

@@ -0,0 +1,115 @@
+/**
+ * A tiny, dependency-free argv parser.
+ *
+ * Handles the shapes the `secura` commands need and nothing more:
+ *   --flag            boolean true
+ *   --key value       string / number (next token is the value)
+ *   --key=value       string / number (inline)
+ *   -f                short boolean (clusterable: -fq)
+ *   -l value | -lvalue | -l=value   short with a value
+ *   --                everything after is positional
+ *
+ * `spec` maps a canonical long name → { type: "boolean"|"string"|"number", alias?: "x" }.
+ * Returns { values, positionals, errors }. Unknown options and malformed
+ * numbers are collected in `errors` rather than thrown, so the caller decides
+ * whether to abort or show usage.
+ */
+export function parseArgs(argv, spec) {
+  const aliasToName = {};
+  for (const [name, opt] of Object.entries(spec)) {
+    if (opt.alias) aliasToName[opt.alias] = name;
+  }
+
+  const values = {};
+  const positionals = [];
+  const errors = [];
+
+  const coerce = (opt, raw, label) => {
+    if (opt.type === "number") {
+      const n = Number(raw);
+      if (Number.isNaN(n)) {
+        errors.push(`${label} expects a number, got '${raw}'`);
+        return undefined;
+      }
+      return n;
+    }
+    return raw;
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+
+    // Long option: --name, --name=value
+    if (arg.startsWith("--")) {
+      let key = arg.slice(2);
+      let inline;
+      const eq = key.indexOf("=");
+      if (eq !== -1) {
+        inline = key.slice(eq + 1);
+        key = key.slice(0, eq);
+      }
+      const name = spec[key] ? key : aliasToName[key];
+      if (!name) {
+        errors.push(`unknown option --${key}`);
+        continue;
+      }
+      const opt = spec[name];
+      if (opt.type === "boolean") {
+        values[name] = inline === undefined ? true : /^(1|true|yes|on)$/i.test(inline);
+      } else {
+        let raw = inline;
+        if (raw === undefined) {
+          raw = argv[++i];
+          if (raw === undefined) {
+            errors.push(`--${key} needs a value`);
+            continue;
+          }
+        }
+        const v = coerce(opt, raw, `--${key}`);
+        if (v !== undefined) values[name] = v;
+      }
+      continue;
+    }
+
+    // Short option(s): -f, -fq, -l value, -lvalue, -l=value
+    if (arg.length > 1 && arg[0] === "-") {
+      const chars = arg.slice(1);
+      for (let c = 0; c < chars.length; c += 1) {
+        const ch = chars[c];
+        const name = aliasToName[ch];
+        if (!name) {
+          errors.push(`unknown option -${ch}`);
+          break;
+        }
+        const opt = spec[name];
+        if (opt.type === "boolean") {
+          values[name] = true;
+          continue; // allow clustering, e.g. -fq
+        }
+        // value option consumes the rest of this token, or the next argv entry
+        let raw = chars.slice(c + 1);
+        if (raw.startsWith("=")) raw = raw.slice(1);
+        if (!raw) {
+          raw = argv[++i];
+          if (raw === undefined) {
+            errors.push(`-${ch} needs a value`);
+            break;
+          }
+        }
+        const v = coerce(opt, raw, `-${ch}`);
+        if (v !== undefined) values[name] = v;
+        break; // rest of the token was the value
+      }
+      continue;
+    }
+
+    positionals.push(arg);
+  }
+
+  return { values, positionals, errors };
+}

package/src/client.mjs

@@ -0,0 +1,95 @@
+/**
+ * Backend client — POSTs to the static-analysis stream endpoints and yields the
+ * parsed SSE events.
+ *
+ * The wire format matches backend/app/api/scan.py: newline-delimited frames of
+ * `data: {json}\n\n`, each carrying one of:
+ *   { event: "start",       message }
+ *   { event: "node_update", node, state }
+ *   { event: "complete",    message }
+ *   { event: "error",       message }
+ *
+ * This mirrors the reader loop in frontend/src/lib/api.ts (split on "\n\n",
+ * parse `data:` lines) so the CLI and the browser consume an identical stream.
+ * Uses Node's global fetch + Web Streams (Node >= 18) — no dependencies.
+ */
+
+function authHeaders(token, extra = {}) {
+  const h = { ...extra };
+  if (token) h.Authorization = `Bearer ${token}`;
+  return h;
+}
+
+async function openStream(url, token, headers, body) {
+  let res;
+  try {
+    res = await fetch(url, { method: "POST", headers: authHeaders(token, headers), body });
+  } catch (err) {
+    throw new Error(
+      `Could not reach the backend at ${url}\n` +
+      `  ${err.message}\n` +
+      `  Is it running? Point elsewhere with --api <url> or the SECURA_API env var.`
+    );
+  }
+  if (!res.ok) {
+    let detail = "";
+    try {
+      detail = (await res.text()).slice(0, 500).trim();
+    } catch {
+      /* ignore */
+    }
+    throw new Error(`Backend returned ${res.status} ${res.statusText}${detail ? `\n  ${detail}` : ""}`);
+  }
+  if (!res.body) throw new Error("Backend sent an empty response body.");
+  return res;
+}
+
+async function* readSse(res) {
+  const decoder = new TextDecoder();
+  const reader = res.body.getReader();
+  let buffer = "";
+
+  const emit = function* (frame) {
+    // A frame may hold several lines; the backend uses a single `data:` line.
+    for (const rawLine of frame.split("\n")) {
+      if (!rawLine.startsWith("data:")) continue;
+      const jsonStr = rawLine.slice(rawLine.indexOf(":") + 1).trim();
+      if (!jsonStr) continue;
+      try {
+        yield JSON.parse(jsonStr);
+      } catch {
+        // Malformed frame — skip it (the browser client does the same).
+      }
+    }
+  };
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const frames = buffer.split("\n\n");
+    buffer = frames.pop() || ""; // keep the trailing partial frame
+    for (const frame of frames) yield* emit(frame);
+  }
+  // Flush any final frame that arrived without a trailing blank line.
+  const tail = buffer.trim();
+  if (tail) yield* emit(tail);
+}
+
+/** Stream a scan of a repo URL or a co-located local path (JSON body). */
+export async function* streamStatic(api, token, body) {
+  const res = await openStream(
+    `${api}/scan/stream/static`,
+    token,
+    { "Content-Type": "application/json" },
+    JSON.stringify(body)
+  );
+  yield* readSse(res);
+}
+
+/** Stream a scan of uploaded local code (multipart tar.gz + form fields). */
+export async function* streamStaticUpload(api, token, form) {
+  // Let fetch set the multipart Content-Type (with boundary) from the FormData.
+  const res = await openStream(`${api}/scan/stream/static/upload`, token, {}, form);
+  yield* readSse(res);
+}

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 = "https://52.91.8.40.nip.io/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;
+  }
+}