praxis-sec 1.0.0

package/cli/core/ast/scope-tree.js

@@ -0,0 +1,287 @@
+/**
+ * Praxis Scope Tree & Symbol Resolver
+ * ===================================
+ *
+ * Constructs lexical scopes and resolves symbols across JavaScript,
+ * TypeScript, and Python codebases.
+ *
+ * Provides:
+ * 1. Scope hierarchy: Global, Function, Class, Block, TryCatch.
+ * 2. Symbol resolution: declarations, parameter origin, constant folding,
+ *    and variable mutation tracking.
+ * 3. Enclosing scope queries: `getScopeAt(line)` for accurate block boundaries.
+ */
+
+import { NodeType } from './parser.js';
+
+export const ScopeType = {
+  GLOBAL: 'GLOBAL',
+  FUNCTION: 'FUNCTION',
+  CLASS: 'CLASS',
+  BLOCK: 'BLOCK',
+  TRY_CATCH: 'TRY_CATCH',
+};
+
+export class Scope {
+  constructor(type, range, parent = null, name = '') {
+    this.type = type;
+    this.name = name;
+    this.range = range || { startLine: 1, endLine: 100000 };
+    this.parent = parent;
+    this.children = [];
+    this.variables = new Map(); // name -> { kind, init, isStatic, line, isParam, sanitized }
+    this.imports = new Map();   // name -> { source, importedName, line }
+  }
+
+  containsLine(line) {
+    return line >= this.range.startLine && line <= this.range.endLine;
+  }
+
+  addVariable(name, info) {
+    this.variables.set(name, {
+      name,
+      kind: info.kind || 'var',
+      init: info.init || null,
+      isStatic: info.isStatic ?? false,
+      line: info.line || 1,
+      isParam: info.isParam ?? false,
+      sanitized: info.sanitized ?? false,
+      assignments: info.assignments || [],
+    });
+  }
+
+  addImport(localName, info) {
+    this.imports.set(localName, info);
+  }
+
+  lookupVariable(name) {
+    if (this.variables.has(name)) {
+      return this.variables.get(name);
+    }
+    if (this.parent) {
+      return this.parent.lookupVariable(name);
+    }
+    return null;
+  }
+
+  lookupImport(name) {
+    if (this.imports.has(name)) {
+      return this.imports.get(name);
+    }
+    if (this.parent) {
+      return this.parent.lookupImport(name);
+    }
+    return null;
+  }
+}
+
+export class ScopeTree {
+  constructor(ast, code = '') {
+    this.ast = ast;
+    this.code = code;
+    this.globalScope = new Scope(ScopeType.GLOBAL, ast?.range || { startLine: 1, endLine: 10000 });
+    this._buildTree();
+  }
+
+  static build(ast, code = '') {
+    return new ScopeTree(ast, code);
+  }
+
+  _buildTree() {
+    if (!this.ast || !this.ast.body) return;
+
+    for (const node of this.ast.body) {
+      this._processNode(node, this.globalScope);
+    }
+  }
+
+  _processNode(node, currentScope) {
+    if (!node) return;
+
+    switch (node.type) {
+      case NodeType.FUNCTION_DECLARATION: {
+        const fnScope = new Scope(
+          ScopeType.FUNCTION,
+          node.range,
+          currentScope,
+          node.name
+        );
+        currentScope.children.push(fnScope);
+        currentScope.addVariable(node.name, {
+          kind: 'function',
+          init: node.name,
+          isStatic: true,
+          line: node.line,
+        });
+
+        // Register parameters
+        if (Array.isArray(node.params)) {
+          for (const param of node.params) {
+            fnScope.addVariable(param, {
+              kind: 'param',
+              init: null,
+              isStatic: false,
+              isParam: true,
+              line: node.line,
+            });
+          }
+        }
+        break;
+      }
+
+      case NodeType.CLASS_DECLARATION: {
+        const classScope = new Scope(
+          ScopeType.CLASS,
+          node.range,
+          currentScope,
+          node.name
+        );
+        currentScope.children.push(classScope);
+        currentScope.addVariable(node.name, {
+          kind: 'class',
+          init: node.name,
+          isStatic: true,
+          line: node.line,
+        });
+        break;
+      }
+
+      case NodeType.VARIABLE_DECLARATION: {
+        if (Array.isArray(node.declarations)) {
+          for (const decl of node.declarations) {
+            currentScope.addVariable(decl.name, {
+              kind: node.kind,
+              init: decl.init,
+              isStatic: decl.isStatic,
+              line: decl.line,
+            });
+          }
+        }
+        break;
+      }
+
+      case NodeType.ASSIGNMENT: {
+        const existing = currentScope.lookupVariable(node.target);
+        if (existing) {
+          existing.assignments = existing.assignments || [];
+          existing.assignments.push({
+            value: node.value,
+            isStatic: node.isStatic,
+            line: node.line,
+          });
+          if (!node.isStatic) {
+            existing.isStatic = false;
+          }
+        } else {
+          currentScope.addVariable(node.target, {
+            kind: 'assignment',
+            init: node.value,
+            isStatic: node.isStatic,
+            line: node.line,
+          });
+        }
+        break;
+      }
+
+      case NodeType.IMPORT_DECLARATION: {
+        if (Array.isArray(node.importedNames)) {
+          for (const name of node.importedNames) {
+            currentScope.addImport(name, {
+              source: node.source,
+              importedName: name,
+              line: node.line,
+            });
+          }
+        }
+        break;
+      }
+
+      case NodeType.TRY_STATEMENT: {
+        const tryScope = new Scope(
+          ScopeType.TRY_CATCH,
+          node.range,
+          currentScope,
+          'try'
+        );
+        currentScope.children.push(tryScope);
+        break;
+      }
+
+      default:
+        break;
+    }
+  }
+
+  /**
+   * Find the deepest enclosing scope for a given line number.
+   *
+   * @param {number} line — 1-indexed line number
+   * @returns {Scope}     — Deepest matching scope (defaults to globalScope)
+   */
+  getScopeAt(line) {
+    let current = this.globalScope;
+
+    const findDeepest = (scope) => {
+      for (const child of scope.children) {
+        if (child.containsLine(line)) {
+          current = child;
+          findDeepest(child);
+          break;
+        }
+      }
+    };
+
+    findDeepest(this.globalScope);
+    return current;
+  }
+
+  /**
+   * Check if a line is within a function scope.
+   */
+  getEnclosingFunction(line) {
+    let scope = this.getScopeAt(line);
+    while (scope) {
+      if (scope.type === ScopeType.FUNCTION) {
+        return scope;
+      }
+      scope = scope.parent;
+    }
+    return null;
+  }
+
+  /**
+   * Check if a line is inside a try/catch block.
+   */
+  isInTryCatch(line) {
+    let scope = this.getScopeAt(line);
+    while (scope) {
+      if (scope.type === ScopeType.TRY_CATCH) {
+        return true;
+      }
+      scope = scope.parent;
+    }
+    return false;
+  }
+
+  /**
+   * Check if a variable at a given line is static (never received user input).
+   */
+  isVariableStatic(name, line) {
+    const scope = this.getScopeAt(line);
+    const variable = scope.lookupVariable(name);
+    if (!variable) return null;
+    return variable.isStatic === true && !variable.isParam;
+  }
+
+  /**
+   * Check if a variable originated from function parameters or known input.
+   */
+  isVariableUserInput(name, line) {
+    const scope = this.getScopeAt(line);
+    const variable = scope.lookupVariable(name);
+    if (!variable) return false;
+    return variable.isParam === true;
+  }
+}
+
+export default ScopeTree;

