@authtrack/secura 0.1.0

package/README.md

@@ -0,0 +1,157 @@
+# @authtrack/secura
+
+**AuthTrack static analysis (SAST) from the command line.**
+
+`secura` points five independent engines — [Semgrep], [Bearer], [OSV-Scanner],
+[Gitleaks] and [CodeQL] — at a repository, merges and deduplicates their
+findings, retrieves similar known-vulnerable patterns, then has an LLM confirm
+or rule out each finding and write a patch for the confirmed ones. It streams
+the whole run live in your terminal and prints a report at the end.
+
+The scanning runs on the **AuthTrack backend**; this CLI is a thin, zero-dependency
+client that talks to it. You don't need Python, and you don't need the scanners
+installed locally.
+
+[Semgrep]: https://semgrep.dev
+[Bearer]: https://www.bearer.com
+[OSV-Scanner]: https://google.github.io/osv-scanner/
+[Gitleaks]: https://github.com/gitleaks/gitleaks
+[CodeQL]: https://codeql.github.com
+
+---
+
+## Install
+
+```bash
+npm install -g @authtrack/secura
+```
+
+Or run it once, without installing:
+
+```bash
+npx @authtrack/secura scan .
+```
+
+Requires **Node ≥ 18**. No build step, no native modules.
+
+## Quick start
+
+```bash
+# Scan the current directory
+secura scan .
+
+# Scan a public GitHub repo (the backend clones it)
+secura scan owner/repo
+secura scan https://github.com/owner/repo
+
+# Fast pass — skip CodeQL (its database build dominates the run)
+secura scan . --fast
+
+# CI gate: exit non-zero if anything HIGH or worse is confirmed
+secura scan . --fail-on high
+
+# Save the full machine-readable report
+secura scan . --json report.json
+```
+
+## Targets
+
+| Target | What happens |
+| --- | --- |
+| `.` or `./path/to/repo` | A local folder. Sent to the backend to scan (see [Backend](#backend)). |
+| `owner/repo` | Public GitHub shorthand. The backend shallow-clones it, scans, then deletes it. |
+| `https://github.com/owner/repo`, `git@…`, `ssh://…` | Any public Git URL. Cloned by the backend. |
+
+For a local path, how the code reaches the backend depends on where the backend runs:
+
+- **Local backend** (the default, `http://localhost:8000`): the absolute path is
+  sent as-is and scanned in place — nothing is copied.
+- **Remote backend** (a `--api` that isn't localhost), or **`--upload`**: the
+  directory is packaged into a `tar.gz` (excluding `node_modules`, `.git`, build
+  output, lockfiles, minified assets, …) and uploaded. Requires `tar` on your
+  PATH (bundled with Windows 10 1803+, macOS and Linux). If `tar` is missing,
+  scan a Git URL instead.
+
+## Options
+
+```
+-f, --fast                 Skip CodeQL (its DB build dominates the run).
+-l, --language <lang>      CodeQL language (javascript, python, java, go, ruby,
+                           csharp, cpp). Auto-detected when omitted.
+-t, --max-triage <n>       Cap findings sent to LLM triage (default 25).
+    --fail-on <sev>        Exit 1 if a confirmed finding is >= this severity
+                           (critical|high|medium|low). For CI gates.
+-o, --json <path>          Write the full report as JSON to <path>.
+    --max-findings <n>     How many confirmed findings to print (default 20).
+    --show-fixes           Print the generated fix diffs in full.
+-q, --quiet                Suppress the live view; print only the report.
+    --api <url>            Backend base URL (default $SECURA_API or
+                           http://localhost:8000/api/v1).
+    --token <token>        Bearer token, if the backend requires one
+                           (default $SECURA_TOKEN).
+    --upload               Package and upload the local dir even for a local
+                           backend (automatic for a remote --api).
+```
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Completed; no `--fail-on` breach. |
+| `1` | `--fail-on` gate breached (a confirmed finding at or above the threshold). |
+| `2` | Bad target, or the scan failed. |
+| `130` | Interrupted (Ctrl-C). |
+
+## Backend
+
+`secura` needs a reachable AuthTrack backend. Point it at one with `--api` or the
+`SECURA_API` environment variable (matching the web app's `NEXT_PUBLIC_API_URL`):
+
+```bash
+export SECURA_API="https://scans.example.com/api/v1"
+secura scan owner/repo
+```
+
+The default is `http://localhost:8000/api/v1`. The scan endpoints are unauthenticated;
+`--token` / `SECURA_TOKEN` is sent as a bearer header only if provided, so it keeps
+working if auth is added later.
+
+## CI example
+
+```yaml
+# GitHub Actions — fail the build on a confirmed high+ finding
+- name: SAST
+  run: npx @authtrack/secura scan . --fast --fail-on high --json sast.json
+  env:
+    SECURA_API: ${{ secrets.SECURA_API }}
+```
+
+---
+
+## Publishing (maintainers)
+
+This package publishes from the `cli/` directory of the AuthTrack repo. It is
+plain ESM with no build step, so publishing is just:
+
+```bash
+cd cli
+npm login                     # once per machine
+npm version patch             # 0.1.0 -> 0.1.1 (bumps package.json + git tag)
+npm publish --access public   # scoped packages need --access public on first publish
+```
+
+Notes:
+
+- **Scope.** The name `@authtrack/secura` requires the `@authtrack` org to exist
+  on npm and your account to be a member. Create it at
+  <https://www.npmjs.com/org/create>, or rename the package to an unscoped name
+  you own (e.g. `authtrack-secura`) in `package.json` — the `bin` stays `secura`
+  either way, so `secura scan …` is unchanged for users.
+- **What ships.** Only `bin/`, `src/` and `README.md` (the `files` allowlist).
+  Verify with `npm pack --dry-run` before publishing.
+- **Smoke test the tarball.** `npm pack` then
+  `npm i -g ./authtrack-secura-<version>.tgz` and run `secura --help`.
+
+## License
+
+MIT

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,46 @@
+{
+  "name": "@authtrack/secura",
+  "version": "0.1.0",
+  "description": "AuthTrack static analysis (SAST) from the command line — streams a five-scanner scan (Semgrep, Bearer, OSV-Scanner, Gitleaks, CodeQL) from the AuthTrack backend and renders it live in your terminal.",
+  "type": "module",
+  "bin": {
+    "secura": "bin/secura.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "sast",
+    "static-analysis",
+    "security",
+    "semgrep",
+    "codeql",
+    "gitleaks",
+    "osv-scanner",
+    "bearer",
+    "cli",
+    "vulnerability",
+    "authtrack"
+  ],
+  "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"
+  }
+}

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