praxis-sec 1.0.0

package/cli/core/web/jobs.js

@@ -0,0 +1,183 @@
+/**
+ * Bounded job queue for the web UI.
+ * ============================================================================
+ *
+ * Runs scans through the existing `Orchestrator` so the web UI never reimplements
+ * detection — the numbers in the browser are the same numbers the CLI produces.
+ *
+ * Threat T7 (resource exhaustion): concurrency is capped and the queue length is
+ * capped, because a scan is expensive (28 agents) and an untrusted local caller could
+ * otherwise pile up work. Jobs live in memory; the report is what gets persisted, so // praxis-ignore AGENT_MEMORY_NO_EXPIRY — doc comment; JobQueue._trim() bounds retention to 50 finished jobs
+ * restarting the server does not lose scan *results* the report already captured.
+ */
+
+import path from 'path';
+import { EventEmitter } from 'events';
+
+export const MAX_CONCURRENCY = 2;
+export const MAX_QUEUE = 16;
+const JOB_RETENTION = 50; // keep the most recent N finished jobs for inspection
+
+let seq = 0;
+
+export class JobQueue extends EventEmitter {
+  constructor({ concurrency = MAX_CONCURRENCY, runScan } = {}) {
+    super();
+    this.concurrency = Math.max(1, concurrency);
+    this.maxQueue = MAX_QUEUE;
+    this.runScan = runScan;
+    this.jobs = [];
+    this.pending = [];
+    this.running = 0;
+  }
+
+  /**
+   * Enqueues a scan for a registered project.
+   * @returns {{ok:true, job:object} | {ok:false, error:string}}
+   */
+  enqueue(project) {
+    const queued = this.jobs.length + this.pending.length;
+    if (queued >= this.maxQueue) {
+      return { ok: false, error: `queue is full (max ${this.maxQueue} scans)` };
+    }
+    const job = {
+      id: `job-${++seq}`,
+      projectId: project.id,
+      projectName: project.name,
+      root: project.root,
+      status: 'queued',
+      queuedAt: new Date().toISOString(),
+      startedAt: null,
+      finishedAt: null,
+      progress: { done: 0, total: 0, current: null },
+      result: null,
+      error: null,
+    };
+    this.jobs.push(job);
+    this.pending.push(job);
+    this._emitUpdate(job);
+    // Snapshot before draining: _drain() starts the job synchronously, so capturing
+    // afterwards would hand the client a job already marked 'running' and make the
+    // 'queued' state unobservable.
+    const snapshot = this._public(job);
+    this._drain();
+    return { ok: true, job: snapshot };
+  }
+
+  get(id) {
+    return this.jobs.find(j => j.id === id) || null;
+  }
+
+  /** All jobs, oldest first, as API-safe objects. */
+  list() {
+    return this.jobs.map(j => this._public(j));
+  }
+
+  cancel(id) {
+    const job = this.get(id);
+    if (!job) return { ok: false, error: 'unknown job' };
+    if (job.status === 'running') {
+      // The orchestrator is not abortable mid-scan; be honest rather than pretend.
+      return { ok: false, error: 'scan already running and cannot be cancelled' };
+    }
+    if (job.status === 'queued') {
+      this.pending = this.pending.filter(j => j.id !== id);
+      job.status = 'cancelled';
+      job.finishedAt = new Date().toISOString();
+      this._emitUpdate(job);
+      return { ok: true };
+    }
+    return { ok: false, error: `job is already ${job.status}` };
+  }
+
+  _public(job) {
+    const { result, root, ...rest } = job;
+    return { ...rest, hasResult: Boolean(result) };
+  }
+
+  _emitUpdate(job) {
+    this.emit('update', this._public(job));
+  }
+
+  _drain() {
+    while (this.running < this.concurrency && this.pending.length > 0) {
+      const job = this.pending.shift();
+      this._run(job);
+    }
+  }
+
+  async _run(job) {
+    this.running++;
+    job.status = 'running';
+    job.startedAt = new Date().toISOString();
+    job.progress = { done: 0, total: 0, current: null };
+    this._emitUpdate(job);
+
+    try {
+      if (typeof this.runScan !== 'function') {
+        throw new Error('no scan runner configured');
+      }
+      const result = await this.runScan(job.root, progress => {
+        // Real per-agent progress from the orchestrator hook. If the hook never fires
+        // (no agents applicable), progress stays 0/0 rather than inventing a number.
+        if (progress) {
+          job.progress = {
+            done: Number(progress.done) || 0,
+            total: Number(progress.total) || 0,
+            current: progress.agent || null,
+          };
+          this._emitUpdate(job);
+        }
+      });
+      job.result = result;
+      job.status = 'done';
+      job.finishedAt = new Date().toISOString();
+    } catch (err) {
+      job.status = 'failed';
+      job.error = err.message || String(err);
+      job.finishedAt = new Date().toISOString();
+    } finally {
+      this.running--;
+      this._emitUpdate(job);
+      this._trim();
+      this._drain();
+    }
+  }
+
+  _trim() {
+    // Bound memory: drop the oldest finished jobs past the retention window.
+    const finished = this.jobs.filter(j => j.status !== 'running' && j.status !== 'queued');
+    if (finished.length <= JOB_RETENTION) return;
+    const drop = new Set(finished.slice(0, finished.length - JOB_RETENTION).map(j => j.id));
+    this.jobs = this.jobs.filter(j => !drop.has(j.id));
+  }
+}
+
+/**
+ * Default scan runner: drives the real Orchestrator so the UI cannot drift from the CLI.
+ * Returns the same shape the CLI's JSON output produces.
+ */
+export async function runScanWithOrchestrator(rootPath, onProgress) {
+  const { buildOrchestratorAsync } = await import('../../agents/index.js');
+  const orchestrator = await buildOrchestratorAsync(rootPath, { quiet: true });
+
+  // runAll returns { recon, findings, agentResults } — the same telemetry the CLI
+  // report renders, so the UI cannot drift from `praxis scan`.
+  // `quiet` must be passed to runAll itself, not just the builder: runAll reads its own
+  // options object, so omitting it would print CLI spinners into the HTTP server's stdout.
+  const { findings, agentResults, recon } = await orchestrator.runAll(rootPath, { // praxis-ignore AGENT_ESCALATED_PERMISSIONS — destructuring runAll()'s result; no permission handling
+    quiet: true,
+    onProgress: info => {
+      if (typeof onProgress === 'function') onProgress(info);
+    },
+  });
+
+  return {
+    root: path.basename(rootPath),
+    agentCount: (agentResults || []).length,
+    totalFindings: (findings || []).length,
+    agents: agentResults || [],
+    recon: recon || null,
+    findings: findings || [],
+  };
+}

