praxis-sec 1.0.0

package/docs/design/WEB-UI.md

@@ -0,0 +1,82 @@
+# Praxis Web UI — design & threat model
+
+> **Status:** design agreed; v1 implemented read-only (scan orchestration).
+> Feature tracking: `P-IMP-052` in `docs/internal/IMPROVEMENT-PLAN.md`.
+>
+> This document exists because a web UI for Praxis is the one place where adding a
+> feature means adding an **attack surface** to a security tool. A CLI runs with the
+> privileges of the person who typed the command. A server runs with whatever
+> privileges the person who *connected to it* has — and may have more.
+
+---
+
+## 1. What it is
+
+A local web app for driving scans and managing scan projects:
+
+- register projects (directories to scan)
+- run single or concurrent scans
+- watch live progress
+- browse findings, agents, standards, and the fix ledger
+- manage baselines
+
+Reuses the existing `Orchestrator` as the scan engine — the UI never reimplements
+detection. All UI is **vanilla JS served from the CLI**, honouring `AGENTS.md`'s
+no-build-step rule: no bundler, no framework, no network fetch of assets. Reports use
+the shared `cli/core/output/html-theme.js`.
+
+## 2. Threat model — the part that matters
+
+Praxis reads source code, prints code excerpts in findings, and can **write code**
+(`praxis fix` applies LLM-guided patches). Exposing that over HTTP is remote code
+execution by design if done carelessly. Threats, ranked:
+
+| # | Threat | Why it is serious | Mitigation in v1 |
+|---|--------|-------------------|------------------|
+| T1 | **Fix application over the network** | An endpoint that accepts a path and writes a patch is arbitrary code write on the host. Even "verified" patches are LLM-authored. | **Not implemented.** v1 is read-only. Remediation stays in the CLI, where a human sees the diff. |
+| T2 | **Arbitrary filesystem read via project paths** | A client-supplied path lets a caller scan `/`, read `~/.ssh`, or enumerate the host. | Projects are **registered explicitly by the operator** and stored server-side. The client sends a project *id*, never a path. Paths are resolved once at registration and pinned. |
+| T3 | **Finding data leaks other projects** | Findings contain file paths and source excerpts. A multi-project UI that serves them to any caller leaks the whole workspace. | Every API call is scoped to a registered project id. No endpoint enumerates arbitrary paths. Loopback-only by default. |
+| T4 | **Remote binding without auth** | `0.0.0.0` with no auth exposes everything above to the network. | **Loopback-only by default.** A non-loopback bind requires an explicit `--allow-remote` flag **and** refuses to start unless a token is provided; the token is required in a header. |
+| T5 | **CSRF / DNS rebinding from a browser** | A malicious page can POST to `127.0.0.1:PORT` while the victim has the UI open. | All mutating endpoints require a custom header (`X-Praxis-Client`) that a cross-origin form cannot set, plus `Origin` checking. This is the standard localhost-server defence. |
+| T6 | **Path traversal in served assets** | Serving the frontend from disk invites `../../`. | Frontend is generated in memory from the shared theme. No static file serving. |
+| T7 | **Resource exhaustion** | 28 agents × many projects; a scan queue can be flooded. | Bounded concurrency, a max project count, and per-request limits. |
+| T8 | **Scan data egress** | `--deep` sends code to an LLM provider. | The UI does **not** enable `--deep`; LLM-backed analysis stays a CLI opt-in so egress is always an explicit human decision. |
+
+### Explicit non-goals for v1
+
+- No authentication, no multi-user, no tenancy (it binds to loopback).
+- No fix application, no `--agentic`, no `--deep`.
+- No remote/multi-tenant deployment story. Exposing this to a network is out of scope
+  until there is real auth, and shipping that is a separate, larger piece of work.
+
+## 3. Shape
+
+```
+cli/commands/web.js          command wiring, bind/guard logic
+cli/core/web/
+  server.js                  node:http server, routing, guards
+  projects.js                project registry (pinned, resolved paths)
+  jobs.js                    bounded job queue driving Orchestrator
+  api.js                     JSON API handlers
+```
+
+Storage under `.praxis/web/` in the * Praxis home* (`~/.praxis/web`), not inside a
+scanned project, so scanning a project never reads the UI's own state.
+
+Endpoints (all project-scoped by id):
+
+```
+GET  /api/projects                 list registered projects
+POST /api/projects                 register (operator-supplied path, server-side)
+POST /api/projects/:id/scan        enqueue a scan
+GET  /api/jobs                     job states
+GET  /api/jobs/:id/events          SSE progress stream
+GET  /api/projects/:id/report      full JSON report (reuses existing renderer)
+```
+
+## 4. Honest limitations
+
+- Scanning still runs as the invoking user; the UI does not sandbox the scan.
+- Loopback-only is the safe default, not a security boundary against a local attacker.
+- Progress is best-effort; the orchestrator reports per-agent completion, not per-file.
+- No incremental/streaming findings yet — the report renders after the scan finishes.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "praxis-sec",
+  "version": "1.0.0",
+  "description": "Praxis — From finding to fix, on autopilot. AI-native security CLI with 28 parallel agents covering AI / MCP / skill threats, OWASP LLM Top 10, multi-source supply-chain intel (OSV / GHSA / KEV / EPSS / NVD / Gitleaks + optional paid feeds), secret scanning, and an LLM-powered agentic remediation loop.",
+  "main": "cli/index.js",
+  "bin": {
+    "praxis": "cli/bin/praxis.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "node --test cli/__tests__/intel.test.js cli/__tests__/agents.test.js cli/__tests__/core.test.js cli/__tests__/standards.test.js cli/__tests__/model-file-scanner.test.js cli/__tests__/prompt-injection-prober.test.js cli/__tests__/ast-engine.test.js cli/__tests__/benchmark.test.js cli/__tests__/redteam.test.js cli/__tests__/html-reporter.test.js cli/__tests__/scan-fingerprint.test.js cli/__tests__/fix-ledger.test.js cli/__tests__/threatpack-probes.test.js cli/__tests__/score-history.test.js cli/__tests__/web-ui.test.js cli/__tests__/rule-portability.test.js",
+    "test:determinism": "node scripts/check-determinism.mjs .",
+    "lint": "eslint cli/",
+    "praxis": "node cli/bin/praxis.js"
+  },
+  "keywords": [
+    "security",
+    "praxis",
+    "ai-security",
+    "agentic-security",
+    "llm-security",
+    "mcp-security",
+    "prompt-injection",
+    "supply-chain",
+    "secrets",
+    "scanner",
+    "sast",
+    "devsecops",
+    "red-team",
+    "vulnerability-scanner",
+    "sbom",
+    "abom",
+    "owasp-llm",
+    "agentic-remediation",
+    "threat-intel",
+    "cve",
+    "kev",
+    "epss",
+    "osv",
+    "ghsa",
+    "cli"
+  ],
+  "author": "Praxis contributors",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "cli/",
+    "!cli/__tests__/",
+    "checklists/",
+    "configs/",
+    "snippets/",
+    "ai-defense/",
+    "docs/",
+    "!docs/internal/",
+    "scripts/check-determinism.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.3",
+    "ora": "^8.0.1",
+    "write-file-atomic": "^7.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.18.0"
+  }
+}

