@lhi/tdd-audit 1.8.4 → 1.10.0

package/lib/config.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const CONFIG_FILE = '.tdd-audit.json';
+
+const DEFAULTS = {
+  port:              3000,
+  output:            'text',    // 'text' | 'json' | 'sarif'
+  severityThreshold: 'LOW',     // minimum severity to include in output
+  ignore:            [],        // path prefixes to skip
+  provider:          null,      // 'anthropic' | 'openai' | 'gemini' | 'ollama'
+  model:             null,
+  apiKey:            null,
+  baseUrl:           null,      // override base URL for OpenAI-compatible providers
+  apiKeyEnv:         null,      // env var name to read the key from
+  serverApiKey:      null,      // key required on REST API calls
+  trustProxy:        false,     // trust X-Forwarded-For for rate limiting
+};
+
+// Template written by `tdd-audit init`
+const INIT_TEMPLATE = {
+  provider:          'openai',
+  model:             'gpt-4o',
+  apiKeyEnv:         'OPENAI_API_KEY',
+  baseUrl:           null,
+  output:            'text',
+  severityThreshold: 'LOW',
+  port:              3000,
+  serverApiKey:      null,
+  ignore:            ['node_modules', 'dist', 'build', 'coverage'],
+};
+
+/**
+ * Load config from an explicit file path or from .tdd-audit.json in cwd.
+ * CLI flags win over file config; file config wins over DEFAULTS.
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @param {object} [cliOverrides={}]  - may include { configPath: '/abs/path/to/file.json' }
+ * @returns {object}
+ */
+function loadConfig(cwd = process.cwd(), cliOverrides = {}) {
+  let fileConfig = {};
+
+  // Explicit --config path wins over the cwd convention
+  const filePath = cliOverrides.configPath
+    ? path.resolve(cliOverrides.configPath)
+    : path.join(cwd, CONFIG_FILE);
+
+  if (fs.existsSync(filePath)) {
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      fileConfig = JSON.parse(raw);
+    } catch (err) {
+      process.stderr.write(`⚠️  Could not parse ${filePath}: ${err.message}\n`);
+    }
+  }
+
+  const merged = { ...DEFAULTS, ...fileConfig };
+
+  // Apply CLI overrides (skip internal keys like configPath)
+  const INTERNAL = new Set(['configPath']);
+  for (const [key, val] of Object.entries(cliOverrides)) {
+    if (!INTERNAL.has(key) && val !== undefined && val !== null) merged[key] = val;
+  }
+
+  // Resolve apiKey from env var if apiKeyEnv is set and apiKey isn't already
+  if (!merged.apiKey && merged.apiKeyEnv) {
+    merged.apiKey = process.env[merged.apiKeyEnv] || null;
+  }
+
+  return merged;
+}
+
+/**
+ * Parse relevant CLI args into an overrides object for loadConfig.
+ * @param {string[]} args - process.argv.slice(2)
+ * @returns {object}
+ */
+function parseCliOverrides(args) {
+  const get = (flag) => {
+    const i = args.indexOf(flag);
+    return i !== -1 ? args[i + 1] : undefined;
+  };
+  const overrides = {};
+  const configPath = get('--config');    if (configPath) overrides.configPath = configPath;
+  const port       = get('--port');      if (port)       overrides.port = Number(port);
+  const provider   = get('--provider'); if (provider)   overrides.provider = provider;
+  const model      = get('--model');    if (model)      overrides.model = model;
+  const apiKey     = get('--api-key');  if (apiKey)     overrides.apiKey = apiKey;
+  const baseUrl    = get('--base-url'); if (baseUrl)    overrides.baseUrl = baseUrl;
+  const format     = get('--format');   if (format)     overrides.output = format;
+  const srvKey     = get('--api-key');  if (srvKey)     overrides.serverApiKey = srvKey;
+  if (args.includes('--json')) overrides.output = 'json';
+  return overrides;
+}
+
+/**
+ * Write a starter .tdd-audit.json to destPath (default: cwd/.tdd-audit.json).
+ * Returns the path written, or throws if the file already exists and force is false.
+ *
+ * @param {string}  [destPath]
+ * @param {boolean} [force=false]
+ * @returns {string}
+ */
+function writeInitConfig(destPath, force = false) {
+  const target = destPath || path.join(process.cwd(), CONFIG_FILE);
+  if (fs.existsSync(target) && !force) {
+    throw new Error(`${target} already exists. Pass --force to overwrite.`);
+  }
+  fs.writeFileSync(target, JSON.stringify(INIT_TEMPLATE, null, 2) + '\n', 'utf8');
+  return target;
+}
+
+module.exports = { loadConfig, parseCliOverrides, writeInitConfig, DEFAULTS, INIT_TEMPLATE, CONFIG_FILE };

