praxis-sec 1.0.0

package/cli/utils/entropy.js

@@ -0,0 +1,132 @@
+/**
+ * Shannon Entropy Scoring
+ * =======================
+ *
+ * Used to reduce false positives in secret detection.
+ *
+ * CONCEPT:
+ * Real secrets (API keys, tokens) are randomly generated and have HIGH entropy.
+ * Placeholder values like "your-api-key-here" or "example123" have LOW entropy
+ * because they follow predictable patterns or use common words.
+ *
+ * Shannon entropy measures the "randomness" of a string on a scale of 0-8.
+ * - 0:   Completely uniform  ("aaaaaaaaaaaaaaaa")
+ * - 2-3: Low entropy         ("your-api-key-here", "example_value")
+ * - 3.5+: High entropy       ("xK9mP2nQ8vL4jR7s") - likely a real secret
+ * - 5+:   Very high entropy  (random bytes, base64)
+ *
+ * We only apply entropy checks to "generic" patterns that lack specific prefixes.
+ * Patterns with known prefixes (sk-ant-, ghp_, AKIA...) are already precise enough.
+ */
+
+// =============================================================================
+// ENTROPY CALCULATION
+// =============================================================================
+
+/**
+ * Calculate Shannon entropy of a string.
+ * Returns a number between 0 and log2(charset size).
+ */
+export function shannonEntropy(str) {
+  if (!str || str.length === 0) return 0;
+
+  const freq = {};
+  for (const char of str) {
+    freq[char] = (freq[char] || 0) + 1;
+  }
+
+  return Object.values(freq).reduce((sum, count) => {
+    const p = count / str.length;
+    return sum - p * Math.log2(p);
+  }, 0);
+}
+
+// Minimum entropy to consider a match a real secret
+// Real secrets: >3.5 | Placeholders: <3.0 | Safe buffer: 3.5
+export const ENTROPY_THRESHOLD = 3.5;
+
+// Strings shorter than this are unreliable for entropy analysis
+const MIN_ENTROPY_LENGTH = 16;
+
+// =============================================================================
+// VALUE EXTRACTION
+// =============================================================================
+
+/**
+ * Extract the actual secret value from a matched string.
+ *
+ * Patterns often match the full assignment, e.g.:
+ *   apiKey = "abc123xyz..."
+ *
+ * We want to score just the value part, not the variable name,
+ * because variable names are low-entropy and would skew the score.
+ */
+function extractSecretValue(matched) {
+  // Match: = "value" or : "value" or = value
+  const assignmentMatch = matched.match(/[:=]\s*["']?([a-zA-Z0-9_\-+/=.]{12,})["']?\s*$/);
+  if (assignmentMatch) return assignmentMatch[1];
+
+  // Match: Bearer <token>
+  const bearerMatch = matched.match(/Bearer\s+([a-zA-Z0-9_\-+/=.]{12,})/i);
+  if (bearerMatch) return bearerMatch[1];
+
+  // Match: quoted value anywhere
+  const quotedMatch = matched.match(/["']([a-zA-Z0-9_\-+/=.]{12,})["']/);
+  if (quotedMatch) return quotedMatch[1];
+
+  return matched;
+}
+
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+
+/**
+ * Determine if a regex match looks like a real secret based on entropy.
+ *
+ * Returns true  → keep the finding (high entropy or can't determine)
+ * Returns false → filter it out (low entropy, likely a placeholder)
+ */
+export function isHighEntropyMatch(matched) {
+  const value = extractSecretValue(matched);
+
+  // If we can't extract a meaningful value, keep the finding
+  if (!value || value.length < MIN_ENTROPY_LENGTH) return true;
+
+  // Common placeholder patterns - fast path rejection
+  const PLACEHOLDER_PATTERNS = [
+    /^(your[-_]?|my[-_]?|example[-_]?|test[-_]?|dummy[-_]?|fake[-_]?|sample[-_]?)/i,
+    /^(xxx+|yyy+|zzz+|aaa+|000+)/i,
+    /^(insert|replace|changeme|placeholder|todo|fixme)/i,
+    /([-_]here|[-_]goes|[-_]key|[-_]token|[-_]secret)$/i,
+    /^[a-z]+[-_][a-z]+[-_][a-z]+$/, // looks like-a-passphrase not a key
+    /^(add[-_]?your|put[-_]?your|enter[-_]?your|set[-_]?your)/i,
+    /^(secret|password|token|apikey|api_key|key|value)[-_]?[0-9]*$/i,
+    /^(n\/a|null|undefined|none|empty|blank)/i,
+    /^(demo|staging|dev|development|local)[-_]/i,
+    /^(abcdef|qwerty|asdfgh|123456|letmein)/i,
+    /(.)\1{5,}/, // 6+ repeated chars: aaaaaaa, 111111
+  ];
+
+  if (PLACEHOLDER_PATTERNS.some(p => p.test(value))) return false;
+
+  const entropy = shannonEntropy(value);
+  return entropy >= ENTROPY_THRESHOLD;
+}
+
+/**
+ * Get a human-readable confidence label for a finding.
+ */
+export function getConfidence(pattern, matched) {
+  // Strict prefix patterns (e.g. sk-ant-, ghp_, AKIA) are always high confidence
+  if (!pattern.requiresEntropyCheck) return 'high';
+
+  const value = extractSecretValue(matched);
+  if (!value || value.length < MIN_ENTROPY_LENGTH) return 'medium';
+
+  const entropy = shannonEntropy(value);
+
+  if (entropy >= 4.5) return 'high';
+  if (entropy >= ENTROPY_THRESHOLD) return 'medium';
+  return 'low'; // Should have been filtered, but just in case
+}

package/cli/utils/fix-ledger.js

@@ -0,0 +1,127 @@
+/**
+ * Fix ledger — read the find→fix→verify record for a project.
+ * ============================================================================
+ *
+ * The scanner's stated moat is "find → fix → verify", but the report stops at
+ * findings, so the differentiator is only visible in the terminal. `.praxis/fixes.jsonl`
+ * already records every applied change (with its verification outcome and the plan
+ * needed to reverse it), and `.praxis/failures.jsonl` records every plan that was
+ * proposed and *rejected* — which is the more interesting half of the story, since a
+ * rejected fix is the loop declining to make a change it cannot justify.
+ *
+ * Semantics worth stating plainly, because it is easy to misreport:
+ *
+ *   - `fixes.jsonl` means **currently applied**. `praxis undo` *removes* reverted
+ *     entries from the log rather than annotating them, so this module reports no
+ *     "undone" count — there is no such data, and inventing one would be a false
+ *     negative (the exact failure mode this project keeps refusing to ship).
+ *   - An entry is **reversible** when its plan still carries enough information to
+ *     undo it: a file creation, an append, or line edits.
+ *   - Unreadable or malformed lines are counted, never silently dropped.
+ *
+ * Everything here is best-effort and never throws: a missing ledger must not break a
+ * report, and a broken ledger must not invent activity.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const FIX_LOG = path.join('.praxis', 'fixes.jsonl');
+const FAILURE_LOG = path.join('.praxis', 'failures.jsonl');
+
+/**
+ * Reads a JSONL log, tolerating absence and malformed lines.
+ * @returns {{entries: object[], unreadable: number, error: string|null}}
+ */
+function readJsonl(absolutePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(absolutePath, 'utf8');
+  } catch (err) {
+    const missing = err.code === 'ENOENT';
+    return { entries: [], unreadable: 0, error: missing ? null : err.message };
+  }
+
+  const entries = [];
+  let unreadable = 0;
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed && typeof parsed === 'object') entries.push(parsed);
+      else unreadable++;
+    } catch {
+      unreadable++;
+    }
+  }
+  return { entries, unreadable, error: null };
+}
+
+/** True when the plan still carries enough information for `praxis undo` to reverse it. */
+export function isReversible(plan) {
+  const files = plan?.files;
+  if (!Array.isArray(files) || files.length === 0) return false;
+  return files.some(fc =>
+    fc && (fc.create === true || fc.append !== undefined || Array.isArray(fc.edits) && fc.edits.length > 0)
+  );
+}
+
+/**
+ * Reads the fix ledger for a project.
+ *
+ * @param {string} rootPath  Project root (the directory containing `.praxis/`).
+ * @returns {{
+ *   applied: object[], rejected: object[],
+ *   appliedUnreadable: number, rejectedUnreadable: number,
+ *   error: string|null, hasLog: boolean
+ * }}
+ */
+export function readFixLedger(rootPath = process.cwd()) {
+  // Coerce before any path work: `path.join(null, …)` throws a TypeError outside the
+  // readJsonl try/catch, which would break the "never throws" contract this module
+  // advertises. A missing root falls back to the cwd, which simply yields no ledger.
+  const root = typeof rootPath === 'string' && rootPath.length > 0 ? rootPath : process.cwd();
+
+  const fixes = readJsonl(path.join(root, FIX_LOG));
+  const failures = readJsonl(path.join(root, FAILURE_LOG));
+
+  return {
+    applied: fixes.entries,
+    rejected: failures.entries,
+    appliedUnreadable: fixes.unreadable,
+    rejectedUnreadable: failures.unreadable,
+    error: fixes.error || failures.error,
+    hasLog: fixes.entries.length > 0 || fixes.error !== null,
+  };
+}
+
+/** Aggregate counters for the ledger panel. */
+export function summarizeFixLedger(ledger) {
+  const applied = ledger?.applied || [];
+  const rejected = ledger?.rejected || [];
+
+  const verified = applied.filter(e => e.verified === true).length;
+  const reversible = applied.filter(e => isReversible(e.plan)).length;
+
+  // Findings addressed by an applied fix. Summed across entries, so a finding fixed in
+  // two files counts once per file — that is what the log actually records.
+  const findingsFixed = applied.reduce((sum, e) => sum + (Array.isArray(e.findings) ? e.findings.length : 0), 0);
+
+  const rejectedByReason = {};
+  for (const r of rejected) {
+    const reason = r.reason || 'unknown';
+    rejectedByReason[reason] = (rejectedByReason[reason] || 0) + 1;
+  }
+
+  return {
+    appliedCount: applied.length,
+    verified,
+    unverified: applied.length - verified,
+    reversible,
+    irreversible: applied.length - reversible,
+    findingsFixed,
+    rejectedCount: rejected.length,
+    rejectedByReason,
+  };
+}

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