package/cli/core/web/projects.js

@@ -0,0 +1,146 @@
+/**
+ * Project registry for the web UI.
+ * ============================================================================
+ *
+ * The security-relevant decision (threats T2/T3 in docs/design/WEB-UI.md): the browser
+ * never sends a filesystem path.
+ *
+ * A client-supplied path would let any caller ask the server to scan `/`, read a home
+ * directory, or enumerate the host — turning "scan my code" into arbitrary file
+ * disclosure. So an operator registers projects here, by path, through the CLI or an
+ * explicit API call, and the API thereafter addresses projects by **id** only.
+ *
+ * Each registered path is resolved once and pinned, so a symlink swapped afterwards
+ * cannot silently redirect a scan somewhere else.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+
+/** Hard ceiling so a runaway caller cannot fill the registry. */
+export const MAX_PROJECTS = 64;
+
+export function registryDir() {
+  // Overridable so tests (and sandboxed runs) do not write into the real home
+  // directory. Defaults to ~/.praxis/web, which is outside any scanned project so a
+  // scan never picks up the UI's own state.
+  const base = process.env.PRAXIS_WEB_HOME || path.join(os.homedir(), '.praxis', 'web');
+  return base;
+}
+
+function registryPath() {
+  return path.join(registryDir(), 'projects.json');
+}
+
+/**
+ * Validates and pins a candidate project path.
+ * @returns {{ok: true, root: string, name: string} | {ok: false, error: string}}
+ */
+export function resolveProject(candidate) {
+  if (typeof candidate !== 'string' || candidate.trim() === '') {
+    return { ok: false, error: 'path must be a non-empty string' };
+  }
+  let resolved;
+  try {
+    resolved = fs.realpathSync(path.resolve(candidate.trim()));
+  } catch (err) {
+    return { ok: false, error: `cannot resolve path: ${err.message}` };
+  }
+  let stat;
+  try {
+    stat = fs.statSync(resolved);
+  } catch (err) {
+    return { ok: false, error: `cannot stat path: ${err.message}` };
+  }
+  if (!stat.isDirectory()) {
+    return { ok: false, error: 'project path must be a directory' };
+  }
+  return { ok: true, root: resolved, name: path.basename(resolved) || resolved };
+}
+
+/** Reads the registry; a missing or corrupt file yields an empty registry. */
+export function readRegistry() {
+  try {
+    const data = JSON.parse(fs.readFileSync(registryPath(), 'utf8'));
+    if (!data || !Array.isArray(data.projects)) return { projects: [] };
+    return {
+      projects: data.projects.filter(p => p && typeof p.id === 'string' && typeof p.root === 'string'),
+    };
+  } catch {
+    return { projects: [] };
+  }
+}
+
+function writeRegistry(state) {
+  fs.mkdirSync(registryDir(), { recursive: true });
+  fs.writeFileSync(registryPath(), JSON.stringify(state, null, 2), 'utf8');
+}
+
+/** Lists registered projects, annotated with whether the pinned path still exists. */
+export function listProjects() {
+  return readRegistry().projects.map(p => {
+    let present = false;
+    try {
+      present = fs.statSync(p.root).isDirectory();
+    } catch { present = false; }
+    return { id: p.id, name: p.name, root: p.root, present };
+  });
+}
+
+/**
+ * Registers a project directory. Idempotent per resolved path.
+ * @returns {{ok: true, project: object, created: boolean} | {ok: false, error: string}}
+ */
+export function addProject(candidate) {
+  const resolved = resolveProject(candidate);
+  if (!resolved.ok) return { ok: false, error: resolved.error };
+
+  const state = readRegistry();
+  const existing = state.projects.find(p => p.root === resolved.root);
+  if (existing) {
+    return { ok: true, project: existing, created: false };
+  }
+  if (state.projects.length >= MAX_PROJECTS) {
+    return { ok: false, error: `registry is full (max ${MAX_PROJECTS} projects)` };
+  }
+
+  const project = {
+    id: crypto.randomUUID(),
+    name: resolved.name,
+    root: resolved.root,
+    addedAt: new Date().toISOString(),
+  };
+  state.projects.push(project);
+  writeRegistry(state);
+  return { ok: true, project, created: true };
+}
+
+/** Removes a project by id. */
+export function removeProject(id) {
+  const state = readRegistry();
+  const before = state.projects.length;
+  state.projects = state.projects.filter(p => p.id !== id);
+  if (state.projects.length === before) return { ok: false, error: 'no such project' };
+  writeRegistry(state);
+  return { ok: true };
+}
+
+/**
+ * Looks up a project by id. This is the only way the API turns a client value into a
+ * path — a client-supplied path is never resolved here.
+ *
+ * Returns `{ok:false}` for an unknown id, and flags a project whose pinned path has
+ * since disappeared so the caller can report that honestly rather than failing opaquely.
+ */
+export function getProject(id) {
+  if (typeof id !== 'string' || id === '') return { ok: false, error: 'project id required' };
+  const found = readRegistry().projects.find(p => p.id === id);
+  if (!found) return { ok: false, error: 'unknown project id' };
+  let present = true;
+  try {
+    present = fs.statSync(found.root).isDirectory();
+  } catch { present = false; }
+  return { ok: true, project: { ...found, present } };
+}