praxis-sec 1.0.0

package/cli/utils/scan-playbook.js

@@ -0,0 +1,312 @@
+/**
+ * Scan Playbook
+ * =============
+ *
+ * Hermes-inspired repo-specific intelligence that accumulates across scans
+ * and gets injected into the DeepAnalyzer system prompt as project context.
+ *
+ * After each scan, the playbook is updated with:
+ *   - Tech stack (frameworks, databases, runtimes)
+ *   - Auth patterns detected
+ *   - Known suppressed rules (from memory)
+ *   - Scan statistics (score trend, most common finding categories)
+ *   - Custom notes added by the user
+ *
+ * DeepAnalyzer reads the playbook and prepends it to every LLM call so the
+ * model has richer context than the generic system prompt alone — reducing
+ * both false positives and missed findings.
+ *
+ * PLAYBOOK FILE: .praxis/playbook.md
+ *
+ * USAGE:
+ *   import { ScanPlaybook } from '../utils/scan-playbook.js';
+ *
+ *   const playbook = new ScanPlaybook(rootPath);
+ *
+ *   // After each scan — update with latest recon + score
+ *   playbook.update(recon, scoreResult, suppressedRules);
+ *
+ *   // Get the context string to inject into LLM prompts
+ *   const context = playbook.getPromptContext();
+ *
+ *   // CLI
+ *   playbook.show()   — print current playbook
+ *   playbook.addNote(text) — add a custom note
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const PLAYBOOK_DIR  = '.praxis';
+const PLAYBOOK_FILE = 'playbook.md';
+const HISTORY_FILE  = 'scan-history.json';
+
+/** Minimum number of scans before the playbook is considered reliable */
+const MIN_SCANS_FOR_PLAYBOOK = 2;
+
+export class ScanPlaybook {
+  constructor(rootPath) {
+    this.rootPath     = rootPath;
+    this.playbookDir  = path.join(rootPath, PLAYBOOK_DIR);
+    this.playbookPath = path.join(this.playbookDir, PLAYBOOK_FILE);
+    this.historyPath  = path.join(this.playbookDir, HISTORY_FILE);
+  }
+
+  // ===========================================================================
+  // UPDATE — called after every scan
+  // ===========================================================================
+
+  /**
+   * Update the playbook with the latest scan data.
+   *
+   * @param {object} recon        — from ReconAgent
+   * @param {object} scoreResult  — { score, grade, totalFindings, ... }
+   * @param {object[]} findings   — all findings (used for category frequency)
+   * @param {string[]} suppressedRules — rules currently in memory
+   */
+  update(recon, scoreResult, findings = [], suppressedRules = []) {
+    // Ensure dir exists
+    if (!fs.existsSync(this.playbookDir)) {
+      fs.mkdirSync(this.playbookDir, { recursive: true });
+    }
+
+    // Update scan history
+    const history = this._loadHistory();
+    history.push({
+      date:          new Date().toISOString(),
+      score:         scoreResult?.score ?? null,
+      grade:         scoreResult?.grade?.letter ?? scoreResult?.grade ?? null,
+      totalFindings: scoreResult?.totalFindings ?? findings.length,
+    });
+    // Keep last 50 entries
+    while (history.length > 50) history.shift();
+    this._saveHistory(history);
+
+    // Only update the playbook markdown after MIN_SCANS
+    if (history.length < MIN_SCANS_FOR_PLAYBOOK) return;
+
+    // Preserve user-written custom notes from existing playbook
+    const existingNotes = this._extractCustomNotes();
+
+    const content = this._buildPlaybook(recon, history, findings, suppressedRules, existingNotes);
+    fs.writeFileSync(this.playbookPath, content, 'utf-8');
+  }
+
+  // ===========================================================================
+  // READ — injected into LLM prompts
+  // ===========================================================================
+
+  /**
+   * Returns a compact context string to prepend to LLM system prompts.
+   * Empty string if the playbook doesn't exist yet.
+   */
+  getPromptContext() {
+    if (!fs.existsSync(this.playbookPath)) return '';
+
+    try {
+      const content = fs.readFileSync(this.playbookPath, 'utf-8');
+      // Extract the machine-readable section between <!-- context-start --> and <!-- context-end -->
+      const match = content.match(/<!-- context-start -->([\s\S]*?)<!-- context-end -->/);
+      if (match) return match[1].trim();
+
+      // Fallback: return first 1500 chars of playbook
+      return content.slice(0, 1500);
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * Whether the playbook has enough data to be useful.
+   */
+  get isReady() {
+    return fs.existsSync(this.playbookPath);
+  }
+
+  // ===========================================================================
+  // CLI
+  // ===========================================================================
+
+  show() {
+    if (!fs.existsSync(this.playbookPath)) {
+      console.log('\n  No playbook yet. Run `praxis audit` at least twice to generate one.\n');
+      return;
+    }
+    const content = fs.readFileSync(this.playbookPath, 'utf-8');
+    console.log('\n' + content);
+  }
+
+  /**
+   * Append a custom user note to the playbook.
+   */
+  addNote(text) {
+    if (!fs.existsSync(this.playbookPath)) {
+      console.error('  No playbook yet — run praxis audit first.');
+      return;
+    }
+    const existing = fs.readFileSync(this.playbookPath, 'utf-8');
+    const timestamp = new Date().toISOString().slice(0, 10);
+    const noteSection = existing.includes('## Custom Notes')
+      ? existing.replace('## Custom Notes', `## Custom Notes\n\n- [${timestamp}] ${text}`)
+      : existing + `\n\n## Custom Notes\n\n- [${timestamp}] ${text}\n`;
+    fs.writeFileSync(this.playbookPath, noteSection, 'utf-8');
+    console.log('  Note added to playbook.');
+  }
+
+  // ===========================================================================
+  // INTERNALS
+  // ===========================================================================
+
+  _loadHistory() {
+    try {
+      if (fs.existsSync(this.historyPath)) {
+        return JSON.parse(fs.readFileSync(this.historyPath, 'utf-8'));
+      }
+    } catch { /* start fresh */ }
+    return [];
+  }
+
+  _saveHistory(history) {
+    try {
+      fs.writeFileSync(this.historyPath, JSON.stringify(history, null, 2), 'utf-8');
+    } catch { /* non-fatal */ }
+  }
+
+  _extractCustomNotes() {
+    if (!fs.existsSync(this.playbookPath)) return '';
+    try {
+      const content = fs.readFileSync(this.playbookPath, 'utf-8');
+      const match = content.match(/## Custom Notes([\s\S]*)$/);
+      return match ? match[0] : '';
+    } catch { return ''; }
+  }
+
+  _buildPlaybook(recon, history, findings, suppressedRules, customNotes) {
+    const repoName  = path.basename(this.rootPath);
+    const lastScore = history.at(-1)?.score ?? '?';
+    const lastGrade = history.at(-1)?.grade ?? '?';
+    const scanCount = history.length;
+    const avgScore  = history.length > 0
+      ? Math.round(history.reduce((s, h) => s + (h.score ?? 0), 0) / history.length)
+      : 0;
+
+    // Score trend
+    const trend = history.length >= 2
+      ? (history.at(-1).score ?? 0) - (history.at(-2).score ?? 0)
+      : 0;
+    const trendStr = trend > 0 ? `↑ +${trend}` : trend < 0 ? `↓ ${trend}` : '→ stable';
+
+    // Category frequency
+    const catCounts = {};
+    for (const f of findings) {
+      catCounts[f.category || 'other'] = (catCounts[f.category || 'other'] || 0) + 1;
+    }
+    const topCategories = Object.entries(catCounts)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5)
+      .map(([cat, count]) => `${cat} (${count})`)
+      .join(', ') || 'none';
+
+    // Tech stack
+    const frameworks = recon?.frameworks?.length ? recon.frameworks.join(', ') : 'unknown';
+    const databases  = recon?.databases?.length  ? recon.databases.join(', ')  : 'none detected';
+    const authPat    = recon?.authPatterns?.length ? recon.authPatterns.join(', ') : 'none detected';
+    const runtime    = recon?.runtime || 'unknown';
+    const packageManager = recon?.packageManager || 'unknown';
+    const language   = recon?.language || recon?.primaryLanguage || 'unknown';
+
+    const suppressedSection = suppressedRules.length > 0
+      ? suppressedRules.map(r => `- ${r}`).join('\n')
+      : '- none';
+
+    const historyTable = history.slice(-10).map(h =>
+      `| ${h.date.slice(0, 10)} | ${h.score ?? '?'}/100 | ${h.grade ?? '?'} | ${h.totalFindings ?? '?'} |`
+    ).join('\n');
+
+    return `# Praxis Playbook — ${repoName}
+
+> Auto-generated after ${scanCount} scan(s). Do not edit the section between the
+> \`<!-- context-start -->\` and \`<!-- context-end -->\` markers — it is overwritten on each scan.
+> Add custom notes at the bottom under **Custom Notes**.
+
+<!-- context-start -->
+REPO: ${repoName}
+LANGUAGE: ${language}
+RUNTIME: ${runtime}
+PACKAGE_MANAGER: ${packageManager}
+FRAMEWORKS: ${frameworks}
+DATABASES: ${databases}
+AUTH_PATTERNS: ${authPat}
+LAST_SCORE: ${lastScore}/100 (${lastGrade})
+TREND: ${trendStr}
+AVG_SCORE: ${avgScore}/100 over ${scanCount} scans
+TOP_FINDING_CATEGORIES: ${topCategories}
+SUPPRESSED_RULES: ${suppressedRules.join(', ') || 'none'}
+SCANS_COMPLETED: ${scanCount}
+<!-- context-end -->
+
+## Security Profile
+
+| Property | Value |
+|----------|-------|
+| Language | ${language} |
+| Runtime  | ${runtime} |
+| Frameworks | ${frameworks} |
+| Databases | ${databases} |
+| Auth patterns | ${authPat} |
+
+## Score History (last 10 scans)
+
+| Date | Score | Grade | Findings |
+|------|-------|-------|----------|
+${historyTable}
+
+**Current:** ${lastScore}/100 ${lastGrade} (${trendStr})
+
+## Known Suppressions
+
+The following rules are currently suppressed in \`.praxis/memory.json\`:
+
+${suppressedSection}
+
+## Top Finding Categories
+
+${topCategories}
+
+${customNotes || '## Custom Notes\n\n_Add project-specific context here with: `praxis playbook add-note "..."`_\n'}
+`;
+  }
+}
+
+// =============================================================================
+// CLI COMMAND  (praxis playbook)
+// =============================================================================
+
+import chalk from 'chalk';
+
+export async function playbookCommand(subcommand, args = [], options = {}) {
+  const rootPath = path.resolve(options.path || '.');
+  const playbook = new ScanPlaybook(rootPath);
+
+  switch (subcommand) {
+    case 'show':
+    case undefined:
+      playbook.show();
+      break;
+
+    case 'add-note': {
+      const text = args.join(' ').trim();
+      if (!text) {
+        console.error('  Usage: praxis playbook add-note "your note here"');
+        process.exit(1);
+      }
+      playbook.addNote(text);
+      break;
+    }
+
+    default:
+      console.error(`  Unknown playbook subcommand: ${subcommand}`);
+      console.log('  Usage: praxis playbook [show|add-note "..."]');
+      process.exit(1);
+  }
+}

package/cli/utils/score-history.js

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

package/cli/utils/secrets-verifier.js

@@ -0,0 +1,247 @@
+/**
+ * Secrets Verifier
+ * =================
+ *
+ * Checks if leaked secrets are still active by probing provider APIs.
+ * Only makes safe, read-only API calls (e.g., account info endpoints).
+ *
+ * USAGE:
+ *   const verifier = new SecretsVerifier();
+ *   const results = await verifier.verify(findings);
+ */
+
+// =============================================================================
+// PROVIDER PROBES
+// =============================================================================
+
+/**
+ * Each probe defines how to test if a specific type of key is active.
+ * All probes use read-only GET endpoints — no side effects.
+ */
+const PROBES = {
+  // GitHub tokens
+  GITHUB_TOKEN: {
+    label: 'GitHub',
+    test: async (token) => {
+      const res = await safeFetch('https://api.github.com/user', {
+        headers: { Authorization: `token ${token}`, 'User-Agent': 'praxis-verifier' },
+      });
+      if (res.status === 200) {
+        const data = await res.json();
+        return { active: true, info: `Authenticated as: ${data.login}` };
+      }
+      return { active: false };
+    },
+  },
+  GITHUB_PAT: { label: 'GitHub PAT', test: (t) => PROBES.GITHUB_TOKEN.test(t) },
+
+  // OpenAI
+  OPENAI_API_KEY: {
+    label: 'OpenAI',
+    test: async (token) => {
+      const res = await safeFetch('https://api.openai.com/v1/models', {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      return { active: res.status === 200 };
+    },
+  },
+
+  // Anthropic
+  ANTHROPIC_API_KEY: {
+    label: 'Anthropic',
+    test: async (token) => {
+      const res = await safeFetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers: {
+          'x-api-key': token,
+          'anthropic-version': '2023-06-01',
+          'content-type': 'application/json',
+        },
+        // Send minimal invalid request — 400 means key is valid, 401 means invalid
+        body: JSON.stringify({ model: 'x', max_tokens: 1, messages: [] }),
+      });
+      // 400 = valid key, bad request; 401 = invalid key
+      return { active: res.status !== 401 && res.status !== 403 };
+    },
+  },
+
+  // Stripe
+  STRIPE_LIVE_KEY: {
+    label: 'Stripe',
+    test: async (token) => {
+      const res = await safeFetch('https://api.stripe.com/v1/balance', {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      return { active: res.status === 200 };
+    },
+  },
+  STRIPE_SECRET_KEY: { label: 'Stripe', test: (t) => PROBES.STRIPE_LIVE_KEY.test(t) },
+
+  // AWS
+  AWS_ACCESS_KEY: {
+    label: 'AWS',
+    test: async (token) => {
+      // AWS keys need both access key and secret — we can only flag that the format is valid
+      return { active: null, info: 'Cannot verify AWS keys without secret key pair' };
+    },
+  },
+
+  // Slack
+  SLACK_TOKEN: {
+    label: 'Slack',
+    test: async (token) => {
+      const res = await safeFetch(`https://slack.com/api/auth.test?token=${encodeURIComponent(token)}`);
+      if (res.status === 200) {
+        const data = await res.json();
+        return { active: data.ok === true, info: data.ok ? `Team: ${data.team}` : undefined };
+      }
+      return { active: false };
+    },
+  },
+  SLACK_WEBHOOK: {
+    label: 'Slack Webhook',
+    test: async () => {
+      // Don't probe webhooks — they'd send a message
+      return { active: null, info: 'Webhook verification skipped (would send message)' };
+    },
+  },
+
+  // Sendgrid
+  SENDGRID_API_KEY: {
+    label: 'SendGrid',
+    test: async (token) => {
+      const res = await safeFetch('https://api.sendgrid.com/v3/user/profile', {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      return { active: res.status === 200 };
+    },
+  },
+
+  // Twilio
+  TWILIO_AUTH_TOKEN: {
+    label: 'Twilio',
+    test: async () => {
+      return { active: null, info: 'Twilio requires Account SID + Auth Token pair' };
+    },
+  },
+
+  // NPM
+  NPM_TOKEN: {
+    label: 'npm',
+    test: async (token) => {
+      const res = await safeFetch('https://registry.npmjs.org/-/whoami', {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      if (res.status === 200) {
+        const data = await res.json();
+        return { active: true, info: `Authenticated as: ${data.username}` };
+      }
+      return { active: false };
+    },
+  },
+};
+
+// =============================================================================
+// SAFE FETCH
+// =============================================================================
+
+async function safeFetch(url, options = {}) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5000);
+
+  try {
+    return await fetch(url, { ...options, signal: controller.signal }); // praxis-ignore SSRF_USER_URL_FETCH — provider API endpoint for liveness check
+  } catch {
+    return { status: 0, json: async () => ({}), text: async () => '' };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// =============================================================================
+// SECRETS VERIFIER
+// =============================================================================
+
+export class SecretsVerifier {
+  /**
+   * Verify an array of secret findings.
+   * Only probes findings that have a matching provider probe.
+   *
+   * @param {object[]} findings — Secret findings with rule and matched fields
+   * @returns {Promise<object[]>} — Findings with verifyResult attached
+   */
+  async verify(findings) {
+    const secretFindings = findings.filter(
+      f => f.category === 'secrets' || f.category === 'secret'
+    );
+
+    const results = [];
+
+    for (const finding of secretFindings) {
+      const probe = this._findProbe(finding.rule);
+      if (!probe) {
+        results.push({ finding, result: { active: null, info: 'No probe available' } });
+        continue;
+      }
+
+      // Extract the actual secret value from the match
+      const secret = this._extractSecret(finding.matched);
+      if (!secret) {
+        results.push({ finding, result: { active: null, info: 'Could not extract key value' } });
+        continue;
+      }
+
+      try {
+        const result = await probe.test(secret);
+        finding.verifyResult = {
+          active: result.active,
+          provider: probe.label,
+          info: result.info || (result.active ? 'Key is ACTIVE — rotate immediately' : 'Key is inactive or revoked'),
+        };
+        results.push({ finding, result: finding.verifyResult });
+      } catch {
+        finding.verifyResult = { active: null, provider: probe.label, info: 'Verification failed' };
+        results.push({ finding, result: finding.verifyResult });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Find the probe for a given rule name.
+   */
+  _findProbe(rule) {
+    // Direct match
+    if (PROBES[rule]) return PROBES[rule];
+
+    // Partial match (rule may have extra suffixes)
+    for (const [key, probe] of Object.entries(PROBES)) {
+      if (rule.includes(key) || key.includes(rule)) return probe;
+    }
+    return null;
+  }
+
+  /**
+   * Extract the secret value from a regex match.
+   * Matches typically look like: API_KEY="sk-1234..." or token: 'ghp_...'
+   */
+  _extractSecret(matched) {
+    if (!matched) return null;
+
+    // Try to extract quoted value
+    const quoted = matched.match(/['"]([^'"]{8,})['"]$/);
+    if (quoted) return quoted[1];
+
+    // Try to extract after = or :
+    const assigned = matched.match(/[=:]\s*['"]?([a-zA-Z0-9_\-./+]{8,})['"]?$/);
+    if (assigned) return assigned[1];
+
+    // If the match itself looks like a token, use it
+    if (/^[a-zA-Z0-9_\-]{20,}$/.test(matched)) return matched;
+
+    return null;
+  }
+}
+
+export default SecretsVerifier;