@@ -0,0 +1,252 @@
+/**
+ * Hermes Tool Registry — Praxis × Hermes Agent
+ * =================================================
+ *
+ * Declares Praxis's five security tools in the Hermes Agent tool-registry
+ * format. Import this module in your Hermes agent bootstrap to register
+ * Praxis as a first-class citizen in the tool registry.
+ *
+ * USAGE:
+ *   import { HERMES_TOOLS, registerWithHermes } from './hermes-tool-registry.js';
+ *
+ *   // Option A — register all tools at once
+ *   await registerWithHermes(agent.toolRegistry);
+ *
+ *   // Option B — use the raw definitions
+ *   for (const tool of HERMES_TOOLS) agent.toolRegistry.register(tool);
+ *
+ * SECURITY NOTE:
+ *   These definitions are pinned, hardcoded, and integrity-verified at load
+ *   time. They are never fetched from a remote URL. Do not replace the
+ *   INTEGRITY_HASH values without auditing the updated definitions.
+ */
+
+import { createHash } from 'crypto';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// =============================================================================
+// TOOL DEFINITIONS (Hermes function-call schema format)
+// =============================================================================
+
+export const HERMES_TOOLS = [
+  {
+    name: 'praxis_audit',
+    description:
+      'Run a Praxis security audit on a local codebase directory. ' +
+      'Returns a findings report with severity-graded issues, CWE/OWASP mappings, ' +
+      'and remediation guidance. Use before deploying any code or merging PRs.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute path to the project root directory to scan.',
+        },
+        severity: {
+          type: 'string',
+          enum: ['critical', 'high', 'medium', 'low'],
+          description: 'Minimum severity threshold for reported findings.',
+          default: 'medium',
+        },
+        deep: {
+          type: 'boolean',
+          description: 'Enable deep LLM-powered taint analysis (Haiku→Sonnet→Opus pipeline). Slower but more accurate.',
+          default: false,
+        },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    handler: async ({ path: scanPath, severity = 'medium', deep = false }) => {
+      const { auditCommand } = await import('../commands/audit.js');
+      return auditCommand(scanPath, { severity, deep, json: true, quiet: true });
+    },
+  },
+
+  {
+    name: 'praxis_scan_mcp',
+    description:
+      'Analyze an MCP server manifest (URL or local file path) for security issues ' +
+      'before connecting. Checks for prompt injection in tool descriptions, credential ' +
+      'harvesting patterns, Hermes function-call poisoning, schema bypass (additionalProperties: true), ' +
+      'and known-malicious server hashes. Returns per-tool findings.',
+    parameters: {
+      type: 'object',
+      properties: {
+        target: {
+          type: 'string',
+          description: 'URL (https://...) or absolute local file path to the MCP manifest JSON.',
+        },
+      },
+      required: ['target'],
+      additionalProperties: false,
+    },
+    handler: async ({ target }) => {
+      const { scanMcpCommand } = await import('../commands/scan-mcp.js');
+      return scanMcpCommand(target, { json: true });
+    },
+  },
+
+  {
+    name: 'praxis_get_findings',
+    description:
+      'Retrieve findings from the last saved Praxis scan report for a project. ' +
+      'Optionally filter by minimum severity. Returns an array of findings with rule, ' +
+      'title, severity, file, line, and remediation guidance.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute path to the project root (used to locate the saved report).',
+        },
+        severity: {
+          type: 'string',
+          enum: ['critical', 'high', 'medium', 'low'],
+          description: 'Minimum severity to include in results.',
+          default: 'medium',
+        },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    handler: async ({ path: projectPath, severity = 'medium' }) => {
+      const { mcpGetFindings } = await import('../commands/mcp.js');
+      return mcpGetFindings({ projectPath, severity });
+    },
+  },
+
+  {
+    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 ' +
+      'confirmed false positive and you can document why it is safe.',
+    parameters: {
+      type: 'object',
+      properties: {
+        file: {
+          type: 'string',
+          description: 'Absolute path to the source file containing the finding.',
+        },
+        line: {
+          type: 'number',
+          description: 'Line number of the finding (1-based).',
+        },
+        reason: {
+          type: 'string',
+          description: 'Human-readable explanation of why this finding is safe to suppress.',
+        },
+      },
+      required: ['file', 'line', 'reason'],
+      additionalProperties: false,
+    },
+    handler: async ({ file, line, reason }) => {
+      const { mcpSuppressFinding } = await import('../commands/mcp.js');
+      return mcpSuppressFinding({ file, line, reason });
+    },
+  },
+
+  {
+    name: 'praxis_memory_list',
+    description:
+      'List all entries in the Praxis security memory for a project. ' +
+      'The memory stores learned false positives that are automatically filtered ' +
+      'from future scans. Returns each entry with its rule, file pattern, and ' +
+      'the snippet that was suppressed.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute path to the project root.',
+        },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    handler: async ({ path: projectPath }) => {
+      const { SecurityMemory } = await import('./security-memory.js');
+      const mem = new SecurityMemory(projectPath);
+      return mem.list();
+    },
+  },
+];
+
+// =============================================================================
+// INTEGRITY VERIFICATION
+// Each tool definition is hashed at module load time. If the registry is
+// tampered with (e.g. supply-chain attack), the hash check will fail.
+// Run `node -e "import('./hermes-tool-registry.js').then(m => m.printHashes())"` to regenerate.
+// =============================================================================
+
+const KNOWN_HASHES = {
+  praxis_audit:             '4d282d29e44fcc01',
+  praxis_scan_mcp:          'f967aea9626ca840',
+  praxis_get_findings:      'c09c9447efd574b3',
+  praxis_suppress_finding:  '3b7339419fe52ac7',
+  praxis_memory_list:       'c71c996716d1805b',
+};
+
+function toolHash(tool) {
+  // Hash name + description + parameter schema only (not handler function)
+  const canonical = JSON.stringify({ name: tool.name, description: tool.description, parameters: tool.parameters });
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}
+
+export function verifyIntegrity() {
+  const mismatches = [];
+  for (const tool of HERMES_TOOLS) {
+    const actual = toolHash(tool);
+    const expected = KNOWN_HASHES[tool.name];
+    if (expected && actual !== expected) {
+      mismatches.push({ tool: tool.name, expected, actual });
+    }
+  }
+  return mismatches;
+}
+
+export function printHashes() {
+  console.log('// Current tool definition hashes — paste into KNOWN_HASHES:');
+  for (const tool of HERMES_TOOLS) {
+    console.log(`  ${tool.name}: '${toolHash(tool)}',`);
+  }
+}
+
+// =============================================================================
+// REGISTRATION HELPER
+// =============================================================================
+
+/**
+ * Register all Praxis tools with a Hermes tool registry instance.
+ *
+ * @param {object} toolRegistry — Hermes ToolRegistry instance with a .register() method
+ * @param {object} options
+ * @param {boolean} [options.skipVerification=false] — bypass hash verification (not recommended)
+ * @param {boolean} [options.quiet=false] — suppress registration log lines
+ */
+export async function registerWithHermes(toolRegistry, options = {}) {
+  if (!options.skipVerification) { // praxis-ignore — this is the integrity-check implementation, not a bypass
+    const mismatches = verifyIntegrity();
+    if (mismatches.length > 0) {
+      const msg = mismatches.map(m => `  ${m.tool}: expected ${m.expected}, got ${m.actual}`).join('\n');
+      throw new Error(`Praxis tool registry integrity check failed:\n${msg}\n\nThis may indicate a supply-chain attack. Run praxis --version to verify your installation.`);
+    }
+  }
+
+  for (const tool of HERMES_TOOLS) {
+    if (typeof toolRegistry.register === 'function') {
+      toolRegistry.register(tool);
+    } else if (typeof toolRegistry.registerTool === 'function') {
+      toolRegistry.registerTool(tool);
+    } else {
+      throw new Error('toolRegistry must have a .register() or .registerTool() method');
+    }
+    if (!options.quiet) {
+      console.log(`  [praxis] Registered tool: ${tool.name}`);
+    }
+  }
+}