package/scripts/check-determinism.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * Determinism gate (P-IMP-053).
+ *
+ * Scans a target twice and compares the *detection* identities produced by each run.
+ * A scanner that returns different findings for an unchanged tree is not a scanner you
+ * can baseline, gate CI on, or quote a number from — so this asserts the property
+ * directly instead of hoping for it.
+ *
+ * Only detection identity (`file:rule`) is compared, deliberately excluding severity,
+ * line numbers and messages: a change in scoring or message wording is not a change in
+ * what Praxis found, and failing on it would make the gate noise rather than signal.
+ *
+ * Usage:
+ *   node scripts/check-determinism.mjs [target] [--runs=2] [--timeout=60000]
+ *
+ * Exit codes:
+ *   0  deterministic (identical detection identities across runs)
+ *   1  drift detected — the diff is printed
+ *   2  the scan itself could not be run
+ */
+
+import { spawnSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+// Comparison semantics come from the library, not a copy: the helper that CI relies on
+// must be the same one the unit tests cover.
+import { diffFindings } from '../cli/utils/scan-fingerprint.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..');
+const CLI = path.join(REPO_ROOT, 'cli', 'bin', 'praxis.js');
+
+const argv = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const hit = argv.find(a => a.startsWith(`--${name}=`));
+  return hit ? hit.split('=')[1] : fallback;
+};
+const positional = argv.filter(a => !a.startsWith('--'));
+const target = positional[0] || '.';
+const runs = Math.max(2, parseInt(flag('runs', '2'), 10));
+const timeout = parseInt(flag('timeout', '120000'), 10);
+
+function scan(label) {
+  process.stderr.write(`  run ${label}…\n`);
+  const res = spawnSync(
+    process.execPath,
+    [CLI, 'scan', 'full', target, '--no-deps', '--no-cache', '--json', '--timeout', String(timeout)],
+    { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, cwd: REPO_ROOT }
+  );
+  if (res.status !== 0) {
+    process.stderr.write(`  scan failed (exit ${res.status}): ${(res.stderr || '').slice(-500)}\n`);
+    return null;
+  }
+  // The CLI pretty-prints the JSON object; take from the first brace onward.
+  const start = res.stdout.indexOf('{');
+  if (start < 0) {
+    process.stderr.write('  scan produced no JSON\n');
+    return null;
+  }
+  try {
+    return JSON.parse(res.stdout.slice(start));
+  } catch (err) {
+    process.stderr.write(`  could not parse scan JSON: ${err.message}\n`);
+    return null;
+  }
+}
+
+console.log(`Determinism gate — ${runs} runs over "${target}"\n`);
+
+const results = [];
+for (let i = 1; i <= runs; i++) {
+  const out = scan(`${i}/${runs}`);
+  if (!out) process.exit(2);
+  results.push(out);
+}
+
+// Fingerprints first: if these differ, a data or runtime change explains any drift.
+const fingerprints = results.map(r => r.fingerprint ?? null);
+const fpStable = fingerprints.every(f => JSON.stringify(f) === JSON.stringify(fingerprints[0]));
+console.log(`\nFingerprint stable across runs: ${fpStable ? 'yes' : 'NO — inputs differ, drift is expected'}`);
+for (const f of fingerprints) {
+  if (!f) continue;
+  const d = f.data || {};
+  console.log(`  praxis ${f.tool ?? '?'} · node ${f.node ?? '?'} · probes v${d.probeCorpus?.version ?? '?'}(${d.probeCorpus?.items ?? '?'}) · threatpack v${d.threatPack?.version ?? '?'}(${d.threatPack?.items ?? '?'}) · files ${f.filesScanned ?? '?'}`);
+}
+
+const base = results[0].findings || [];
+const baseIdentityCount = new Set(base.map(f => `${f.file ?? '?'}::${f.rule ?? '?'}`)).size;
+let drifted = false;
+
+for (let i = 1; i < results.length; i++) {
+  const other = results[i].findings || [];
+  const { added, removed, common } = diffFindings(base, other);
+  const total = baseIdentityCount || 1;
+  const drift = Math.round(((added.length + removed.length) / total) * 10000) / 100;
+
+  console.log(`\nRun 1 vs run ${i + 1}: ${common} shared identities, ${added.length} added, ${removed.length} removed (${drift}% drift)`);
+  console.log(`  (raw findings: ${base.length} vs ${other.length})`);
+  if (added.length) {
+    console.log('  + appeared:');
+    added.slice(0, 20).forEach(x => console.log(`      ${x}`));
+    if (added.length > 20) console.log(`      …and ${added.length - 20} more`);
+  }
+  if (removed.length) {
+    console.log('  - disappeared:');
+    removed.slice(0, 20).forEach(x => console.log(`      ${x}`));
+    if (removed.length > 20) console.log(`      …and ${removed.length - 20} more`);
+  }
+  if (added.length || removed.length) drifted = true;
+}
+
+if (drifted) {
+  console.log('\nFAIL — detection is not deterministic for an unchanged tree.');
+  console.log('Detection identities must be stable. Investigate before trusting or baselining these numbers.');
+  process.exit(1);
+}
+
+console.log(`\nPASS — detection identical across ${runs} runs (${baseIdentityCount} distinct identities across ${base.length} raw findings).`);