package/lib/github.js

@@ -0,0 +1,93 @@
+'use strict';
+
+// ─── GitHub REST helpers ──────────────────────────────────────────────────────
+
+async function ghFetch(path, token, method = 'GET', body = null) {
+  const opts = {
+    method,
+    headers: {
+      'Accept':        'application/vnd.github+json',
+      'Authorization': `Bearer ${token}`,
+      'X-GitHub-Api-Version': '2022-11-28',
+      'Content-Type':  'application/json',
+    },
+  };
+  if (body) opts.body = JSON.stringify(body);
+  const res = await fetch(`https://api.github.com${path}`, opts);
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`GitHub API ${method} ${path} → ${res.status}: ${text.slice(0, 200)}`);
+  }
+  return res.status === 204 ? null : res.json();
+}
+
+// ─── SARIF upload ─────────────────────────────────────────────────────────────
+
+/**
+ * Upload a SARIF report to GitHub code scanning.
+ * Findings will appear inline in PRs and the Security tab.
+ *
+ * @param {object} opts
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {string} opts.token   - GitHub token with `security_events` write scope
+ * @param {string} opts.ref     - full git ref, e.g. "refs/heads/main"
+ * @param {string} opts.commitSha
+ * @param {object} opts.sarif   - SARIF 2.1.0 object from toSarif()
+ * @returns {Promise<object>}
+ */
+async function uploadSarif({ owner, repo, token, ref, commitSha, sarif }) {
+  const encoded = Buffer.from(JSON.stringify(sarif)).toString('base64');
+  return ghFetch(`/repos/${owner}/${repo}/code-scanning/sarifs`, token, 'POST', {
+    ref,
+    commit_sha: commitSha,
+    sarif:      encoded,
+    tool_name:  '@lhi/tdd-audit',
+  });
+}
+
+// ─── PR review comments ───────────────────────────────────────────────────────
+
+/**
+ * Post inline review comments on a pull request for each finding.
+ * CRITICAL and HIGH findings request changes; others leave comments only.
+ *
+ * @param {object} opts
+ * @param {string} opts.owner
+ * @param {string} opts.repo
+ * @param {number} opts.pull_number
+ * @param {string} opts.token
+ * @param {string} opts.commitSha  - head SHA of the PR
+ * @param {Array}  opts.findings
+ * @returns {Promise<object>} - GitHub review object
+ */
+async function postReviewComments({ owner, repo, pull_number, token, commitSha, findings }) {
+  const real = findings.filter(f => !f.likelyFalsePositive);
+  if (!real.length) return null;
+
+  const hasCritical = real.some(f => f.severity === 'CRITICAL' || f.severity === 'HIGH');
+
+  const comments = real.map(f => ({
+    path:     f.file,
+    line:     f.line,
+    side:     'RIGHT',
+    body:     `**[${f.severity}] ${f.name}**\n\`\`\`\n${f.snippet}\n\`\`\`\nRun \`/tdd-audit\` to remediate.`,
+  }));
+
+  return ghFetch(`/repos/${owner}/${repo}/pulls/${pull_number}/reviews`, token, 'POST', {
+    commit_id: commitSha,
+    body:      `**@lhi/tdd-audit** found ${real.length} issue(s). ${hasCritical ? 'CRITICAL/HIGH findings require changes.' : 'See inline comments.'}`,
+    event:     hasCritical ? 'REQUEST_CHANGES' : 'COMMENT',
+    comments,
+  });
+}
+
+// ─── Parse "owner/repo" helper ────────────────────────────────────────────────
+
+function parseRepo(repoStr) {
+  const [owner, repo] = (repoStr || '').split('/');
+  if (!owner || !repo) throw new Error('--repo must be in "owner/repo" format');
+  return { owner, repo };
+}
+
+module.exports = { uploadSarif, postReviewComments, parseRepo };

package/lib/remediator.js

