praxis-sec 1.2.0 → 1.2.2

package/cli/utils/scan-fingerprint.js

@@ -2,7 +2,7 @@
  * Scan fingerprint — identify exactly what produced a set of findings.
  * ============================================================================
  *
- * Why this exists (P-IMP-053): during self-dogfooding a scan reported 325 findings
+ * Why this exists: during self-dogfooding a scan reported 325 findings
  * where four subsequent scans of the identical tree reported 308. The extra 17 were
  * `PROBE_*` / `VIBE_*` rules in files nobody had touched. Data drift, test fixtures
  * and the scan cache were each ruled out, so the cause stayed unknown.

package/cli/utils/score-history.js

@@ -1,119 +1,119 @@
-/**
- * Score history — read the scan-over-time series behind the trend section.
- * ============================================================================
- *
- * `.praxis/history.json` is appended once per scan with `{timestamp, score, grade,
- * totalFindings, totalDepVulns, categoryScores}`.
- *
- * The discipline here is about *not overstating* the data (P-IMP-055):
- *   - with no prior scans the project is at its **baseline** — the report must say so
- *     rather than draw an empty graph, which reads as "flat, no change"
- *   - a two-point series is **two measurements, not a trend**, and is labelled as such
- *   - the sample size and the time span are always shown next to the chart, so nobody
- *     reads three scans over four minutes as a security trajectory
- *
- * Best-effort and never throws: a corrupt history must not break a report, and it must
- * never be silently replaced with fabricated points.
- */
-
-import fs from 'fs';
-import path from 'path';
-
-const HISTORY_FILE = path.join('.praxis', 'history.json');
-
-/**
- * Reads the score history for a project.
- * @returns {{points: object[], unreadable: number, error: string|null}}
- */
-export function readScoreHistory(rootPath = process.cwd()) {
-  const root = typeof rootPath === 'string' && rootPath.length > 0 ? rootPath : process.cwd();
-  let raw;
-  try {
-    raw = fs.readFileSync(path.join(root, HISTORY_FILE), 'utf8');
-  } catch (err) {
-    return { points: [], unreadable: 0, error: err.code === 'ENOENT' ? null : err.message };
-  }
-
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    return { points: [], unreadable: 0, error: `history.json is not valid JSON: ${err.message}` };
-  }
-
-  if (!Array.isArray(parsed)) {
-    return { points: [], unreadable: 0, error: 'history.json is not an array of scan entries' };
-  }
-
-  const points = [];
-  let unreadable = 0;
-  for (const entry of parsed) {
-    if (entry && typeof entry === 'object' && typeof entry.score === 'number') {
-      points.push({
-        timestamp: entry.timestamp || null,
-        score: entry.score,
-        grade: entry.grade ?? null,
-        totalFindings: typeof entry.totalFindings === 'number' ? entry.totalFindings : null,
-      });
-    } else {
-      unreadable++;
-    }
-  }
-
-  // Oldest → newest, so callers can treat the tail as "latest".
-  points.sort((a, b) => String(a.timestamp ?? '').localeCompare(String(b.timestamp ?? '')));
-  return { points, unreadable, error: null };
-}
-
-/**
- * Summarises a series for display, and states plainly how much data there is.
- *
- * @param {object[]} points   History points, oldest first (from readScoreHistory).
- * @param {object}   [current] `{score, grade}` for the scan being reported, so the
- *                             live score appears on the chart even before it is
- *                             appended to history.
- */
-export function summarizeHistory(points = [], current = null) {
-  // Coerce first: spreading null/undefined throws, which would break the
-  // "never throws" contract this module advertises.
-  const series = Array.isArray(points) ? [...points] : [];
-
-  // Append the in-flight scan if history doesn't already end with it. Without this the
-  // chart would show the *previous* score as the latest point and quietly mislead.
-  const last = series[series.length - 1];
-  const currentAlreadyPresent =
-    current && typeof current.score === 'number' && last && last.score === current.score;
-  if (current && typeof current.score === 'number' && !currentAlreadyPresent) {
-    series.push({ timestamp: null, score: current.score, grade: current.grade ?? null, totalFindings: null, isCurrent: true });
-  }
-
-  const scores = series.map(p => p.score);
-  const latest = scores[scores.length - 1] ?? null;
-  const previous = scores.length >= 2 ? scores[scores.length - 2] : null;
-
-  // How many *measurements* exist, and how many are prior runs (excluding the live one).
-  const measurementCount = scores.length;
-  const priorCount = Math.max(0, measurementCount - (current && !currentAlreadyPresent ? 1 : 0));
-
-  let spanDays = null;
-  const dated = series.filter(p => p.timestamp);
-  if (dated.length >= 2) {
-    const t0 = Date.parse(dated[0].timestamp);
-    const tN = Date.parse(dated[dated.length - 1].timestamp);
-    if (Number.isFinite(t0) && Number.isFinite(tN)) spanDays = Math.round(((tN - t0) / 86400000) * 10) / 10;
-  }
-
-  return {
-    series,
-    measurementCount,
-    priorCount,
-    latest,
-    previous,
-    delta: latest !== null && previous !== null ? Math.round((latest - previous) * 10) / 10 : null,
-    best: scores.length ? Math.max(...scores) : null,
-    worst: scores.length ? Math.min(...scores) : null,
-    isBaseline: measurementCount <= 1 && !current,
-    needsMoreData: measurementCount >= 1 && measurementCount < 3,
-    spanDays,
-  };
+/**
+ * Score history — read the scan-over-time series behind the trend section.
+ * ============================================================================
+ *
+ * `.praxis/history.json` is appended once per scan with `{timestamp, score, grade,
+ * totalFindings, totalDepVulns, categoryScores}`.
+ *
+ * The discipline here is about *not overstating* the data:
+ *   - with no prior scans the project is at its **baseline** — the report must say so
+ *     rather than draw an empty graph, which reads as "flat, no change"
+ *   - a two-point series is **two measurements, not a trend**, and is labelled as such
+ *   - the sample size and the time span are always shown next to the chart, so nobody
+ *     reads three scans over four minutes as a security trajectory
+ *
+ * Best-effort and never throws: a corrupt history must not break a report, and it must
+ * never be silently replaced with fabricated points.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const HISTORY_FILE = path.join('.praxis', 'history.json');
+
+/**
+ * Reads the score history for a project.
+ * @returns {{points: object[], unreadable: number, error: string|null}}
+ */
+export function readScoreHistory(rootPath = process.cwd()) {
+  const root = typeof rootPath === 'string' && rootPath.length > 0 ? rootPath : process.cwd();
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(root, HISTORY_FILE), 'utf8');
+  } catch (err) {
+    return { points: [], unreadable: 0, error: err.code === 'ENOENT' ? null : err.message };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { points: [], unreadable: 0, error: `history.json is not valid JSON: ${err.message}` };
+  }
+
+  if (!Array.isArray(parsed)) {
+    return { points: [], unreadable: 0, error: 'history.json is not an array of scan entries' };
+  }
+
+  const points = [];
+  let unreadable = 0;
+  for (const entry of parsed) {
+    if (entry && typeof entry === 'object' && typeof entry.score === 'number') {
+      points.push({
+        timestamp: entry.timestamp || null,
+        score: entry.score,
+        grade: entry.grade ?? null,
+        totalFindings: typeof entry.totalFindings === 'number' ? entry.totalFindings : null,
+      });
+    } else {
+      unreadable++;
+    }
+  }
+
+  // Oldest → newest, so callers can treat the tail as "latest".
+  points.sort((a, b) => String(a.timestamp ?? '').localeCompare(String(b.timestamp ?? '')));
+  return { points, unreadable, error: null };
+}
+
+/**
+ * Summarises a series for display, and states plainly how much data there is.
+ *
+ * @param {object[]} points   History points, oldest first (from readScoreHistory).
+ * @param {object}   [current] `{score, grade}` for the scan being reported, so the
+ *                             live score appears on the chart even before it is
+ *                             appended to history.
+ */
+export function summarizeHistory(points = [], current = null) {
+  // Coerce first: spreading null/undefined throws, which would break the
+  // "never throws" contract this module advertises.
+  const series = Array.isArray(points) ? [...points] : [];
+
+  // Append the in-flight scan if history doesn't already end with it. Without this the
+  // chart would show the *previous* score as the latest point and quietly mislead.
+  const last = series[series.length - 1];
+  const currentAlreadyPresent =
+    current && typeof current.score === 'number' && last && last.score === current.score;
+  if (current && typeof current.score === 'number' && !currentAlreadyPresent) {
+    series.push({ timestamp: null, score: current.score, grade: current.grade ?? null, totalFindings: null, isCurrent: true });
+  }
+
+  const scores = series.map(p => p.score);
+  const latest = scores[scores.length - 1] ?? null;
+  const previous = scores.length >= 2 ? scores[scores.length - 2] : null;
+
+  // How many *measurements* exist, and how many are prior runs (excluding the live one).
+  const measurementCount = scores.length;
+  const priorCount = Math.max(0, measurementCount - (current && !currentAlreadyPresent ? 1 : 0));
+
+  let spanDays = null;
+  const dated = series.filter(p => p.timestamp);
+  if (dated.length >= 2) {
+    const t0 = Date.parse(dated[0].timestamp);
+    const tN = Date.parse(dated[dated.length - 1].timestamp);
+    if (Number.isFinite(t0) && Number.isFinite(tN)) spanDays = Math.round(((tN - t0) / 86400000) * 10) / 10;
+  }
+
+  return {
+    series,
+    measurementCount,
+    priorCount,
+    latest,
+    previous,
+    delta: latest !== null && previous !== null ? Math.round((latest - previous) * 10) / 10 : null,
+    best: scores.length ? Math.max(...scores) : null,
+    worst: scores.length ? Math.min(...scores) : null,
+    isBaseline: measurementCount <= 1 && !current,
+    needsMoreData: measurementCount >= 1 && measurementCount < 3,
+    spanDays,
+  };
 }

