@lhi/tdd-audit 1.5.0 → 1.8.1

package/README.md

@@ -1,12 +1,12 @@
 # @lhi/tdd-audit
 
-Security skill installer for **Claude Code, Gemini CLI, Cursor, Codex, and OpenCode**. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol — you prove the hole exists, apply the fix, and prove it's closed.
+> **v1.8.0** — Security skill installer for **Claude Code, Gemini CLI, Cursor, Codex, and OpenCode**. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol — you prove the hole exists, apply the fix, and prove it's closed.
 
 ## What happens on install
 
 Running the installer does five things immediately:
 
-1. **Scans your codebase** for 29 vulnerability patterns (SQL injection, IDOR, XSS, command injection, path traversal, broken auth, JWT alg:none, ReDoS, timing-unsafe comparisons, and more) and prints findings to stdout
+1. **Scans your codebase** for 34 vulnerability patterns across OWASP Top 10, mobile, agentic AI, and prompt/skill files — prints a severity-ranked findings report to stdout
 2. **Scaffolds `__tests__/security/`** with a framework-matched boilerplate exploit test
 3. **Adds `test:security`** to your `package.json` scripts (Node.js projects)
 4. **Creates `.github/workflows/security-tests.yml`** so the CI gate exists from day one
@@ -31,25 +31,25 @@ node index.js
 | Claude Code | `npx @lhi/tdd-audit --local --claude` |
 | Gemini CLI / Codex / OpenCode | `npx @lhi/tdd-audit --local` |
 | With pre-commit hook | add `--with-hooks` |
-| Scan only (no install) | `npx @lhi/tdd-audit --scan-only` |
+| Scan only (no install) | `npx @lhi/tdd-audit --scan` |
 
 ### All flags
 
 | Flag | Description |
 |---|---|
-| `--local` | Install skill files to the current project directory instead of `~` |
+| `--local` | Install skill files into the current project instead of `~` |
 | `--claude` | Use `.claude/` instead of `.agents/` as the skill directory |
 | `--with-hooks` | Install a pre-commit hook that blocks commits if security tests fail |
 | `--skip-scan` | Skip the automatic vulnerability scan on install |
-| `--scan-only` | Run the vulnerability scan without installing anything |
+| `--scan` / `--scan-only` | Run the vulnerability scan without installing anything |
 
-### Framework Detection
+### Framework detection
 
 The installer automatically detects your project's test framework and scaffolds the right boilerplate:
 
 | Detected | Boilerplate | `test:security` command |
 |---|---|---|
-| `jest` / `supertest` | `sample.exploit.test.js` | `jest --testPathPattern=__tests__/security` |
+| `jest` / `supertest` | `sample.exploit.test.js` | `jest --testPathPatterns=__tests__/security` |
 | `vitest` | `sample.exploit.test.vitest.js` | `vitest run __tests__/security` |
 | `mocha` | `sample.exploit.test.js` | `mocha '__tests__/security/**/*.spec.js'` |
 | `pytest.ini` / `pyproject.toml` | `sample.exploit.test.pytest.py` | `pytest tests/security/ -v` |
