praxis-sec 1.2.1 → 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

@@ -16,9 +16,10 @@ 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 { 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';
@@ -28,7 +29,7 @@ const BASELINE_FILE = '.praxis/baseline.json';
  * Uses rule + relative file path + first 40 chars of matched text.
  */
 function fingerprint(finding, rootPath) {
-  const relFile = path.relative(rootPath, finding.file || '').replace(/\\/g, '/');
+  const relFile = displayPath(finding.file || '', rootPath);
   const matched = (finding.matched || '').slice(0, 40);
   return `${finding.rule}:${relFile}:${matched}`;
 }
@@ -60,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

@@ -19,7 +19,9 @@
 
 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';
@@ -34,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';
@@ -44,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;
@@ -56,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);
   }
 
@@ -87,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,
@@ -181,7 +185,7 @@ export async function ciCommand(targetPath = '.', options = {}) {
       }])),
       ...(options.includeFindings ? {
         findings: allFindings.map(f => ({
-          file: path.relative(absolutePath, f.file).replace(/\\/g, '/'),
+          file: displayPath(f.file, absolutePath),
           line: f.line, rule: f.rule, severity: f.severity,
         })),
       } : {}),
@@ -203,7 +207,7 @@ export async function ciCommand(targetPath = '.', options = {}) {
     if (critical > 0) {
       console.log(`[praxis] Critical findings:`);
       for (const f of allFindings.filter(f => f.severity === 'critical').slice(0, 5)) {
-        const rel = path.relative(absolutePath, f.file).replace(/\\/g, '/');
+        const rel = displayPath(f.file, absolutePath);
         console.log(`  - ${f.rule} at ${rel}:${f.line}`);
       }
     }
@@ -274,7 +278,7 @@ function emitGitHubAnnotations(findings, rootPath) {
   if (process.env.GITHUB_ACTIONS !== 'true') return;
   for (const f of findings) {
     if (!f.file || !f.line) continue;
-    const rel = path.relative(rootPath, f.file).replace(/\\/g, '/');
+    const rel = displayPath(f.file, rootPath);
     const level = ['critical', 'high'].includes(f.severity) ? 'error' : 'warning';
     const col = f.column || 1;
     const escapeData = value => String(value).replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
@@ -350,7 +354,7 @@ function postPRComment(scoreResult, findings, depVulns, rootPath, duration) {
     body += `### Critical & High Findings\n\n`;
     body += `| Severity | File | Issue |\n|----------|------|-------|\n`;
     for (const f of findings.filter(f => f.severity === 'critical' || f.severity === 'high').slice(0, 20)) {
-      const rel = path.relative(rootPath, f.file).replace(/\\/g, '/');
+      const rel = displayPath(f.file, rootPath);
       body += `| ${f.severity.toUpperCase()} | \`${rel}:${f.line}\` | ${(f.title || f.rule).slice(0, 60)} |\n`;
     }
     body += '\n';

package/cli/commands/diff.js

@@ -16,6 +16,7 @@ import { execFileSync } from 'child_process';
 import path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
+import { displayPath } from '../core/paths.js';
 import { SECRET_PATTERNS, SECURITY_PATTERNS, SKIP_EXTENSIONS, SKIP_FILENAMES } from '../utils/patterns.js';
 import { buildOrchestrator } from '../agents/index.js';
 import { ScoringEngine } from '../agents/scoring-engine.js';
@@ -165,7 +166,7 @@ export async function diffCommand(ref, options) {
       const sevColor = f.severity === 'critical' ? chalk.red :
                         f.severity === 'high' ? chalk.yellow :
                         f.severity === 'medium' ? chalk.cyan : chalk.gray;
-      const relPath = path.relative(absolutePath, f.file);
+      const relPath = displayPath(f.file, absolutePath);
       console.log(`  ${sevColor(`[${f.severity.toUpperCase()}]`)} ${chalk.white(f.title)}`);
       console.log(chalk.gray(`    ${relPath}:${f.line} → ${f.fix || f.description}`));
       shown++;

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/legal.js

@@ -19,6 +19,7 @@ import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
+import { displayPath } from '../core/paths.js';
 import { LegalRiskAgent } from '../agents/legal-risk-agent.js';
 import * as output from '../utils/output.js';
 
@@ -136,7 +137,7 @@ export async function legalCommand(targetPath = '.', options = {}) {
       const riskLabel = RISK_LABELS[riskKey] || riskKey;
 
       console.log(`  ${sevBadge}  ${chalk.white.bold(f.title)}`);
-      console.log(`          ${riskColor(`[${riskLabel}]`)}  ${chalk.gray(path.relative(absolutePath, f.file) || f.file)}`);
+      console.log(`          ${riskColor(`[${riskLabel}]`)}  ${chalk.gray(displayPath(f.file, absolutePath))}`);
       console.log();
       console.log(`          ${chalk.gray(f.description)}`);
       console.log();

package/cli/commands/mcp.js

@@ -34,9 +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';
@@ -90,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: {
@@ -117,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: {
@@ -252,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
@@ -269,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;
@@ -288,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 = {};
@@ -304,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,
@@ -313,7 +321,7 @@ async function scanRepo({ path: targetPath, agents: agentFilter, llm = false, ou
         severity:      f.severity,
         category:      f.category,
         rule:          f.rule,
-        file:          f.file ? path.relative(rootPath, f.file) : null,
+        file:          f.file ? displayPath(f.file, rootPath) : null,
         line:          f.line,
         description:   f.description,
         remediation:   f.remediation,
@@ -321,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) {
@@ -332,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;
@@ -342,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)) {
@@ -367,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,
@@ -375,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)) {
@@ -392,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)` };
   }
 
@@ -410,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 {
@@ -427,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'
   });
@@ -435,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)}.`,
   };
 }
 
@@ -505,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,
@@ -628,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/openclaw.js

@@ -15,6 +15,7 @@
 import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
+import { displayPath } from '../core/paths.js';
 import * as output from '../utils/output.js';
 import { AgentConfigScanner } from '../agents/agent-config-scanner.js';
 import { MCPSecurityAgent } from '../agents/mcp-security-agent.js';
@@ -138,11 +139,7 @@ async function runJsonMode(absolutePath, options) {
   const findings = [...configFindings, ...mcpFindings];
   const normFindings = findings.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),
   }));
   const result = {
     findings: normFindings,
@@ -174,7 +171,7 @@ function printFindings(findings, rootPath) {
   findings.sort((a, b) => (sevOrder[a.severity] ?? 4) - (sevOrder[b.severity] ?? 4));
 
   for (const f of findings) {
-    const relFile = path.relative(rootPath, f.file).replace(/\\/g, '/');
+    const relFile = displayPath(f.file, rootPath);
     const sevLabel = f.severity === 'critical' ? chalk.red.bold('CRITICAL')
       : f.severity === 'high' ? chalk.yellow('HIGH')
       : chalk.blue('MEDIUM');

package/cli/commands/red-team.js

@@ -18,6 +18,7 @@ import path from 'path';
 import { renderFindingsSARIF } from '../core/output/sarif.js';
 import chalk from 'chalk';
 import ora from 'ora';
+import { displayPath } from '../core/paths.js';
 import { buildOrchestratorAsync } from '../agents/index.js';
 import { SwarmOrchestrator } from '../agents/swarm-orchestrator.js';
 import { ReconAgent } from '../agents/recon-agent.js';
@@ -267,7 +268,7 @@ function printResults(scoreResult, findings, recon, agentResults, depVulns, root
     console.log(chalk.yellow('  ' + '─'.repeat(58)));
 
     for (const f of findings.slice(0, 20)) {
-      const relFile = path.relative(rootPath, f.file).replace(/\\/g, '/');
+      const relFile = displayPath(f.file, rootPath);
       const sevColor = SEV_COLOR[f.severity] || chalk.white;
       const aiTag = f.aiClassification === 'FALSE_POSITIVE'
         ? chalk.gray(' [FP]')

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,