package/docs/USAGE.md

@@ -896,8 +896,8 @@ praxis project policy init
 
 ### `.praxis/agents/*.js`
 
-Custom agent plugins, auto-discovered when running scans from a project
-that contains them. Scaffold one with:
+Custom agent plugins, loaded only when a local scan uses `--trust-plugins`.
+Scaffold one with:
 
 ```bash
 praxis project plugins new my-rule
@@ -906,7 +906,7 @@ praxis project plugins new my-rule
 A plugin is any module exporting a class extending `BaseAgent`:
 
 ```js
-import { BaseAgent, createFinding } from 'praxis';
+import { BaseAgent, createFinding } from 'praxis-sec';
 
 export default class MyAgent extends BaseAgent {
   constructor() { super('MyAgent', 'description', 'category'); }
@@ -961,7 +961,7 @@ only ever emits a known class name.
 prints a provenance line in its footer:
 
 ```
-praxis 1.0.0 · node v24.14.1 · probes v1.1(23) · threatpack v1.1(3) · eaa v0.1.0 · files 197
+praxis 1.2.2 · node v24.14.1 · probes v1.1(23) · threatpack v1.1(3) · eaa v0.1.0 · files 215
 ```
 
 It records the tool version, the runtime, and the version of every vendored data asset
@@ -1095,14 +1095,21 @@ praxis fix undo --all
 
 ## Custom plugins
 
-Praxis discovers plugins from `.praxis/agents/` automatically when scans run
-from that project root. The discovery uses `buildOrchestratorAsync(rootPath)` —
-the synchronous `buildOrchestrator()` skips plugin loading.
+Praxis loads plugins from `.praxis/agents/` only with explicit trust:
+
+```bash
+praxis scan full . --trust-plugins
+```
+
+Plugins execute arbitrary JavaScript with your permissions. Remote repository and
+web scans do not execute target plugins. Programmatic callers opt in with
+`buildOrchestratorAsync(rootPath, { trustPlugins: true })`; the synchronous
+`buildOrchestrator()` uses only built-in agents.
 
 A plugin extends `BaseAgent` and follows the standard contract:
 
 ```js
-import { BaseAgent, createFinding } from 'praxis';
+import { BaseAgent, createFinding } from 'praxis-sec';
 
 export default class HardcodedAdminCheck extends BaseAgent {
   constructor() {
@@ -1151,7 +1158,7 @@ plugin-side wiring required.
 | --- | --- |
 | `praxis intel update` is slow | NVD rate-limits to 6s/request without a key. Set `NVD_API_KEY`. |
 | `praxis scan ci --strict-intel` fails locally | Run `praxis intel update` first. Default freshness window is `7d`. |
-| Custom plugins not loading | Make sure you're running through `buildOrchestratorAsync(rootPath)` — the default `praxis scan` does this; programmatic API callers using `buildOrchestrator()` won't get plugins. |
+| Custom plugins not loading | Use `praxis scan full . --trust-plugins` for a trusted local project, or `buildOrchestratorAsync(rootPath, { trustPlugins: true })`. Remote and web scans use built-in agents only. |
 | `node cli/bin/praxis.js` works but `praxis` doesn't | Run `npm link` once (or `npm install -g .` from the repo). |
 | Test files report secrets | Confidence is auto-downgraded in test/doc/example paths — but use `praxis-ignore` for explicit suppression. |
 | Feed lives somewhere else | Override `HOME` (Unix) or `USERPROFILE` (Windows) — used by the test suite. |

package/docs/design/WEB-UI.md

@@ -1,7 +1,6 @@
 # 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`.
+> **Status:** implemented — read-only scan orchestration, served locally by the CLI.
 >
 > 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
@@ -21,9 +20,9 @@ A local web app for driving scans and managing scan projects:
 - 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`.
+detection. All UI is **vanilla JS served from the CLI**, with no bundler, no
+framework, and no network fetch of assets. Reports use the shared
+`cli/core/output/html-theme.js`.
 
 ## 2. Threat model — the part that matters
 

package/package.json

@@ -1,71 +1,81 @@
-{
-  "name": "praxis-sec",
-  "version": "1.2.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 cli/__tests__/git-remote.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"
-  }
-}
+{
+  "name": "praxis-sec",
+  "version": "1.2.2",
+  "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 cli/__tests__/git-remote.test.js cli/__tests__/release-reliability.test.js",
+    "test:determinism": "node scripts/check-determinism.mjs .",
+    "lint": "eslint cli/",
+    "praxis": "node cli/bin/praxis.js",
+    "prepublishOnly": "npm test && npm run lint && npm run test:determinism"
+  },
+  "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/",
+    "assets/",
+    "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": "^5.0.1"
+  },
+  "devDependencies": {
+    "eslint": "^9.18.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ganron007/Praxis.git"
+  },
+  "homepage": "https://github.com/Ganron007/Praxis#readme",
+  "bugs": {
+    "url": "https://github.com/Ganron007/Praxis/issues"
+  }
+}