@@ -65,33 +65,46 @@ Once installed, trigger the autonomous audit in your agent:
 ```
 
 The agent will:
-1. Scan the codebase and present a severity-ranked findings report (CRITICAL / HIGH / MEDIUM / LOW)
-2. Wait for your confirmation before making any changes
-3. For each confirmed vulnerability, apply the full Red-Green-Refactor loop:
+
+1. Detect your tech stack and scope the scan to relevant patterns only
+2. Scan the codebase and present a severity-ranked findings report (CRITICAL / HIGH / MEDIUM / LOW)
+3. **Wait for your confirmation** before making any changes
+4. For each confirmed vulnerability, apply the full Red-Green-Refactor loop:
    - **Red** — write an exploit test that fails, proving the vulnerability exists
    - **Green** — apply the targeted patch, making the test pass
    - **Refactor** — run the full suite to confirm no regressions
-4. Deliver a final Remediation Summary table
+5. Apply proactive hardening controls (security headers, rate limiting, `npm audit`, secret history scan)
+6. Deliver a final Remediation Summary table
 
 The agent works one vulnerability at a time and does not advance until the current one is fully proven closed.
 
-## Vulnerability Scanner
+Pass `--scan` in your prompt to get the Audit Report only, without any code changes.
+
+## Vulnerability scanner
 
-The built-in scanner catches 29 patterns across OWASP Top 10 + mobile + agentic AI stacks:
+The built-in scanner catches **34 patterns** across OWASP Top 10, mobile, agentic AI, and prompt/skill files:
 
 | Category | Patterns |
 |---|---|
-| Injection | SQL Injection, Command Injection, NoSQL Injection, Template Injection, LDAP |
-| Broken Auth | JWT alg:none, Broken Auth, Timing-Unsafe Comparison, Hardcoded Secret, Secret Fallback |
+| Injection | SQL Injection, Command Injection, NoSQL Injection, Template Injection |
+| Broken Auth | JWT Alg None, Broken Auth, Timing-Unsafe Comparison, Hardcoded Secret, Secret Fallback |
 | XSS / Output | XSS, eval() Injection, Open Redirect |
 | Crypto | Weak Crypto (MD5/SHA1), Insecure Random, TLS Bypass |
 | Server-side | SSRF, Path Traversal, XXE, Insecure Deserialization |
 | Assignment | Mass Assignment, Prototype Pollution |
 | Mobile | Sensitive Storage, WebView JS Bridge, Deep Link Injection, Android Debuggable |
-| Config | CORS Wildcard, Cleartext Traffic, Config Secrets |
-| New (v1.5) | JWT Alg None, Timing-Unsafe Comparison, ReDoS |
+| Config / Infra | CORS Wildcard, Cleartext Traffic, Config Secrets, ReDoS |
+| Agentic / Prompt | Deprecated CSRF Package (`csurf`), Unpinned npx MCP Server, Cleartext URL in Prompt |
+
+### Scanner behaviour
 
-## Running security tests manually
+- **Test files are flagged but labelled** — findings in `__tests__/`, `tests/`, `spec/`, or `*.test.*` files are shown with a `[test file]` badge. Patterns that mark `skipInTests: true` (e.g. Hardcoded Secret, Sensitive Log, Cleartext Traffic) are further tagged `likelyFalsePositive` and separated at the bottom of the report.
+- **Prompt/skill files get their own scan** — `.md` files inside `prompts/`, `skills/`, `.claude/`, `workflows/`, plus `CLAUDE.md` and `SKILL.md`, are scanned for prompt-specific anti-patterns. Matches inside backtick code spans are suppressed to avoid noise from documentation examples.
+- **`audit_status: safe` exemption** — any prompt file with `audit_status: safe` in its YAML frontmatter is skipped and listed separately so you can verify exemptions are intentional.
+- **Binary and oversized files skipped** — files larger than 512 KB or containing null bytes are skipped to prevent OOM.
+- **Symlinks skipped** — symlinks are never followed, preventing directory-escape on M-series Macs and shared filesystems.
+
+## Running security tests
 
 ```bash
 # Node.js
@@ -102,20 +115,30 @@ pytest tests/security/ -v
 
 # Go
 go test ./security/... -v
+
+# Flutter
+flutter test test/security/
 ```
 
 ## CI/CD
 
-The installer creates `.github/workflows/security-tests.yml` for your stack. It runs on every pull request targeting `main` — any exploit test that regresses will block the merge.
+The installer creates framework-matched workflow files under `.github/workflows/`. Both `security-tests.yml` and `ci.yml` include:
+
+- SHA-pinned `uses:` references on every action (supply chain hardening)
+- `npm audit --audit-level=high` (or equivalent) to catch vulnerable dependencies
+- The security exploit test suite on every push and pull request
 
-To add this gate to an existing CI pipeline manually:
+To add the security gate to an existing pipeline manually:
 
 ```yaml
+- name: Dependency audit
+  run: npm audit --audit-level=high
+
 - name: Run security exploit tests
-  run: npm run test:security   # or pytest tests/security/, or go test ./security/...
+  run: npm run test:security   # or pytest tests/security/, flutter test test/security/
 ```
 
-## Pre-commit Hook
+## Pre-commit hook
 
 The `--with-hooks` flag appends a security gate to `.git/hooks/pre-commit`. Commits are blocked if any exploit test fails:
 
@@ -123,7 +146,37 @@ The `--with-hooks` flag appends a security gate to `.git/hooks/pre-commit`. Comm
 ❌ Security tests failed. Commit blocked.
 ```
 
