praxis-sec 1.2.2 → 1.2.4

package/cli/commands/autofix.js

@@ -29,6 +29,9 @@ import path from 'path';
 import { execFileSync, execSync } from 'child_process';
 import chalk from 'chalk';
 import * as output from '../utils/output.js';
+import { resolveProjectFile } from '../core/fs.js';
+import { isProtectedFixPath } from '../core/fix-plan.js';
+import writeFileAtomic from 'write-file-atomic';
 
 // Severity rank for filtering
 const SEV_RANK = { critical: 4, high: 3, medium: 2, low: 1 };
@@ -86,7 +89,11 @@ export async function autofixCommand(options = {}) {
     if (!f.deepAnalysis?.fix) return false;
     if ((SEV_RANK[f.severity] ?? 0) < minRank) return false;
     if (!f.file) return false;
-    const absFile = path.resolve(rootPath, f.file);
+    let absFile;
+    try {
+      absFile = resolveProjectFile(rootPath, f.file);
+      if (isProtectedFixPath(path.relative(fs.realpathSync(rootPath), absFile)) || /^~[\\/]/.test(f.file)) return false;
+    } catch { return false; }
     if (NEVER_EDIT.some(p => p.test(absFile.replace(/\\/g, '/')))) return false;
     if (!fs.existsSync(absFile)) return false;
     return true;
@@ -160,11 +167,14 @@ export async function autofixCommand(options = {}) {
   const failed  = [];
 
   for (const f of fixable) {
-    const absFile = path.resolve(rootPath, f.file);
     const fix     = f.deepAnalysis.fix;
 
     try {
-      applyInlineAnnotation(absFile, f.line, fix);
+      const absFile = resolveProjectFile(rootPath, f.file);
+      if (!applyInlineAnnotation(absFile, f.line, fix)) {
+        console.log(chalk.gray(`  Already annotated: ${f.file}:${f.line ?? ''}`));
+        continue;
+      }
       applied.push(f);
       console.log(chalk.green(`  ✔ Annotated: ${f.file}:${f.line ?? ''}`));
     } catch (err) {
@@ -269,16 +279,20 @@ export async function autofixCommand(options = {}) {
  * Returns the count of files successfully annotated.
  * Exported for use by the --agentic audit loop.
  */
-export function applyInlineAnnotations(findings) {
-  const NEVER_EDIT = new Set(['.env', '.env.local', '.env.production', 'secrets.json', '.npmrc', '.netrc']);
-  const fixable = findings.filter(f =>
-    f.fix && f.file && fs.existsSync(f.file) && !NEVER_EDIT.has(path.basename(f.file))
-  );
+export function applyInlineAnnotations(findings, rootPath = process.cwd()) {
+  const neverEdit = new Set(['secrets.json', '.npmrc', '.netrc']);
   let count = 0;
-  for (const f of fixable.slice(0, 10)) {
+  // Insert from the bottom of each file so earlier insertions do not shift
+  // the original line numbers of later findings.
+  const ordered = [...findings].sort((a, b) => String(a.file).localeCompare(String(b.file)) || (b.line || 1) - (a.line || 1));
+  for (const f of ordered) {
+    if (count >= 10) break;
     try {
-      applyInlineAnnotation(f.file, f.line, f.fix);
-      count++;
+      if (!f.fix || !f.file || /^(?:~[\\/])/.test(f.file)) continue;
+      const absFile = resolveProjectFile(rootPath, f.file);
+      const relative = path.relative(fs.realpathSync(rootPath), absFile);
+      if (isProtectedFixPath(relative) || neverEdit.has(path.basename(absFile)) || !fs.statSync(absFile).isFile()) continue;
+      if (applyInlineAnnotation(absFile, f.line, f.fix)) count++;
     } catch { /* skip unwritable */ }
   }
   return count;
@@ -294,11 +308,15 @@ export function applyInlineAnnotation(filePath, lineNum, fix) {
   }
 
   // Already annotated?
-  if (idx > 0 && /praxis-fix/i.test(lines[idx - 1])) return;
+  if (/^\s*(?:\/\/|#)\s*praxis-fix\b/i.test(lines[idx])) return false;
+  for (let previous = idx - 1; previous >= 0 && /^\s*(?:\/\/|#)/.test(lines[previous]); previous--) {
+    if (/praxis-fix/i.test(lines[previous])) return false;
+  }
 
   const indent = lines[idx].match(/^(\s*)/)?.[1] ?? '';
   const isJs   = /\.(js|ts|jsx|tsx|mjs|cjs|java|c|cpp|cs|go|rs|swift|kt)$/.test(filePath);
   const isPy   = /\.py$/.test(filePath);
+  if (!isJs && !isPy) throw new Error('Inline annotations require a supported source-code comment syntax');
 
   // Wrap fix in a structured annotation comment
   const fixLines = fix.split('\n').map(l => l.trim()).filter(Boolean);
@@ -317,7 +335,8 @@ export function applyInlineAnnotation(filePath, lineNum, fix) {
   }
 
   lines.splice(idx, 0, annotation);
-  fs.writeFileSync(filePath, lines.join('\n'), 'utf-8');
+  writeFileAtomic.sync(filePath, lines.join('\n'), { encoding: 'utf8' });
+  return true;
 }
 
 function buildPRBody(applied, failed, reportPath) {

package/cli/commands/baseline.js

@@ -19,7 +19,7 @@ import ora from 'ora';
 import { displayPath } from '../core/paths.js';
 import { buildOrchestrator } from '../agents/index.js';
 import { SECRET_PATTERNS, SKIP_DIRS, SKIP_EXTENSIONS, SKIP_FILENAMES, MAX_FILE_SIZE } from '../utils/patterns.js';
-import { isHighEntropyMatch } from '../utils/entropy.js';
+import { isHighEntropyMatch, isDocumentedSecretExample } from '../utils/entropy.js';
 import fg from '../core/glob.js';
 
 const BASELINE_FILE = '.praxis/baseline.json';
@@ -61,6 +61,7 @@ async function quickScan(rootPath) {
           p.pattern.lastIndex = 0;
           let m;
           while ((m = p.pattern.exec(lines[i])) !== null) {
+            if (isDocumentedSecretExample(p.name, m[0])) continue;
             if (p.requiresEntropyCheck && !isHighEntropyMatch(m[0])) continue;
             findings.push({ file, line: i + 1, rule: p.name, matched: m[0], severity: p.severity });
           }

package/cli/commands/benchmark.js

@@ -32,7 +32,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 * as output from '../utils/output.js';
 import fg from '../core/glob.js';
 
@@ -150,6 +150,7 @@ export async function benchmarkCommand(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,

package/cli/commands/ci.js

@@ -21,6 +21,7 @@ import fs from 'fs';
 import path from 'path';
 import { displayPath } from '../core/paths.js';
 import { renderFindingsSARIF } from '../core/output/sarif.js';
+import { validateDir } from '../core/fs.js';
 import { execFileSync } from 'child_process';
 import { buildOrchestrator } from '../agents/index.js';
 import { ScoringEngine } from '../agents/scoring-engine.js';
@@ -35,7 +36,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 { ThreatIntel } from '../utils/threat-intel.js';
 import * as intelOrchestrator from '../utils/intel/index.js';
 import fg from '../core/glob.js';
@@ -45,7 +46,7 @@ import fg from '../core/glob.js';
 // =============================================================================
 
 export async function ciCommand(targetPath = '.', options = {}) {
-  const absolutePath = path.resolve(targetPath);
+  const absolutePath = validateDir(targetPath, { exitOnMissing: false });
   const threshold = options.threshold ?? 75;
   const failOn = options.failOn || null;
   const alwaysFailOn = options.alwaysFailOn || null;
@@ -57,8 +58,8 @@ export async function ciCommand(targetPath = '.', options = {}) {
     process.exit(2);
   }
 
-  if (!fs.existsSync(absolutePath)) {
-    console.error(`[praxis] Path does not exist: ${absolutePath}`);
+  if (!absolutePath) {
+    console.error('[praxis] CI scans require an existing directory.');
     process.exit(1);
   }
 
@@ -88,6 +89,8 @@ export async function ciCommand(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,

package/cli/commands/env-audit.js

@@ -27,6 +27,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { execFileSync } from 'child_process';
 import { SECRET_PATTERNS, SKIP_DIRS } from '../utils/patterns.js';
+import { isDocumentedSecretExample } from '../utils/entropy.js';
 
 // Minimum value length to cross-reference (skip short values like "true", "3000")
 const MIN_VALUE_LENGTH = 8;
@@ -138,8 +139,9 @@ export async function envAuditCommand(targetPath = '.', options) {
           const content = fs.readFileSync(pFile, 'utf-8');
           for (const pattern of SECRET_PATTERNS) {
             pattern.pattern.lastIndex = 0;
-            const match = pattern.pattern.exec(content);
-            if (match) {
+            let match;
+            while ((match = pattern.pattern.exec(content)) !== null) {
+              if (isDocumentedSecretExample(pattern.name, match[0])) continue;
               const relPath = path.relative(absolutePath, pFile).replace(/\\/g, '/');
               findings.push({
                 type: 'projects-manifest',

package/cli/commands/fix.js

@@ -22,7 +22,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 fg from '../core/glob.js';
 import * as output from '../utils/output.js';
 
@@ -111,6 +111,7 @@ async function scanFile(filePath) {
         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: lineNum + 1,

package/cli/commands/mcp.js

@@ -34,10 +34,12 @@
 
 import fs from 'fs';
 import path from 'path';
+import writeFileAtomic from 'write-file-atomic';
 import { displayPath } from '../core/paths.js';
+import { validateDir } from '../core/fs.js';
 import fg from '../core/glob.js';
 import { SECRET_PATTERNS, SKIP_DIRS, SKIP_EXTENSIONS, SKIP_FILENAMES, TEST_FILE_PATTERNS, MAX_FILE_SIZE } from '../utils/patterns.js';
-import { isHighEntropyMatch } from '../utils/entropy.js';
+import { isHighEntropyMatch, isDocumentedSecretExample } from '../utils/entropy.js';
 import { buildOrchestrator } from '../agents/index.js';
 import { ScoringEngine } from '../agents/scoring-engine.js';
 import { autoDetectProvider } from '../providers/llm-provider.js';
@@ -91,7 +93,7 @@ const TOOLS = [
   },
   {
     name: 'scan_repo',
-    description: 'Run a full multi-agent security scan on a repository or directory. Runs all 20+ praxis security agents (injection, auth bypass, secrets, supply chain, LLM security, etc.) and returns a structured findings report with severity ratings and remediation advice. Use this when the user asks to audit, scan, or check the security of their project.',
+    description: 'Run a full multi-agent security scan on a repository or directory. Runs the 28 built-in Praxis security agents (injection, auth bypass, secrets, supply chain, LLM security, etc.) and returns a structured findings report with severity ratings and remediation advice. Use this when the user asks to audit, scan, or check the security of their project.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -118,7 +120,7 @@ const TOOLS = [
   },
   {
     name: 'get_findings',
-    description: 'Read and return findings from a praxis JSON report file previously saved by scan_repo or the praxis CLI (npx praxis-sec audit --json). Useful for reviewing or referencing a prior scan without re-running it.',
+    description: 'Read and return findings from a praxis JSON report file previously saved by scan_repo or the praxis CLI (praxis scan full --json). Useful for reviewing or referencing a prior scan without re-running it.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -253,11 +255,10 @@ async function analyzeFile({ path: filePath }) {
   };
 }
 
-async function scanRepo({ path: targetPath, agents: agentFilter, llm = false, outputFile }) {
-  const rootPath = path.resolve(targetPath);
-
-  if (!fs.existsSync(rootPath)) {
-    return { error: `Path does not exist: ${rootPath}` };
+export async function mcpScanRepo({ path: targetPath, agents: agentFilter, llm = false, outputFile }, orchestrator = buildOrchestrator()) {
+  const rootPath = validateDir(targetPath, { exitOnMissing: false });
+  if (!rootPath) {
+    return { error: 'Repository scans require an existing directory', scanComplete: false };
   }
 
   // MCP communicates over stdout as JSON-RPC. Suppress all console output during
@@ -270,16 +271,15 @@ async function scanRepo({ path: targetPath, agents: agentFilter, llm = false, ou
   console.log = console.warn = console.error = console.info = noop;
 
   try {
-    const orchestrator = buildOrchestrator();
-    const context = { rootPath };
-
     // Run all agents (quiet:true suppresses ora spinners; console is already nulled)
-    const { findings, recon } = await orchestrator.runAll(rootPath, {
+    const { findings, recon, agentResults } = await orchestrator.runAll(rootPath, {
       agents: agentFilter,
       timeout: 30000,
       concurrency: 6,
       quiet: true,
     });
+    const scanErrors = (agentResults ?? []).filter(result => result.success === false)
+      .map(result => ({ stage: 'agent', agent: result.agent, message: result.error || 'Agent failed' }));
 
     // Optional: LLM deep analysis
     let deepStats = null;
@@ -289,12 +289,16 @@ async function scanRepo({ path: targetPath, agents: agentFilter, llm = false, ou
         const analyzer = new DeepAnalyzer({ provider, budgetCents: 50, verbose: false });
         await analyzer.analyze(findings, { rootPath, recon });
         deepStats = analyzer.getStats();
+      } else {
+        scanErrors.push({ stage: 'deep-analysis', message: 'Requested LLM analysis has no configured provider' });
       }
     }
 
     // Score
     const scorer = new ScoringEngine();
-    const { score, grade } = scorer.score(findings);
+    const scoreResult = scorer.compute(findings);
+    const score = scoreResult.score;
+    const grade = scoreResult.grade.letter;
 
     const SEV_ORDER = ['critical', 'high', 'medium', 'low'];
     const bySeverity = {};
@@ -305,6 +309,9 @@ async function scanRepo({ path: targetPath, agents: agentFilter, llm = false, ou
     const report = {
       scannedAt: new Date().toISOString(),
       rootPath,
+      scanComplete: scanErrors.length === 0,
+      scanErrors,
+      dependencyAudit: 'skipped',
       score,
       grade,
       totalFindings: findings.length,
@@ -322,7 +329,7 @@ async function scanRepo({ path: targetPath, agents: agentFilter, llm = false, ou
         ...(f.deepAnalysis ? { deepAnalysis: f.deepAnalysis } : {}),
       })),
       ...(deepStats ? { deepAnalysis: deepStats } : {}),
-      summary: `Score: ${score}/100 (${grade}) — ${findings.length} finding(s): ${bySeverity.critical} critical, ${bySeverity.high} high, ${bySeverity.medium} medium, ${bySeverity.low} low.`,
+      summary: `${scanErrors.length ? 'Incomplete scan. ' : ''}Score: ${score}/100 (${grade}) — ${findings.length} finding(s): ${bySeverity.critical} critical, ${bySeverity.high} high, ${bySeverity.medium} medium, ${bySeverity.low} low.`,
     };
 
     if (outputFile) {
@@ -333,7 +340,7 @@ async function scanRepo({ path: targetPath, agents: agentFilter, llm = false, ou
 
     return report;
   } catch (err) {
-    return { error: `Scan failed: ${err.message}` };
+    return { error: `Scan failed: ${err.message}`, scanComplete: false, scanErrors: [{ stage: 'scan', message: err.message }] };
   } finally {
     // Always restore console so other tool calls are not affected
     console.log   = savedLog;
@@ -343,7 +350,7 @@ async function scanRepo({ path: targetPath, agents: agentFilter, llm = false, ou
   }
 }
 
-function getFindings({ reportPath, severity }) {
+export function mcpGetFindings({ reportPath, severity }) {
   const absPath = path.resolve(reportPath);
 
   if (!fs.existsSync(absPath)) {
@@ -368,6 +375,9 @@ function getFindings({ reportPath, severity }) {
     scannedAt:     report.scannedAt,
     score:         report.score,
     grade:         report.grade,
+    scanComplete:  report.scanComplete,
+    scanErrors:    report.scanErrors,
+    dependencyAudit: report.dependencyAudit,
     totalFindings: filtered.length,
     bySeverity:    report.bySeverity,
     findings:      filtered,
@@ -376,7 +386,7 @@ function getFindings({ reportPath, severity }) {
   };
 }
 
-function suppressFinding({ file, line, reason }) {
+export function mcpSuppressFinding({ file, line, reason }) {
   const absPath = path.resolve(file);
 
   if (!fs.existsSync(absPath)) {
@@ -393,7 +403,7 @@ function suppressFinding({ file, line, reason }) {
   const lines = content.split('\n');
   const lineIdx = line - 1; // Convert to 0-indexed
 
-  if (lineIdx < 0 || lineIdx >= lines.length) {
+  if (!Number.isInteger(line) || lineIdx < 0 || lineIdx >= lines.length) {
     return { error: `Line ${line} is out of range (file has ${lines.length} lines)` };
   }
 
@@ -411,7 +421,23 @@ function suppressFinding({ file, line, reason }) {
     return { error: `Cannot suppress critical severity finding: ${criticalFinding.description}` };
   }
 
-  // Log suppression request to .praxis/suppressions.json for manual audit
+  const isSlashComment = /\.(js|ts|jsx|tsx|mjs|cjs|java|c|cpp|cs|go|rs|swift|kt)$/i.test(file);
+  const isHashComment = /\.(py|rb|sh|bash|yaml|yml|toml)$/i.test(file);
+  if (!isSlashComment && !isHashComment) {
+    return { error: 'Suppression requires a supported source-code comment syntax' };
+  }
+  const safeReason = String(reason ?? '').replace(/[\r\n\u2028\u2029]/g, ' ').trim();
+  if (!safeReason) return { error: 'A suppression reason is required' };
+  const ignoreComment = `${isHashComment ? '#' : '//'} praxis-ignore — ${safeReason}`;
+  const cr = targetLine.endsWith('\r') ? '\r' : '';
+  lines[lineIdx] = `${targetLine.replace(/\r$/, '')} ${ignoreComment}${cr}`;
+  try {
+    writeFileAtomic.sync(absPath, lines.join('\n'), { encoding: 'utf8' });
+  } catch (err) {
+    return { error: `Cannot write file: ${err.message}` };
+  }
+
+  // Log only successful suppression writes for manual audit.
   const suppressionsDir = path.join(process.cwd(), '.praxis');
   if (!fs.existsSync(suppressionsDir)) {
     try {
@@ -428,7 +454,7 @@ function suppressFinding({ file, line, reason }) {
   suppressions.push({
     file: path.relative(process.cwd(), absPath),
     line,
-    reason,
+    reason: safeReason,
     timestamp: new Date().toISOString(),
     status: 'pending_review'
   });
@@ -436,38 +462,13 @@ function suppressFinding({ file, line, reason }) {
     fs.writeFileSync(suppressionsFile, JSON.stringify(suppressions, null, 2), 'utf-8');
   } catch {}
 
-  // Detect indentation and comment style
-  const indent = targetLine.match(/^(\s*)/)?.[1] ?? '';
-  const isJs   = /\.(js|ts|jsx|tsx|mjs|cjs|java|c|cpp|cs|go|rs|swift|kt)$/.test(file);
-  const isPy   = /\.py$/.test(file);
-  const isRb   = /\.rb$/.test(file);
-  const isHtml = /\.(html?|vue|svelte)$/.test(file);
-
-  let ignoreComment;
-  if (isHtml) {
-    ignoreComment = `${indent}<!-- praxis-ignore — ${reason} -->`;
-  } else if (isPy || isRb) {
-    ignoreComment = `${indent}# praxis-ignore — ${reason}`;
-  } else {
-    ignoreComment = `${indent}// praxis-ignore — ${reason}`;
-  }
-
-  // Insert ignore comment on the line BEFORE the finding
-  lines.splice(lineIdx, 0, ignoreComment);
-
-  try {
-    fs.writeFileSync(absPath, lines.join('\n'), 'utf-8');
-  } catch (err) {
-    return { error: `Cannot write file: ${err.message}` };
-  }
-
   return {
     suppressed:    true,
     file:          absPath,
     originalLine:  line,
-    insertedLine:  line, // The ignore comment is now on this line, original moved to line+1
+    insertedLine:  line,
     comment:       ignoreComment,
-    message:       `Added praxis-ignore comment before line ${line} in ${path.basename(file)}.`,
+    message:       `Added trailing praxis-ignore comment on line ${line} in ${path.basename(file)}.`,
   };
 }
 
@@ -506,6 +507,7 @@ function scanFile(filePath) {
         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: lineNum + 1,
@@ -629,13 +631,13 @@ async function handleRequest(request) {
             result = await analyzeFile(args);
             break;
           case 'scan_repo':
-            result = await scanRepo(args);
+            result = await mcpScanRepo(args);
             break;
           case 'get_findings':
-            result = getFindings(args);
+            result = mcpGetFindings(args);
             break;
           case 'suppress_finding':
-            result = suppressFinding(args);
+            result = mcpSuppressFinding(args);
             break;
           case 'explain_and_fix':
             result = await explainAndFix(args);

package/cli/commands/remediate.js

@@ -47,7 +47,7 @@ import {
   TEST_FILE_PATTERNS,
   MAX_FILE_SIZE
 } 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';
 
 // =============================================================================
@@ -468,6 +468,7 @@ async function scanFile(filePath) {
         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: lineNum + 1,

package/cli/commands/rotate.js

@@ -34,7 +34,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 * as output from '../utils/output.js';
 
 // =============================================================================
@@ -439,6 +439,7 @@ async function scanFile(filePath) {
         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: lineNum + 1,

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.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;
           }