package/snippets/README.md

@@ -0,0 +1,122 @@
+# Security Snippets
+
+**Copy-paste code blocks for common security patterns.**
+
+This folder contains drop-in code snippets for securing your application. Each snippet is heavily commented to explain *why* it works.
+
+---
+
+## Available Snippets
+
+### Rate Limiting
+
+| File | Description |
+|------|-------------|
+| [upstash-ratelimit.ts](./rate-limiting/upstash-ratelimit.ts) | Production-ready rate limiting with Upstash Redis. Includes different limiters for API, auth, and AI endpoints. |
+| [nextjs-middleware.ts](./rate-limiting/nextjs-middleware.ts) | In-memory rate limiting at the Next.js middleware level. Good for development or simple deployments. |
+
+**Quick Start:**
+```typescript
+import { apiRatelimit } from './rate-limiting/upstash-ratelimit';
+
+const { success } = await apiRatelimit.limit(userId);
+if (!success) {
+  return new Response('Too Many Requests', { status: 429 });
+}
+```
+
+---
+
+### Authentication
+
+| File | Description |
+|------|-------------|
+| [jwt-checklist.md](./auth/jwt-checklist.md) | Complete JWT security checklist. Covers algorithms, token lifetime, storage, validation, and revocation. |
+
+**Key Points:**
+- Use RS256/ES256, not HS256 with weak secrets
+- Access tokens: 15-60 minutes max
+- Store in httpOnly cookies, not localStorage
+- Always validate issuer and audience claims
+
+---
+
+### API Security
+
+| File | Description |
+|------|-------------|
+| [cors-config.ts](./api-security/cors-config.ts) | CORS configurations for Next.js, Express, Fastify, Hono, and Vercel Edge. |
+| [input-validation.ts](./api-security/input-validation.ts) | Zod schemas and validation patterns for API endpoints. Includes file upload validation. |
+| [api-security-checklist.md](./api-security/api-security-checklist.md) | Comprehensive API security checklist based on OWASP API Security Top 10. |
+
+**Quick Start (CORS):**
+```typescript
+const ALLOWED_ORIGINS = ['https://yourapp.com'];
+
+// Only allow specific origins
+if (origin && ALLOWED_ORIGINS.includes(origin)) {
+  headers['Access-Control-Allow-Origin'] = origin;
+}
+```
+
+**Quick Start (Validation):**
+```typescript
+import { z } from 'zod';
+
+const schema = z.object({
+  email: z.string().email().max(255),
+  password: z.string().min(8).max(128),
+});
+
+const result = schema.safeParse(body);
+if (!result.success) {
+  return Response.json({ error: result.error.issues }, { status: 400 });
+}
+```
+
+---
+
+## Usage Pattern
+
+Each snippet follows this format:
+
+```
+// =============================================================================
+// WHAT: Brief description
+// WHY: What attack/vulnerability this prevents
+// HOW: Integration instructions
+// =============================================================================
+
+[actual code with inline comments]
+```
+
+---
+
+## Related Resources
+
+- **[/configs](../configs/)** - Framework configs (Next.js headers, Supabase RLS, Firebase rules)
+- **[/ai-defense](../ai-defense/)** - AI/LLM security (prompt injection, cost protection)
+- **[/checklists](../checklists/)** - Security checklists (launch day)
+
+---
+
+## Contributing
+
+Have a security snippet that saved your app? Add it here!
+
+1. Create a new file in the appropriate subfolder
+2. Add extensive comments explaining:
+   - What attack this prevents
+   - How to integrate it
+   - Common gotchas
+3. Open a PR
+
+---
+
+## What's Next
+
+Future additions planned:
+- Webhook signature verification (Stripe, GitHub)
+- OAuth state parameter handling
+- CSRF protection patterns
+- Content Security Policy builder