-The hook is non-destructive — it appends to any existing hook content rather than overwriting it.
+The hook is non-destructive — it appends to existing hook content rather than overwriting it.
+
+## Agentic AI security (ASI01–ASI10)
+
+When the project contains AI agent code, MCP configurations, or `CLAUDE.md` files, the scanner also checks for agentic-specific vulnerabilities:
+
+| ID | Vulnerability | Risk |
+|---|---|---|
+| ASI01 | Prompt injection via tool output | Malicious content in web/file reads hijacks agent behaviour |
+| ASI02 | CLAUDE.md / instructions file injection | Attacker-controlled system prompts override agent identity |
+| ASI03 | MCP server supply chain (unpinned `npx`) | Compromised package version exfiltrates secrets |
+| ASI04 | Excessive tool permissions | Agent can write files or run shell when only read is needed |
+| ASI05 | Secrets in tool call arguments | Tokens/passwords logged by external tools |
+| ASI06 | Unvalidated agent action execution | Agent runs irreversible actions without user confirmation |
+| ASI07 | Insecure direct agent communication | Sub-agent messages trusted without verification |
+| ASI08 | GitHub Actions command injection | `github.event.*` interpolated directly into `run:` steps |
+| ASI09 | Unpinned GitHub Actions (supply chain) | Mutable `@v4` / `@main` tags can be hijacked |
+| ASI10 | Secrets in workflow environment | Secrets printed to logs or embedded in curl URLs |
+
+See [`docs/agentic-ai-security.md`](docs/agentic-ai-security.md) for grep patterns, examples, and fixes.
+
+## Documentation
+
+| File | Contents |
+|---|---|
+| [`docs/scanner.md`](docs/scanner.md) | How the scanner works — architecture, detection logic, false-positive handling |
+| [`docs/vulnerability-patterns.md`](docs/vulnerability-patterns.md) | All 34 patterns with descriptions, grep signatures, and fix pointers |
+| [`docs/tdd-protocol.md`](docs/tdd-protocol.md) | The Red-Green-Refactor protocol in full, with framework templates |
+| [`docs/agentic-ai-security.md`](docs/agentic-ai-security.md) | ASI01–ASI10 agentic AI vulnerability reference |
+| [`docs/hardening.md`](docs/hardening.md) | Phase 4 proactive hardening controls |
+| [`docs/ci-cd.md`](docs/ci-cd.md) | CI/CD integration guide for all supported stacks |
 
 ## License
 

package/SKILL.md

@@ -53,7 +53,7 @@ jobs:
   security-tests:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - name: Install dependencies
         run: npm ci
       - name: Run Security Exploit Tests

package/lib/scanner.js

@@ -45,6 +45,9 @@ const VULN_PATTERNS = [
 ];
 
 const SCAN_EXTENSIONS = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.py', '.go', '.dart']);
+
+/** Maximum file size to read before skipping (512 KB). Prevents OOM on large generated files. */
+const MAX_SCAN_FILE_BYTES = 512 * 1024;
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', '__pycache__', 'venv', '.venv', 'vendor', '.expo', '.dart_tool', '.pub-cache']);
 
 // ─── Prompt / Skill Patterns ──────────────────────────────────────────────────