@@ -0,0 +1,181 @@
+'use strict';
+
+// ─── Provider endpoints ───────────────────────────────────────────────────────
+
+const PROVIDERS = {
+  anthropic: {
+    url:     'https://api.anthropic.com/v1/messages',
+    headers: (apiKey) => ({
+      'Content-Type':      'application/json',
+      'x-api-key':         apiKey,
+      'anthropic-version': '2023-06-01',
+    }),
+    body: (model, prompt) => ({
+      model:      model || 'claude-opus-4-6',
+      max_tokens: 8192,
+      messages:   [{ role: 'user', content: prompt }],
+    }),
+    extract: (data) => data?.content?.[0]?.text || '',
+  },
+  openai: {
+    url:          'https://api.openai.com/v1/chat/completions',
+    openaiCompat: true,  // supports --base-url override for compatible APIs
+    headers: (apiKey) => ({
+      'Content-Type':  'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    }),
+    body: (model, prompt) => ({
+      model:    model || 'gpt-4o',
+      messages: [{ role: 'user', content: prompt }],
+    }),
+    extract: (data) => data?.choices?.[0]?.message?.content || '',
+  },
+  gemini: {
+    url:     'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent',
+    headers: (apiKey) => ({ 'Content-Type': 'application/json', 'x-goog-api-key': apiKey }),
+    body: (model, prompt) => ({
+      contents: [{ parts: [{ text: prompt }] }],
+    }),
+    extract: (data) => data?.candidates?.[0]?.content?.parts?.[0]?.text || '',
+  },
+  ollama: {
+    url:     'http://localhost:11434/api/generate',
+    headers: () => ({ 'Content-Type': 'application/json' }),
+    body: (model, prompt) => ({
+      model:  model || 'llama3',
+      prompt,
+      stream: false,
+    }),
+    extract: (data) => data?.response || '',
+  },
+};
+
+// ─── Prompt builder ───────────────────────────────────────────────────────────
+
+const MAX_SNIPPET_CHARS = 500;
+
+/**
+ * Sanitize a raw code snippet before embedding it in an AI prompt.
+ * Strips null bytes, limits length, and trims whitespace so that
+ * injected newlines cannot introduce new top-level instruction lines.
+ */
+function sanitizeSnippet(raw) {
+  if (typeof raw !== 'string') return '';
+  return raw
+    .replace(/\x00/g, '')          // strip null bytes
+    .replace(/[\r\n]+/g, ' ')      // collapse newlines → prevent line injection
+    .slice(0, MAX_SNIPPET_CHARS)
+    .trim();
+}
+
+function buildRemediationPrompt(finding) {
+  const snippet = sanitizeSnippet(finding.snippet);
+  return `You are a security engineer applying the Red-Green-Refactor TDD remediation protocol.
+
+VULNERABILITY FINDING:
+- Type: ${finding.name}
+- Severity: ${finding.severity}
+- File: ${finding.file}
+- Line: ${finding.line}
+- Code snippet: <snippet>${snippet}</snippet>
+
+TASK:
+1. Write a Jest/supertest exploit test (Red phase) that proves this vulnerability exists.
+   The test must be placed in __tests__/security/ and must FAIL before the fix.
+2. Write the minimum code patch (Green phase) that closes the vulnerability.
+   Show it as a unified diff against the original file.
+3. Confirm what regression checks to run (Refactor phase).
+
+Respond with valid JSON in exactly this shape:
+{
+  "exploitTest": {
+    "filename": "__tests__/security/<slug>.test.js",
+    "content": "<full test file content>"
+  },
+  "patch": {
+    "filename": "<path to file being patched>",
+    "diff": "<unified diff>"
+  },
+  "refactorChecks": ["<check 1>", "<check 2>"]
+}`;
+}
+
+// ─── HTTP call ────────────────────────────────────────────────────────────────
+
+/**
+ * @param {string}  provider  - 'anthropic' | 'openai' | 'gemini' | 'ollama'
+ * @param {string}  apiKey
+ * @param {string}  model
+ * @param {string}  prompt
+ * @param {string}  [baseUrl] - override base URL for OpenAI-compatible providers
+ *                              e.g. 'https://api.groq.com/openai/v1'
+ *                                   'https://openrouter.ai/api/v1'
+ *                                   'https://api.together.xyz/v1'
+ */
+async function callProvider(provider, apiKey, model, prompt, baseUrl) {
+  const p = PROVIDERS[provider];
+  if (!p) throw new Error(`Unknown provider "${provider}". Supported: ${Object.keys(PROVIDERS).join(', ')}`);
+
+  let url = typeof p.url === 'function' ? p.url(apiKey) : p.url;
+  if (baseUrl && p.openaiCompat) {
+    // Any OpenAI-compatible service: strip trailing slash and append path
+    url = baseUrl.replace(/\/+$/, '') + '/chat/completions';
+  }
+  const headers = p.headers(apiKey);
+  const body    = JSON.stringify(p.body(model, prompt));
+
+  const res = await fetch(url, { method: 'POST', headers, body });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Provider ${provider} returned ${res.status}: ${text.slice(0, 200)}`);
+  }
+  const data = await res.json();
+  return p.extract(data);
+}
+
+// ─── Parse model response ─────────────────────────────────────────────────────
+
+function parseResponse(text) {
+  // Extract JSON from response (model may wrap it in markdown)
+  const match = text.match(/\{[\s\S]*\}/);
+  if (!match) throw new Error('Model response did not contain a JSON object');
+  return JSON.parse(match[0]);
+}
+
+// ─── Main remediate function ──────────────────────────────────────────────────
+
+/**
+ * Run AI-powered remediation for a list of findings.
+ *
+ * @param {object} opts
+ * @param {Array}  opts.findings  - finding objects from quickScan
+ * @param {string} opts.provider  - 'anthropic' | 'openai' | 'gemini' | 'ollama'
+ * @param {string} opts.apiKey
+ * @param {string} [opts.model]
+ * @param {string} [opts.baseUrl]  - override base URL for OpenAI-compatible providers
+ * @param {string} [opts.severity] - minimum severity to fix ('CRITICAL','HIGH','MEDIUM','LOW')
+ * @returns {Promise<Array>} - results per finding
+ */
+async function remediate({ findings, provider, apiKey, model, baseUrl, severity = 'LOW' }) {
+  const ORDER = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
+  const threshold = ORDER[severity.toUpperCase()] ?? 3;
+
+  const targets = findings
+    .filter(f => !f.likelyFalsePositive && (ORDER[f.severity] ?? 99) <= threshold)
+    .sort((a, b) => (ORDER[a.severity] ?? 99) - (ORDER[b.severity] ?? 99));
+
+  const results = [];
+  for (const finding of targets) {
+    try {
+      const prompt   = buildRemediationPrompt(finding);
+      const raw      = await callProvider(provider, apiKey, model, prompt, baseUrl);
+      const parsed   = parseResponse(raw);
+      results.push({ finding, status: 'remediated', ...parsed });
+    } catch (err) {
+      results.push({ finding, status: 'error', error: err.message });
+    }
+  }
+  return results;
+}
+
+module.exports = { remediate, callProvider, buildRemediationPrompt, PROVIDERS };

package/lib/reporter.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const { version } = require('../package.json');
+
+// ─── JSON ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Return findings as a structured JSON-serialisable object.
+ * @param {Array}    findings
+ * @param {string[]} [exempted=[]]
+ * @returns {object}
+ */
+function toJson(findings, exempted = []) {
+  const real  = findings.filter(f => !f.likelyFalsePositive);
+  const noisy = findings.filter(f =>  f.likelyFalsePositive);
+
+  const summary = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
+  for (const f of real) summary[f.severity] = (summary[f.severity] || 0) + 1;
+
+  return {
+    version,
+    summary,
+    findings: real,
+    likelyFalsePositives: noisy,
+    exempted,
+    scannedAt: new Date().toISOString(),
+  };
+}
+
+// ─── SARIF ────────────────────────────────────────────────────────────────────
+
+const SARIF_LEVEL = { CRITICAL: 'error', HIGH: 'error', MEDIUM: 'warning', LOW: 'note' };
+
+// Maps our vuln names to CWE IDs for richer GitHub annotations
+const CWE_MAP = {
+  'SQL Injection':             'CWE-89',
+  'Command Injection':         'CWE-78',
+  'Path Traversal':            'CWE-22',
+  'XSS':                       'CWE-79',
+  'IDOR':                      'CWE-639',
+  'Broken Auth':               'CWE-287',
+  'Hardcoded Secret':          'CWE-798',
+  'SSRF':                      'CWE-918',
+  'Open Redirect':             'CWE-601',
+  'NoSQL Injection':           'CWE-943',
+  'Mass Assignment':           'CWE-915',
+  'Prototype Pollution':       'CWE-1321',
+  'Weak Crypto':               'CWE-327',
+  'Insecure Deserialization':  'CWE-502',
+  'TLS Bypass':                'CWE-295',
+  'Sensitive Storage':         'CWE-312',
+  'JWT Alg None':              'CWE-347',
+  'Secret Fallback':           'CWE-798',
+  'eval() Injection':          'CWE-95',
+  'Template Injection':        'CWE-94',
+  'ReDoS':                     'CWE-1333',
+  'XXE':                       'CWE-611',
+  'CORS Wildcard':             'CWE-942',
+  'Insecure Random':           'CWE-338',
+  'Timing-Unsafe Comparison':  'CWE-208',
+};
+
+/**
+ * Return findings as a SARIF 2.1.0 object (GitHub code scanning compatible).
+ * @param {Array}  findings
+ * @param {string} [projectDir='']  - used to build relative artifact URIs
+ * @returns {object}
+ */
+function toSarif(findings, projectDir = '') {
+  const rules = [];
+  const ruleIndex = {};
+
+  const results = findings.filter(f => !f.likelyFalsePositive).map(f => {
+    if (ruleIndex[f.name] === undefined) {
+      ruleIndex[f.name] = rules.length;
+      const cwe = CWE_MAP[f.name];
+      rules.push({
+        id: f.name.replace(/\s+/g, '-').replace(/[()]/g, '').toLowerCase(),
+        name: f.name,
+        shortDescription: { text: f.name },
+        fullDescription:  { text: `${f.name} detected — severity: ${f.severity}` },
+        defaultConfiguration: { level: SARIF_LEVEL[f.severity] || 'warning' },
+        ...(cwe && { relationships: [{ target: { id: cwe, toolComponent: { name: 'CWE' } } }] }),
+        helpUri: `https://cwe.mitre.org/data/definitions/${cwe ? cwe.replace('CWE-', '') : '0'}.html`,
+      });
+    }
+
+    return {
+      ruleId:    rules[ruleIndex[f.name]].id,
+      ruleIndex: ruleIndex[f.name],
+      level:     SARIF_LEVEL[f.severity] || 'warning',
+      message:   { text: f.snippet || f.name },
+      locations: [{
+        physicalLocation: {
+          artifactLocation: {
+            uri:       f.file.replace(/\\/g, '/'),
+            uriBaseId: '%SRCROOT%',
+          },
+          region: { startLine: f.line },
+        },
+      }],
+    };
+  });
+
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name:            '@lhi/tdd-audit',
+          version,
+          informationUri:  'https://www.npmjs.com/package/@lhi/tdd-audit',
+          rules,
+        },
+      },
+      results,
+    }],
+  };
+}
+
+// ─── Text (existing printFindings extracted for reuse) ────────────────────────
+
+/**
+ * Return a human-readable text report string (without printing it).
+ * @param {Array}    findings
+ * @param {string[]} [exempted=[]]
+ * @returns {string}
+ */
+function toText(findings, exempted = []) {
+  const lines = [];
+  if (findings.length === 0) {
+    lines.push('   ✅ No obvious vulnerability patterns detected.\n');
+  } else {
+    const real  = findings.filter(f => !f.likelyFalsePositive);
+    const noisy = findings.filter(f =>  f.likelyFalsePositive);
+    const bySeverity = { CRITICAL: [], HIGH: [], MEDIUM: [], LOW: [] };
+    for (const f of real) (bySeverity[f.severity] || bySeverity.LOW).push(f);
+    const icons = { CRITICAL: '🔴', HIGH: '🟠', MEDIUM: '🟡', LOW: '🔵' };
+
+    lines.push(`\n   Found ${real.length} potential issue(s)${noisy.length ? ` (+${noisy.length} in test files — see below)` : ''}:\n`);
+    for (const [sev, list] of Object.entries(bySeverity)) {
+      if (!list.length) continue;
+      for (const f of list) {
+        const badge = f.inTestFile ? ' [test file]' : '';
+        lines.push(`   ${icons[sev]} [${sev}] ${f.name} — ${f.file}:${f.line}${badge}`);
+        lines.push(`         ${f.snippet}`);
+      }
+    }
+    if (noisy.length) {
+      lines.push('\n   ⚪ Likely intentional (in test files — verify manually):');
+      for (const f of noisy) lines.push(`      ${f.name} — ${f.file}:${f.line}`);
+    }
+    lines.push('\n   Run /tdd-audit in your agent to remediate.\n');
+  }
+  if (exempted.length) {
+    lines.push('   ⚠️  Files skipped via audit_status:safe (verify these exemptions are intentional):');
+    for (const p of exempted) lines.push(`      ${p}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+module.exports = { toJson, toSarif, toText };