package/cli/core/ast/taint-tracker.js

@@ -0,0 +1,158 @@
+/**
+ * Praxis Taint Tracker & Dataflow Engine
+ * =====================================
+ *
+ * Performs intra-file source-to-sink dataflow analysis to determine whether
+ * dangerous sinks (SQL, Command execution, RAG ingestion, Prompt injection)
+ * receive tainted untrusted input or safe/sanitized values.
+ */
+
+import { ASTParser } from './parser.js';
+import { ScopeTree } from './scope-tree.js';
+
+// =============================================================================
+// PATTERNS & REGEXES
+// =============================================================================
+
+export const UNTRUSTED_SOURCES = [
+  /\breq\.(?:body|query|params|headers|file|files|cookies)\b/,
+  /\brequest\.(?:body|query|params|args|form|json|data|GET|POST|headers|files)\b/,
+  /\bctx\.(?:request|query|params|body)\b/,
+  /\bevent\.(?:body|queryStringParameters|headers)\b/,
+  /\bsearchParams\.get\s*\(/,
+  /\bformData\.(?:get|getAll)\s*\(/,
+  /\bprocess\.argv\b/,
+  /\bsys\.argv\b/,
+  /\binput\s*\(/,
+  /\b(?:userInput|user_input|userPayload|user_payload|userQuery|user_query|userPrompt|user_prompt|userMessage|user_message|rawInput|raw_input)\b/i,
+];
+
+export const SANITIZERS = [
+  { name: 'parseInt/parseFloat/Number', regex: /\b(?:parseInt|parseFloat|Number|int|float)\s*\(/ },
+  { name: 'DOMPurify', regex: /\bDOMPurify\.sanitize\s*\(/ },
+  { name: 'sanitizeHtml', regex: /\bsanitize(?:Html)?\s*\(/i },
+  { name: 'validator.escape', regex: /\bvalidator\.escape\s*\(/ },
+  { name: 'encodeURIComponent', regex: /\bencodeURIComponent\s*\(/ },
+  { name: 'shlex.quote', regex: /\bshlex\.quote\s*\(/ },
+  { name: 'html.escape', regex: /\bhtml\.escape\s*\(/ },
+  { name: 'schema.safeParse/Zod', regex: /\b(?:schema\.safeParse|safeParse|schema\.parse|zod|yup|ajv)\b/i },
+  { name: 'parameterized/prepared', regex: /(?:\$1|\$\d+|\?|Prisma\.sql|prepared|bindValue|bindParam)/i },
+];
+
+export class TaintTracker {
+  /**
+   * Analyze dataflow for a finding's code context.
+   *
+   * @param {object} context — { file, line, matched, code, ast, scopeTree }
+   * @returns {object} — { isTainted, isSanitized, isStatic, reason, confidenceAdjustment }
+   */
+  static evaluateFinding(context) {
+    const { line, matched = '', code = '' } = context;
+    const lines = code ? code.split('\n') : [];
+    const findingLine = lines[line - 1] || matched;
+
+    // ── 1. Comment check ──────────────────────────────────────────────────────
+    if (/^\s*(?:\/\/|#|\*|\/\*|<!--)/.test(findingLine)) {
+      return {
+        isTainted: false,
+        isSanitized: true,
+        isStatic: true,
+        reason: 'Finding is inside a comment line',
+        confidenceAdjustment: 'low',
+      };
+    }
+
+    // ── 2. Direct string literal / constant check ────────────────────────────
+    if (/^['"][^'"]*['"]$/.test(matched.trim())) {
+      return {
+        isTainted: false,
+        isSanitized: false,
+        isStatic: true,
+        reason: 'Value is a static string literal without interpolation',
+        confidenceAdjustment: 'low',
+      };
+    }
+
+    // ── 3. Check for immediate user input on the finding line ─────────────────
+    const hasDirectUserInput = UNTRUSTED_SOURCES.some(src => src.test(findingLine));
+    const hasDirectSanitization = SANITIZERS.some(s => s.regex.test(findingLine));
+
+    if (hasDirectSanitization && !hasDirectUserInput) {
+      return {
+        isTainted: false,
+        isSanitized: true,
+        isStatic: false,
+        reason: 'Finding is wrapped in active sanitization/validation logic',
+        confidenceAdjustment: 'low',
+      };
+    }
+
+    // ── 4. AST Scope-based upstream trace ─────────────────────────────────────
+    let scopeTree = context.scopeTree;
+    if (!scopeTree && code) {
+      const parsed = ASTParser.parse(code, context.file || '');
+      scopeTree = ScopeTree.build(parsed.ast, code);
+    }
+
+    if (scopeTree) {
+      const scope = scopeTree.getScopeAt(line);
+      const encFn = scopeTree.getEnclosingFunction(line);
+      const inTryCatch = scopeTree.isInTryCatch(line);
+
+      // Check the lines within the enclosing scope (not bleeding into other functions)
+      const startLine = scope.range.startLine;
+      const endLine = Math.min(line, scope.range.endLine);
+      const upstreamLines = lines.slice(startLine - 1, endLine - 1);
+      const upstreamText = upstreamLines.join('\n');
+
+      const hasScopeUserInput = UNTRUSTED_SOURCES.some(src => src.test(upstreamText));
+      const matchedSanitizer = SANITIZERS.find(s => s.regex.test(upstreamText));
+
+      if (matchedSanitizer && !hasDirectUserInput) {
+        return {
+          isTainted: false,
+          isSanitized: true,
+          isStatic: false,
+          sanitizer: matchedSanitizer.name,
+          reason: `Sanitization detected in enclosing scope via ${matchedSanitizer.name}`,
+          confidenceAdjustment: 'downgrade',
+        };
+      }
+
+      if (hasScopeUserInput || hasDirectUserInput || encFn?.params?.length > 0) {
+        return {
+          isTainted: true,
+          isSanitized: false,
+          isStatic: false,
+          inTryCatch,
+          reason: 'Untrusted user input flows into this sink within function scope',
+          confidenceAdjustment: 'confirm',
+        };
+      }
+
+      // Check if variables referenced in matched text are static in scope
+      const idMatches = matched.match(/[a-zA-Z_$][a-zA-Z0-9_$]*/g) || [];
+      const staticVars = idMatches.filter(id => scopeTree.isVariableStatic(id, line));
+      if (staticVars.length > 0 && !hasScopeUserInput) {
+        return {
+          isTainted: false,
+          isSanitized: false,
+          isStatic: true,
+          reason: `Referenced variable(s) [${staticVars.join(', ')}] are statically initialized constants`,
+          confidenceAdjustment: 'downgrade',
+        };
+      }
+    }
+
+    // Default neutral
+    return {
+      isTainted: hasDirectUserInput,
+      isSanitized: hasDirectSanitization,
+      isStatic: false,
+      reason: 'Standard pattern match',
+      confidenceAdjustment: null,
+    };
+  }
+}
+
+export default TaintTracker;

package/cli/core/branding.js

@@ -0,0 +1,37 @@
+/**
+ * Praxis branding & identity
+ * ==========================
+ *
+ * Single source of truth for the banner, tagline, and product name used
+ * across the CLI. Importing this avoids hardcoded "praxis" / "Praxis"
+ * strings drifting out of sync after the rebrand.
+ */
+
+import chalk from 'chalk';
+
+export const PRODUCT_NAME = 'praxis';
+export const PRODUCT_DISPLAY = 'Praxis';
+export const TAGLINE = 'From finding to fix, on autopilot.';
+export const SUBTITLE = '28 agents. AI-native security with agentic remediation.';
+
+/**
+ * Print the praxis ASCII banner. Call at the top of any command that
+ * should show branding (mostly `--help` and `praxis` with no args).
+ */
+export function printBanner(version) {
+  console.log();
+  console.log(chalk.cyan('██████╗ ██████╗  █████╗ ██╗  ██╗██╗███████╗'));
+  console.log(chalk.cyan('██╔══██╗██╔══██╗██╔══██╗╚██╗██╔╝██║██╔════╝'));
+  console.log(chalk.cyan('██████╔╝██████╔╝███████║ ╚███╔╝ ██║███████╗'));
+  console.log(chalk.cyan('██╔═══╝ ██╔══██╗██╔══██║ ██╔██╗ ██║╚════██║'));
+  console.log(chalk.cyan('██║     ██║  ██║██║  ██║██╔╝ ██╗██║███████║'));
+  console.log(chalk.cyan('╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚══════╝'));
+  console.log();
+  console.log(chalk.white.bold(`  ${TAGLINE}`));
+  if (version) {
+    console.log(chalk.gray(`  v${version} · ${SUBTITLE}`));
+  } else {
+    console.log(chalk.gray(`  ${SUBTITLE}`));
+  }
+  console.log();
+}

package/cli/core/env.js

@@ -0,0 +1,38 @@
+/**
+ * Minimal .env loader (no dependency).
+ *
+ * Loads KEY=VALUE pairs from <rootPath>/.env into process.env without
+ * overriding variables that are already set (real environment wins).
+ * Lines starting with # and blank lines are ignored; values may be
+ * wrapped in single or double quotes.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export function loadDotEnv(rootPath) {
+  try {
+    const envPath = path.join(rootPath, '.env');
+    if (!fs.existsSync(envPath)) return false;
+
+    const content = fs.readFileSync(envPath, 'utf-8');
+    for (const line of content.split('\n')) {
+      const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+      if (!m) continue;
+      const key = m[1];
+      let val = m[2].trim();
+      if (
+        (val.startsWith('"') && val.endsWith('"') && val.length >= 2) ||
+        (val.startsWith("'") && val.endsWith("'") && val.length >= 2)
+      ) {
+        val = val.slice(1, -1);
+      }
+      if (process.env[key] === undefined || process.env[key] === '') {
+        process.env[key] = val;
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

package/cli/core/errors.js

@@ -0,0 +1,61 @@
+/**
+ * Error handling helpers
+ * ======================
+ *
+ * Replacement for the ~124 silent `try { ... } catch { /* skip *\/ }`
+ * blocks scattered across the codebase. Errors are no longer invisible:
+ * they surface under `--verbose` (or when `PRAXIS_DEBUG=1`).
+ */
+
+import * as output from '../utils/output.js';
+
+const DEBUG = process.env.PRAXIS_DEBUG === '1' || process.env.PRAXIS_DEBUG === 'true';
+
+/**
+ * Run `fn`, return its result, and on throw return `fallback` instead.
+ * Optionally logs the error under verbose/debug mode so it stops being
+ * invisible.
+ *
+ *   const config = safeCatch(() => JSON.parse(raw), {}, { ctx: 'config' });
+ */
+export function safeCatch(fn, fallback, options = {}) {
+  const { ctx = 'unknown', verbose = false } = options;
+  try {
+    return fn();
+  } catch (err) {
+    if (DEBUG || verbose) {
+      output.warning(`[${ctx}] swallowed: ${err.message}`);
+    }
+    return fallback;
+  }
+}
+
+/**
+ * Async variant.
+ */
+export async function safeCatchAsync(fn, fallback, options = {}) {
+  const { ctx = 'unknown', verbose = false } = options;
+  try {
+    return await fn();
+  } catch (err) {
+    if (DEBUG || verbose) {
+      output.warning(`[${ctx}] swallowed: ${err.message}`);
+    }
+    return fallback;
+  }
+}
+
+/**
+ * Convert any value into an Error so callers can rely on `.message` and
+ * `.stack`. Useful at boundaries (catch arms with `catch (e)` where `e`
+ * may be a string).
+ */
+export function toError(value) {
+  if (value instanceof Error) return value;
+  if (typeof value === 'string') return new Error(value);
+  try {
+    return new Error(JSON.stringify(value));
+  } catch {
+    return new Error(String(value));
+  }
+}

package/cli/core/fs.js

@@ -0,0 +1,62 @@
+/**
+ * Path & filesystem helpers
+ * =========================
+ *
+ * One implementation of the path-validation logic that was previously
+ * duplicated 16+ times across `cli/commands/`. Commands should use these
+ * instead of rolling their own `path.resolve + fs.existsSync` checks.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import * as output from '../utils/output.js';
+
+/**
+ * Resolve a user-supplied path to an absolute path and verify it exists.
+ *
+ * Exits the process with code 1 (and prints a friendly error) if the path
+ * is missing, unless `{ exitOnMissing: false }` is passed. Returns the
+ * absolute path on success.
+ */
+export function validatePath(targetPath, options = {}) {
+  const { exitOnMissing = true, label = 'path' } = options;
+  const absolutePath = path.resolve(targetPath || '.');
+
+  if (!fs.existsSync(absolutePath)) {
+    if (exitOnMissing) {
+      output.error(`${label} does not exist: ${absolutePath}`);
+      process.exit(1);
+    }
+    return null;
+  }
+
+  return absolutePath;
+}
+
+/**
+ * Resolve a path and require that it points at a directory. Same exit
+ * semantics as `validatePath`.
+ */
+export function validateDir(targetPath, options = {}) {
+  const absolutePath = validatePath(targetPath, options);
+  if (!absolutePath) return null;
+
+  const stat = fs.statSync(absolutePath);
+  if (!stat.isDirectory()) {
+    if (options.exitOnMissing !== false) {
+      output.error(`expected a directory, got a file: ${absolutePath}`);
+      process.exit(1);
+    }
+    return null;
+  }
+  return absolutePath;
+}
+
+/**
+ * Synchronously and atomically ensure a directory exists. Mirrors the
+ * `mkdir -p` idiom used throughout the codebase.
+ */
+export function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}