package/cli/utils/intel/cache.js

@@ -0,0 +1,61 @@
+/**
+ * Per-source disk cache with TTL.
+ *
+ * Lives at ~/.praxis/intel/<source>.json. Each entry is wrapped in:
+ *   { fetchedAt: ISO string, ttlMs: number, payload: ... }
+ *
+ * Sources call cache.read('osv') to get the last good payload (or null),
+ * and cache.write('osv', data, ttlMs) after a successful fetch.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// Lazy — resolve home each call so HOME overrides (e.g. in tests) take effect.
+const rootDir = () => path.join(os.homedir(), '.praxis', 'intel');
+
+function ensureDir() {
+  const dir = rootDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function pathFor(source) {
+  return path.join(rootDir(), `${source}.json`);
+}
+
+export function read(source) {
+  try {
+    const file = pathFor(source);
+    if (!fs.existsSync(file)) return null;
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function write(source, payload, ttlMs) {
+  ensureDir();
+  const entry = {
+    fetchedAt: new Date().toISOString(),
+    ttlMs,
+    payload,
+  };
+  fs.writeFileSync(pathFor(source), JSON.stringify(entry, null, 2));
+  return entry;
+}
+
+export function isFresh(entry) {
+  if (!entry || !entry.fetchedAt || !entry.ttlMs) return false;
+  const age = Date.now() - new Date(entry.fetchedAt).getTime();
+  return age < entry.ttlMs;
+}
+
+export function ageMs(entry) {
+  if (!entry || !entry.fetchedAt) return Infinity;
+  return Date.now() - new Date(entry.fetchedAt).getTime();
+}
+
+export function root() {
+  return rootDir();
+}

package/cli/utils/intel/http.js

@@ -0,0 +1,88 @@
+/**
+ * HTTP helper used by all intel source fetchers.
+ *
+ * - 30s timeout (overridable)
+ * - Retries on 5xx and network errors with exponential backoff
+ * - User-Agent header so providers can identify praxis traffic
+ */
+
+const DEFAULT_TIMEOUT = 30_000;
+const DEFAULT_RETRIES = 2;
+const USER_AGENT = 'praxis-intel/1.0 (+https://github.com/Ganron007/Praxis)';
+
+export async function safeFetch(url, options = {}) {
+  const { timeout = DEFAULT_TIMEOUT, retries = DEFAULT_RETRIES, ...rest } = options;
+
+  // Scanner hardening: only allow http/https to external feed endpoints.
+  // Prevents SSRF if a future intel source ever resolves a fetch target from
+  // untrusted data (file://, ftp://, and internal hosts are rejected).
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`safeFetch: invalid URL ${String(url).slice(0, 80)}`);
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`safeFetch: non-http(s) scheme rejected: ${parsed.protocol}`);
+  }
+  const LOOPBACK_RE = /^(?:127\.|10\.|172\.(?:1[6-9]|2\d|3[01])\.|192\.168\.|0\.0\.0\.0|::1|localhost)(?:[:/]|$)/i;
+  if (LOOPBACK_RE.test(parsed.hostname)) {
+    throw new Error(`safeFetch: loopback/private host rejected: ${parsed.hostname}`);
+  }
+
+  let lastErr;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+      const res = await fetch(url, { // praxis-ignore SSRF_USER_URL_FETCH — scheme + loopback guarded above
+        ...rest,
+        signal: controller.signal,
+        headers: {
+          'User-Agent': USER_AGENT,
+          ...(rest.headers || {}),
+        },
+      });
+      clearTimeout(timer);
+
+      // Retry on 5xx, otherwise return whatever we got (caller decides)
+      if (res.status >= 500 && attempt < retries) {
+        await sleep(backoffMs(attempt));
+        continue;
+      }
+      return res;
+    } catch (err) {
+      clearTimeout(timer);
+      lastErr = err;
+      if (attempt < retries) {
+        await sleep(backoffMs(attempt));
+        continue;
+      }
+    }
+  }
+  throw lastErr || new Error(`Failed to fetch ${url}`);
+}
+
+export async function fetchJson(url, options = {}) {
+  const res = await safeFetch(url, options);
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} from ${url}`);
+  }
+  return res.json();
+}
+
+export async function fetchText(url, options = {}) {
+  const res = await safeFetch(url, options);
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} from ${url}`);
+  }
+  return res.text();
+}
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+function backoffMs(attempt) {
+  return Math.min(1000 * Math.pow(2, attempt), 8000);
+}