praxis-sec 1.2.1 → 1.2.4

package/cli/commands/scan-mcp.js

@@ -188,31 +188,37 @@ const DANGEROUS_TOOL_NAMES = [
 // =============================================================================
 
 export async function scanMcpCommand(target, options = {}) {
+  const machineOutput = options.json || options.quiet;
   if (!target) {
+    if (options.quiet) throw new Error('An MCP manifest path or URL is required');
     output.error('Usage: praxis scan-mcp <url|path>');
     output.info('  Analyze an MCP server\'s tool manifest for security issues before connecting.');
     process.exit(1);
   }
 
-  console.log();
-  output.header('Praxis — MCP Server Security Analysis');
-  console.log();
+  if (!machineOutput) {
+    console.log();
+    output.header('Praxis — MCP Server Security Analysis');
+    console.log();
+  }
 
   let manifest, serverName, source;
 
   if (target.startsWith('http://') || target.startsWith('https://')) {
-    console.log(chalk.gray(`  Fetching MCP manifest from: ${target}`));
+    if (!machineOutput) console.log(chalk.gray(`  Fetching MCP manifest from: ${target}`));
     try {
       manifest = await fetchMcpManifest(target);
       serverName = new URL(target).hostname;
       source = target;
     } catch (err) {
+      if (options.quiet) throw err;
       output.error(`Failed to fetch MCP manifest: ${err.message}`);
       process.exit(1);
     }
   } else {
     const filePath = path.resolve(target);
     if (!fs.existsSync(filePath)) {
+      if (options.quiet) throw new Error(`File not found: ${filePath}`);
       output.error(`File not found: ${filePath}`);
       process.exit(1);
     }
@@ -221,26 +227,31 @@ export async function scanMcpCommand(target, options = {}) {
       serverName = path.basename(filePath);
       source = filePath;
     } catch (err) {
+      if (options.quiet) throw err;
       output.error(`Failed to parse manifest: ${err.message}`);
       process.exit(1);
     }
   }
 
   const tools = extractTools(manifest);
-  console.log(chalk.gray(`  Server: ${serverName}`));
-  console.log(chalk.gray(`  Tools found: ${tools.length}`));
-  console.log();
+  if (!machineOutput) {
+    console.log(chalk.gray(`  Server: ${serverName}`));
+    console.log(chalk.gray(`  Tools found: ${tools.length}`));
+    console.log();
+  }
 
   if (tools.length === 0) {
+    if (options.quiet) throw new Error('No tools found in MCP manifest');
     output.warning('No tools found in manifest. Is this a valid MCP tools response?');
     return;
   }
 
   const findings = analyzeManifest(manifest, tools, serverName, source);
+  const report = { server: serverName, source, toolCount: tools.length, findings, summary: getSummary(findings) };
 
   if (options.json) {
-    console.log(JSON.stringify({ server: serverName, source, toolCount: tools.length, findings, summary: getSummary(findings) }, null, 2));
-    return;
+    if (!options.quiet) console.log(JSON.stringify(report, null, 2));
+    return report;
   }
 
   printFindings(findings, serverName, tools.length);

package/cli/commands/scan-standard.js

@@ -16,6 +16,7 @@ import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
+import { displayPath } from '../core/paths.js';
 import { buildOrchestratorAsync } from '../agents/index.js';
 import { ScoringEngine } from '../agents/scoring-engine.js';
 import {
@@ -102,11 +103,7 @@ export async function scanStandardCommand(name, targetPath = '.', options = {})
     controls: standardSummary.controls,
     findings: filtered.map(f => ({
       ...f,
-      file: String(f.file || '')
-        .replace(/\\/g, '/')
-        .replace(/^[a-zA-Z]:\/+/, '')
-        .replace(/^.*\/Praxis\/showcase-target\//, 'showcase-target/')
-        .replace(/^.*\/Praxis\//, ''),
+      file: displayPath(f.file, absolutePath),
     })),
     score: scoreResult.score,
     grade: scoreResult.grade?.letter || 'A',
@@ -239,7 +236,7 @@ async function printHumanReport(standard, report) {  console.log(chalk.white.bol
     const sev = (f.severity || 'medium').toUpperCase();
     const color = SEV_COLORS[f.severity] || chalk.white;
     const tag = ids.join(', ');
-    const file = f.file ? path.relative(process.cwd(), f.file) : '';
+    const file = f.file ? displayPath(f.file, process.cwd()) : '';
     const loc = file ? `${file}:${f.line || 0}` : '';
     console.log(`  ${color(`[${sev}]`)} ${chalk.cyan(`[${tag}]`)} ${f.title || f.rule || ''}`);
     if (loc) console.log(chalk.gray(`    ${loc}`));

package/cli/commands/scan.js

@@ -35,10 +35,12 @@ import {
   MAX_FILE_SIZE,
   loadGitignorePatterns
 } from '../utils/patterns.js';
-import { isHighEntropyMatch, getConfidence } from '../utils/entropy.js';
+import { isHighEntropyMatch, getConfidence, isDocumentedSecretExample } from '../utils/entropy.js';
 import * as output from '../utils/output.js';
 import { CacheManager } from '../utils/cache-manager.js';
 import { isGitUrl, cloneGitRepo } from '../core/git-clone.js';
+import { displayPath } from '../core/paths.js';
+import { validateDir } from '../core/fs.js';
 
 // =============================================================================
 // CUSTOM PATTERNS (.praxis.json)
@@ -113,12 +115,12 @@ export async function scanCommand(targetPath = '.', options = {}) {
     }
   };
 
-  const absolutePath = path.resolve(effectivePath);
+  const absolutePath = validateDir(effectivePath, { exitOnMissing: false });
 
   // Validate path exists
-  if (!fs.existsSync(absolutePath)) {
+  if (!absolutePath) {
     cleanup();
-    output.error(`Path does not exist: ${absolutePath}`);
+    console.error('Secret scans require an existing directory.');
     process.exit(1);
   }
 
@@ -231,7 +233,7 @@ export async function scanCommand(targetPath = '.', options = {}) {
     if (options.sarif) {
       console.log(renderSARIF(allResults, absolutePath));
     } else if (options.json) {
-      outputJSON(allResults, files.length);
+      outputJSON(allResults, files.length, absolutePath);
     } else {
       outputPretty(allResults, files.length, absolutePath);
     }
@@ -376,6 +378,8 @@ async function scanFile(filePath, patterns = SECRET_PATTERNS) {
         let match;
         while ((match = pattern.pattern.exec(line)) !== null) {
           // For generic patterns, apply entropy check to filter placeholders
+          if (isDocumentedSecretExample(pattern.name, match[0])) continue;
+
           if (pattern.requiresEntropyCheck && !isHighEntropyMatch(match[0])) {
             continue;
           }
@@ -498,7 +502,7 @@ function outputPretty(results, filesScanned, rootPath) {
   output.summary(stats);
 }
 
-function outputJSON(results, filesScanned) {
+function outputJSON(results, filesScanned, rootPath) {
   const jsonOutput = {
     success: results.length === 0,
     filesScanned,
@@ -510,7 +514,11 @@ function outputJSON(results, filesScanned) {
     for (const f of findings) {
       jsonOutput.totalFindings++;
       jsonOutput.findings.push({
-        file,
+        // `results` is keyed by the raw absolute glob path, so this command never
+        // passes through the orchestrator's normalisation. Without it the JSON
+        // report published the absolute path, username and all — worse than the
+        // drive-letter stripping this replaced.
+        file: displayPath(file, rootPath),
         line: f.line,
         column: f.column,
         category: f.category || 'secret',

package/cli/commands/score.js

@@ -40,7 +40,7 @@ import {
   TEST_FILE_PATTERNS,
   MAX_FILE_SIZE
 } from '../utils/patterns.js';
-import { isHighEntropyMatch } from '../utils/entropy.js';
+import { isHighEntropyMatch, isDocumentedSecretExample } from '../utils/entropy.js';
 import { runDepsAudit } from './deps.js';
 import * as output from '../utils/output.js';
 
@@ -422,6 +422,7 @@ function scanFile(filePath) {
 
         let match;
         while ((match = pattern.pattern.exec(line)) !== null) {
+          if (isDocumentedSecretExample(pattern.name, match[0])) continue;
           if (pattern.requiresEntropyCheck && !isHighEntropyMatch(match[0])) {
             continue;
           }

package/cli/commands/vibe-check.js

@@ -18,6 +18,7 @@ import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
+import { displayPath } from '../core/paths.js';
 import { buildOrchestrator } from '../agents/index.js';
 import { ScoringEngine } from '../agents/scoring-engine.js';
 import { runDepsAudit } from './deps.js';
@@ -29,7 +30,7 @@ import {
   MAX_FILE_SIZE,
   loadGitignorePatterns
 } from '../utils/patterns.js';
-import { isHighEntropyMatch, getConfidence } from '../utils/entropy.js';
+import { isHighEntropyMatch, getConfidence, isDocumentedSecretExample } from '../utils/entropy.js';
 import fg from '../core/glob.js';
 
 // =============================================================================
@@ -134,6 +135,7 @@ export async function vibeCheckCommand(targetPath = '.', options = {}) {
           pattern.pattern.lastIndex = 0;
           let match;
           while ((match = pattern.pattern.exec(line)) !== null) {
+            if (isDocumentedSecretExample(pattern.name, match[0])) continue;
             if (pattern.requiresEntropyCheck && !isHighEntropyMatch(match[0])) continue;
             secretFindings.push({
               file, line: lineNum + 1, column: match.index + 1,
@@ -215,7 +217,7 @@ export async function vibeCheckCommand(targetPath = '.', options = {}) {
       })
       .slice(0, 3);
     for (const f of top) {
-      const rel = path.relative(absolutePath, f.file).replace(/\\/g, '/');
+      const rel = displayPath(f.file, absolutePath);
       console.log(`    ${SEV_EMOJI[f.severity] || '⚪'} ${f.title || f.rule} ${chalk.gray(`(${rel}:${f.line})`)}`);
     }
     console.log();

package/cli/commands/watch.js

@@ -13,9 +13,10 @@
 import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
+import { displayPath } from '../core/paths.js';
 import { execFileSync } from 'child_process';
 import { SKIP_DIRS, SKIP_EXTENSIONS, SKIP_FILENAMES, SECRET_PATTERNS, SECURITY_PATTERNS } from '../utils/patterns.js';
-import { isHighEntropyMatch, getConfidence } from '../utils/entropy.js';
+import { isHighEntropyMatch, getConfidence, isDocumentedSecretExample } from '../utils/entropy.js';
 import * as output from '../utils/output.js';
 import { ScoringEngine } from '../agents/scoring-engine.js';
 
@@ -174,6 +175,7 @@ function scanFile(filePath, patterns) {
         pattern.pattern.lastIndex = 0;
         let match;
         while ((match = pattern.pattern.exec(line)) !== null) {
+          if (isDocumentedSecretExample(pattern.name, match[0])) continue;
           if (pattern.requiresEntropyCheck && !isHighEntropyMatch(match[0])) continue;
           findings.push({
             line: i + 1,
@@ -358,7 +360,7 @@ async function watchStateful(absolutePath, options = {}) {
         const scoreColor = scoreResult.score >= 75 ? chalk.cyan : scoreResult.score >= 50 ? chalk.yellow : chalk.red;
         console.log(`  [${timestamp}] ${chalk.white(`${newFindings.length} new finding(s)`)}: Score ${scoreColor(`${scoreResult.score}/100`)}`);
         for (const f of newFindings.filter(f => f.severity === 'critical' || f.severity === 'high')) {
-          const relFile = path.relative(absolutePath, f.file || '');
+          const relFile = displayPath(f.file || '', absolutePath);
           const sev = f.severity === 'critical' ? chalk.red.bold('!!') : chalk.yellow(' !');
           console.log(`    ${sev} ${f.title} — ${relFile}:${f.line}`);
         }
@@ -375,7 +377,7 @@ async function watchStateful(absolutePath, options = {}) {
             provider: stats.provider,
             model: stats.model,
             findings: allFindings.map(f => ({
-              file: path.relative(absolutePath, f.file || ''),
+              file: displayPath(f.file || '', absolutePath),
               line: f.line,
               severity: f.severity,
               rule: f.rule,
@@ -498,7 +500,7 @@ async function watchDeep(absolutePath, options = {}) {
             ? { flagged: scoreResult.agenticSummary.flagged, total: scoreResult.agenticSummary.total }
             : null,
           findings: findings.map(f => ({
-            file: path.relative(absolutePath, f.file || ''),
+            file: displayPath(f.file || '', absolutePath),
             line: f.line,
             severity: f.severity,
             rule: f.rule,
@@ -519,7 +521,7 @@ async function watchDeep(absolutePath, options = {}) {
         console.log(`  [${timestamp}] ${chalk.white(`${findings.length} finding(s)`)}: ${criticals ? chalk.red.bold(`${criticals} critical`) : ''}${criticals && highs ? ', ' : ''}${highs ? chalk.yellow(`${highs} high`) : ''}. Score: ${scoreColor(`${scoreResult.score}/100 ${scoreResult.grade?.letter}`)}`);
 
         for (const f of findings.filter(f => f.severity === 'critical' || f.severity === 'high')) {
-          const relFile = path.relative(absolutePath, f.file || '');
+          const relFile = displayPath(f.file || '', absolutePath);
           const sev = f.severity === 'critical' ? chalk.red.bold('!!') : chalk.yellow(' !');
           const agentic = f.agenticRisk ? chalk.gray(` [${f.agenticRisk.id}]`) : '';
           console.log(`    ${sev} ${f.title} — ${relFile}:${f.line}${agentic}`);
@@ -671,7 +673,7 @@ async function postPRComments(findings, rootPath) {
   ).slice(0, 10); // Max 10 comments per scan
 
   for (const f of criticalOrHigh) {
-    const relFile = path.relative(rootPath, f.file).replace(/\\/g, '/');
+    const relFile = displayPath(f.file, rootPath);
     const body = [
       `**Praxis — ${f.severity.toUpperCase()} finding**`,
       '',

package/cli/core/glob.js

@@ -1,9 +1,10 @@
 /**
  * Scanner file discovery boundary. Target-controlled patterns are bounded before
- * fast-glob/braces parse them (GHSA-vfj7-8cjw-p6xm has no upstream patch yet).
+ * the glob parser sees them, including pathological ignore patterns.
  * Directory symlinks must not turn a project scan into a scan of the host.
  */
-import fastGlob from 'fast-glob';
+import { glob as discover, globSync } from 'tinyglobby';
+import { validateDir } from './fs.js';
 
 const MAX_PATTERNS = 4096;
 const MAX_LENGTH = 8192;
@@ -42,15 +43,16 @@ export function validateGlobPatterns(patterns) {
 }
 
 function safeOptions(patterns, options) {
+  if (options.cwd && !validateDir(options.cwd, { exitOnMissing: false })) throw new Error('Scan root must be an existing directory');
   validateGlobPatterns(patterns);
   if (options.ignore) validateGlobPatterns(options.ignore);
-  return { ...options, followSymbolicLinks: false };
+  return { ...options, expandDirectories: false, followSymbolicLinks: false };
 }
 
 function glob(patterns, options = {}) {
-  return fastGlob(patterns, safeOptions(patterns, options));
+  return discover(patterns, safeOptions(patterns, options));
 }
 
-glob.sync = (patterns, options = {}) => fastGlob.sync(patterns, safeOptions(patterns, options));
+glob.sync = (patterns, options = {}) => globSync(patterns, safeOptions(patterns, options));
 
 export default glob;

package/cli/core/output/json.js

@@ -1,48 +1,56 @@
-/**
- * JSON output formatter.
- *
- * Reports are emitted with `schemaVersion` so consumers can pin to a
- * version. Bump the version when the shape changes in a breaking way.
- *
- * Scanner hardening: secret-category findings never expose their raw
- * matched value — `matched` is redacted centrally so no consumer of the
- * JSON report can leak a credential.
- */
-
-const SCHEMA_VERSION = 3;
-
-function redactFinding(f) {
-  if (!f || typeof f !== 'object') return f;
-  const isSecret = f.category === 'secrets' || f.category === 'secret'
-    || /secret|api[_-]?key|token|password|credential/i.test(String(f.rule || ''));
-  const out = { ...f };
-  if (f.matched) {
-    out.matched = isSecret
-      ? `${String(f.matched).slice(0, 3)}***`
-      : String(f.matched).slice(0, 160);
-  }
-  if (out.file) {
-    out.file = String(out.file)
-      .replace(/\\/g, '/')
-      .replace(/^[a-zA-Z]:\/+/, '')
-      .replace(/^.*\/Praxis\/showcase-target\//, 'showcase-target/')
-      .replace(/^.*\/Praxis\//, '');
-  }
-  return out;
-}
-
-export default function json(report, options = {}) {
-  const { pretty = true } = options;
-  const enriched = {
-    schemaVersion: SCHEMA_VERSION,
-    ...report,
-  };
-  if (Array.isArray(enriched.findings)) {
-    enriched.findings = enriched.findings.map(redactFinding);
-  }
-  return pretty
-    ? JSON.stringify(enriched, null, 2)
-    : JSON.stringify(enriched);
-}
-
-export { redactFinding, SCHEMA_VERSION };
+/**
+ * JSON output formatter.
+ *
+ * Reports are emitted with `schemaVersion` so consumers can pin to a
+ * version. Bump the version when the shape changes in a breaking way.
+ *
+ * Scanner hardening: secret-category findings never expose their raw
+ * matched value — `matched` is redacted centrally so no consumer of the
+ * JSON report can leak a credential. Finding paths are normalised against the scan
+ * root by the orchestrator, so no consumer can receive an absolute path either.
+ */
+
+import path from 'path';
+
+const SCHEMA_VERSION = 3;
+
+function redactFinding(f) {
+  if (!f || typeof f !== 'object') return f;
+  const isSecret = f.category === 'secrets' || f.category === 'secret'
+    || /secret|api[_-]?key|token|password|credential/i.test(String(f.rule || ''));
+  const out = { ...f };
+  if (f.matched) {
+    out.matched = isSecret
+      ? `${String(f.matched).slice(0, 3)}***`
+      : String(f.matched).slice(0, 160);
+  }
+  if (out.file) {
+    // Paths arrive already normalised against the scan root by the orchestrator,
+    // so this only has to unify separators. The three strippers that used to live
+    // here were wrong for everyone but this repository:
+    //   `^[a-zA-Z]:\/+`  turned `C:\Users\alice\.cursor\mcp.json` into
+    //                   `Users/alice/.cursor/mcp.json` — leaking the username and
+    //                   naming a repo-relative file that does not exist;
+    //   the two `/Praxis/` rules were dogfooding hacks that silently truncated any
+    //                   real path merely containing a directory called `Praxis`.
+    // See cli/core/paths.js for the replacement.
+    out.file = String(out.file).split(path.sep).join('/').replace(/\\/g, '/');
+  }
+  return out;
+}
+
+export default function json(report, options = {}) {
+  const { pretty = true } = options;
+  const enriched = {
+    schemaVersion: SCHEMA_VERSION,
+    ...report,
+  };
+  if (Array.isArray(enriched.findings)) {
+    enriched.findings = enriched.findings.map(redactFinding);
+  }
+  return pretty
+    ? JSON.stringify(enriched, null, 2)
+    : JSON.stringify(enriched);
+}
+
+export { redactFinding, SCHEMA_VERSION };

package/cli/core/paths.js

@@ -0,0 +1,91 @@
+/**
+ * Honest, publishable paths for findings.
+ *
+ * A finding is not always about a file inside the scanned tree.
+ * `MCP_SHADOW_CONFIG` reports the developer's own `~/.cursor/mcp.json`, because a
+ * shadow MCP server configured outside version control is precisely the finding
+ * worth reporting. That file sits above the scan root, and neither obvious way of
+ * rendering it is acceptable:
+ *
+ *   path.relative(root, file)  ->  '../../../Users/alice/.cursor/mcp.json'
+ *                                  leaks the username and the directory depth into
+ *                                  a report that gets pasted into a CI comment.
+ *   strip the drive letter     ->  'Users/alice/.cursor/mcp.json'
+ *                                  does not exist, and falsely reads as
+ *                                  repo-relative, so the finding is unlocatable.
+ *
+ * The only honest rendering of a path above the root is `~/…`. It identifies the
+ * file, leaks neither the username nor the directory layout, and — unlike either
+ * alternative — is identical on every machine, so a self-scan's findings do not
+ * change identity when a colleague runs it.
+ *
+ * Applied once by the orchestrator, before findings reach any renderer, because
+ * the terminal table, the HTML and JSON reports, CI annotations and SARIF all read
+ * the same `finding.file`. `fix` and `remediate` build their own absolute paths and
+ * never read this field, so normalising it cannot redirect a write.
+ */
+
+import os from 'os';
+import path from 'path';
+
+const toSlash = (p) => String(p).split(path.sep).join('/').replace(/\\/g, '/');
+
+// `path.isAbsolute` is platform-specific: on POSIX it reports false for
+// `C:/work/src/a.js`, because that is a legal relative filename there. Findings
+// normally come from the host's own glob, but a path read back from a report or
+// a cache can carry the other platform's shape, and treating it as relative would
+// print a drive letter straight into the output. Same guard sarif.js uses.
+const isAbsoluteLike = (s) => path.isAbsolute(s) || /^[a-zA-Z]:[\\/]/.test(s) || /^\\\\/.test(s);
+
+/**
+ * Render a finding's file for display.
+ *
+ * @param {string} file  Absolute or already-relative path.
+ * @param {string} [root] Absolute scan root, when known.
+ * @returns {string} Root-relative when inside `root`, `~/…` when inside the home
+ *   directory, otherwise the bare filename — never an absolute path.
+ */
+export function displayPath(file, root) {
+  if (file === undefined || file === null || file === '') return file;
+
+  const s = String(file);
+  // Already display-shaped. Passing a relative path back through
+  // `path.relative(root, ...)` would resolve it against the cwd, escape the root
+  // and collapse it to a bare filename — the trap that made Code Scanning alerts
+  // unlocatable.
+  if (!isAbsoluteLike(s)) return toSlash(s);
+
+  if (root) {
+    const rel = path.relative(root, s);
+    // `rel` starting with '..' means the file is outside the scan root.
+    if (rel && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)) return toSlash(rel);
+  }
+
+  const home = os.homedir();
+  if (home && s !== home && s.startsWith(home + path.sep)) {
+    return '~/' + toSlash(s.slice(home.length + 1));
+  }
+
+  // Outside the root and outside home: identify the file without publishing the
+  // local directory layout.
+  return path.posix.basename(toSlash(s));
+}
+
+/**
+ * Apply {@link displayPath} to every finding that carries a path.
+ *
+ * The orchestrator calls this once, at the boundary where findings stop being
+ * internal state and become report output.
+ *
+ * @param {Array<object>} findings Mutated in place and returned.
+ * @param {string} [root] Absolute scan root.
+ */
+export function normalizeFindingPaths(findings, root) {
+  if (!Array.isArray(findings)) return findings;
+  for (const f of findings) {
+    if (f && typeof f === 'object' && f.file) f.file = displayPath(f.file, root);
+  }
+  return findings;
+}
+
+export default displayPath;

package/cli/core/web/jobs.js

@@ -172,6 +172,8 @@ export async function runScanWithOrchestrator(rootPath, onProgress) {
     },
   });
 
+  if (agentResults.some(agent => !agent.success)) throw new Error('Scan incomplete: one or more agents failed');
+
   let score = 100;
   let grade = 'A';
   let categories = {};

package/cli/data/documented-secret-examples.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "lastReviewed": "2026-10-07",
+  "description": "Exact provider-documented non-working credential identifiers. No substring, test-directory, or history-wide exemptions.",
+  "examples": [
+    {
+      "pattern": "AWS Access Key ID",
+      "aliases": ["AGENT_LOG_EXPOSED_AWS_KEY"],
+      "value": "AKIAIOSFODNN7EXAMPLE",
+      "source": "https://docs.aws.amazon.com/AmazonS3/latest/developerguide/RESTAuthentication.html",
+      "reason": "AWS explicitly labels this identifier a non-working example credential."
+    }
+  ]
+}

package/cli/utils/cache-manager.js

@@ -17,6 +17,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import { displayPath } from '../core/paths.js';
 import crypto from 'crypto';
 import { toolVersion } from '../core/version.js';
 
@@ -200,7 +201,7 @@ export class CacheManager {
       // Group findings by file (relative paths)
       const lastFindings = {};
       for (const f of allFindings) {
-        const relPath = path.relative(this.rootPath, f.file).replace(/\\/g, '/');
+        const relPath = displayPath(f.file, this.rootPath);
         if (!lastFindings[relPath]) lastFindings[relPath] = [];
         // Store a lightweight copy (no absolute paths)
         lastFindings[relPath].push({

package/cli/utils/entropy.js

@@ -19,6 +19,25 @@
  * Patterns with known prefixes (sk-ant-, ghp_, AKIA...) are already precise enough.
  */
 
+import fs from 'fs';
+
+const documentedExamples = new Map();
+try {
+  const catalog = JSON.parse(fs.readFileSync(new URL('../data/documented-secret-examples.json', import.meta.url), 'utf8'));
+  for (const entry of catalog.examples || []) {
+    if (typeof entry.pattern !== 'string' || typeof entry.value !== 'string') continue;
+    for (const name of [entry.pattern, ...(Array.isArray(entry.aliases) ? entry.aliases : [])]) {
+      if (typeof name !== 'string') continue;
+      if (!documentedExamples.has(name)) documentedExamples.set(name, new Set());
+      documentedExamples.get(name).add(entry.value);
+    }
+  }
+} catch { /* Missing example data must never suppress unknown credentials. */ }
+
+export function isDocumentedSecretExample(patternName, matched) {
+  return documentedExamples.get(patternName)?.has(extractSecretValue(matched)) === true;
+}
+
 // =============================================================================
 // ENTROPY CALCULATION
 // =============================================================================

package/cli/utils/hermes-tool-registry.js

@@ -62,7 +62,9 @@ export const HERMES_TOOLS = [
     },
     handler: async ({ path: scanPath, severity = 'medium', deep = false }) => {
       const { auditCommand } = await import('../commands/audit.js');
-      return auditCommand(scanPath, { severity, deep, json: true, quiet: true });
+      const report = await auditCommand(scanPath, { deep, _agenticInner: true, deps: false, noAi: true });
+      const ranks = { critical: 4, high: 3, medium: 2, low: 1 };
+      return { ...report, findings: report.findings.filter(f => (ranks[f.severity] ?? 0) >= (ranks[severity] ?? 0)) };
     },
   },
 
@@ -86,7 +88,7 @@ export const HERMES_TOOLS = [
     },
     handler: async ({ target }) => {
       const { scanMcpCommand } = await import('../commands/scan-mcp.js');
-      return scanMcpCommand(target, { json: true });
+      return scanMcpCommand(target, { json: true, quiet: true });
     },
   },
 
@@ -115,7 +117,7 @@ export const HERMES_TOOLS = [
     },
     handler: async ({ path: projectPath, severity = 'medium' }) => {
       const { mcpGetFindings } = await import('../commands/mcp.js');
-      return mcpGetFindings({ projectPath, severity });
+      return mcpGetFindings({ reportPath: path.join(projectPath, '.praxis', 'last-report.json'), severity });
     },
   },
 
@@ -123,7 +125,7 @@ export const HERMES_TOOLS = [
     name: 'praxis_suppress_finding',
     description:
       'Suppress a known-safe finding by inserting an inline praxis-ignore comment ' +
-      'in the source file before the flagged line. Use only when the finding is a ' +
+      'on the flagged source line. Use only when the finding is a ' +
       'confirmed false positive and you can document why it is safe.',
     parameters: {
       type: 'object',
@@ -184,11 +186,11 @@ export const HERMES_TOOLS = [
 // =============================================================================
 
 const KNOWN_HASHES = {
-  praxis_audit:             '4d282d29e44fcc01',
-  praxis_scan_mcp:          'f967aea9626ca840',
-  praxis_get_findings:      'c09c9447efd574b3',
-  praxis_suppress_finding:  '3b7339419fe52ac7',
-  praxis_memory_list:       'c71c996716d1805b',
+  praxis_audit:             '4bdb0dafe1efea27',
+  praxis_scan_mcp:          '99c278579ccc7e38',
+  praxis_get_findings:      '8c3b10c970f047ab',
+  praxis_suppress_finding:  '3cedaa6e7ae974ae',
+  praxis_memory_list:       '9d405b87e81c7263',
 };
 
 function toolHash(tool) {