@@ -214,14 +217,22 @@ function hasSafeAuditStatus(lines) {
 }
 
 /**
- * Returns true if the match at matchIndex falls inside a backtick code span.
- * Used to suppress PROMPT_PATTERN hits on pattern-documentation table rows.
+ * Returns true if the match at matchIndex falls inside a *closed* backtick
+ * code span on the same line.  A code span is closed only when there is an
+ * odd number of backticks before the match AND at least one closing backtick
+ * after it on the same line.  A lone, unmatched backtick before the pattern
+ * does NOT constitute a code span and must NOT suppress the finding.
  * @param {string} line
  * @param {number} matchIndex - character index of the match start
  */
 function isInsideBackticks(line, matchIndex) {
   const before = line.slice(0, matchIndex);
-  return (before.match(/`/g) || []).length % 2 === 1;
+  const after  = line.slice(matchIndex);
+  const backticksBefore = (before.match(/`/g) || []).length;
+  const backticksAfter  = (after.match(/`/g)  || []).length;
+  // Suppress only when the span is properly closed: odd opening count + at
+  // least one closing backtick exists after the match position.
+  return backticksBefore % 2 === 1 && backticksAfter >= 1;
 }
 
 /**
@@ -234,16 +245,32 @@ function isCommentLine(line) {
 
 /**
  * Scan all prompt/skill .md files in projectDir for prompt-specific patterns.
+ *
+ * Returns a findings array with a non-enumerable `.exempted` property — an
+ * array of relative paths for files skipped via `audit_status: safe`.  Using
+ * a non-enumerable property preserves full backward compatibility: spread,
+ * toEqual([]), and quickScan's `...scanPromptFiles()` all continue to work.
+ *
  * @param {string} projectDir - project root
- * @returns {Array} findings
+ * @returns {Array} findings  (with non-enumerable .exempted: string[])
  */
 function scanPromptFiles(projectDir) {
   const findings = [];
+  const exempted = [];
   for (const filePath of walkMdFiles(projectDir)) {
     if (!isPromptFile(filePath, projectDir)) continue;
     let lines;
-    try { lines = fs.readFileSync(filePath, 'utf8').split('\n'); } catch { continue; }
-    if (hasSafeAuditStatus(lines)) continue;
+    try {
+      // SEC-06: read first, then check length — eliminates statSync/readFileSync TOCTOU race.
+      const content = fs.readFileSync(filePath, 'utf8');
+      if (content.length > MAX_SCAN_FILE_BYTES) continue;
+      if (content.includes('\0')) continue; // skip binary files (mirrors quickScan guard)
+      lines = content.split('\n');
+    } catch { continue; }
+    if (hasSafeAuditStatus(lines)) {
+      exempted.push(path.relative(projectDir, filePath));
+      continue;
+    }
     for (let i = 0; i < lines.length; i++) {
       for (const p of PROMPT_PATTERNS) {
         const match = p.pattern.exec(lines[i]);
@@ -262,6 +289,8 @@ function scanPromptFiles(projectDir) {
       }
     }
   }
+  // Attach exempted as non-enumerable so spread / toEqual([]) are unaffected.
+  Object.defineProperty(findings, 'exempted', { value: exempted, enumerable: false, configurable: true });
   return findings;
 }
 
@@ -339,8 +368,10 @@ function quickScan(projectDir) {
     const inTest = isTestFile(filePath, projectDir);
     let content;
     // L1 fix: guard against binary / non-UTF-8 files
+    // SEC-06: read first, then check length — eliminates statSync/readFileSync TOCTOU race.
     try {
       content = fs.readFileSync(filePath, 'utf8');
+      if (content.length > MAX_SCAN_FILE_BYTES) continue;
     } catch {
       continue;
     }
@@ -372,38 +403,47 @@ function quickScan(projectDir) {
 
 /**
  * Print a human-readable findings report to stdout.
- * @param {Array} findings
+ * @param {Array}    findings - array of finding objects
+ * @param {string[]} [exempted=[]] - relative paths of files skipped via audit_status:safe
  */
-function printFindings(findings) {
+function printFindings(findings, exempted = []) {
   if (findings.length === 0) {
     console.log('   ✅ No obvious vulnerability patterns detected.\n');
-    return;
-  }
-  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: '🔵' };
-
-  console.log(`\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 testBadge = f.inTestFile ? ' [test file]' : '';
-      console.log(`   ${icons[sev]} [${sev}] ${f.name} — ${f.file}:${f.line}${testBadge}`);
-      console.log(`         ${f.snippet}`);
+  } 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: '🔵' };
+
+    console.log(`\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 testBadge = f.inTestFile ? ' [test file]' : '';
+        console.log(`   ${icons[sev]} [${sev}] ${f.name} — ${f.file}:${f.line}${testBadge}`);
+        console.log(`         ${f.snippet}`);
+      }
     }
-  }
 
-  if (noisy.length) {
-    console.log('\n   ⚪ Likely intentional (in test files — verify manually):');
-    for (const f of noisy) {
-      console.log(`      ${f.name} — ${f.file}:${f.line}`);
+    if (noisy.length) {
+      console.log('\n   ⚪ Likely intentional (in test files — verify manually):');
+      for (const f of noisy) {
+        console.log(`      ${f.name} — ${f.file}:${f.line}`);
+      }
     }
+
+    console.log('\n   Run /tdd-audit in your agent to remediate.\n');
   }
 
-  console.log('\n   Run /tdd-audit in your agent to remediate.\n');
+  if (exempted.length) {
+    console.log('   ⚠️  Files skipped via audit_status:safe (verify these exemptions are intentional):');
+    for (const p of exempted) {
+      console.log(`      ${p}`);
+    }
+    console.log('');
+  }
 }
 
 module.exports = {
@@ -411,6 +451,7 @@ module.exports = {
   PROMPT_PATTERNS,
   SCAN_EXTENSIONS,
   SKIP_DIRS,
+  MAX_SCAN_FILE_BYTES,
   detectFramework,
   detectAppFramework,
   detectTestBaseDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lhi/tdd-audit",
-  "version": "1.5.0",
+  "version": "1.8.1",
   "description": "Security skill installer for Claude Code, Gemini CLI, Cursor, Codex, and OpenCode. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol.",
   "main": "index.js",
   "bin": {

package/workflows/tdd-audit.md

@@ -1,5 +1,11 @@
 ---
 description: Run the complete TDD Remediation Autonomous Audit
+risk: low
+source: personal
+date_added: "2024-01-01"
+audited_by: lcanady
+last_audited: "2026-03-25"
+audit_status: safe
 ---
 Please use the TDD Remediation Protocol Auto-Audit skill (located in the `skills/tdd-remediation` folder) to secure this repository.