@lhi/tdd-audit 1.5.0 → 1.8.2

package/docs/hardening.md

@@ -0,0 +1,267 @@
+# Phase 4 — Proactive Hardening
+
+Phase 4 runs after all known vulnerabilities are patched. It applies defence-in-depth controls that make future vulnerabilities harder to introduce and easier to catch.
+
+Apply each control independently. Confirm the test suite stays green after each.
+
+---
+
+## 4a. Security headers (Helmet)
+
+```bash
+npm install helmet
+```
+
+Apply as the **first** middleware, before any routes:
+
+```javascript
+const helmet = require('helmet');
+app.use(helmet());
+```
+
+For **Next.js**, add to `next.config.js`:
+
+```javascript
+const securityHeaders = [
+  { key: 'X-Content-Type-Options',    value: 'nosniff' },
+  { key: 'X-Frame-Options',           value: 'SAMEORIGIN' },
+  { key: 'X-XSS-Protection',          value: '1; mode=block' },
+  { key: 'Referrer-Policy',           value: 'strict-origin-when-cross-origin' },
+  { key: 'Permissions-Policy',        value: 'camera=(), microphone=(), geolocation=()' },
+  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
+];
+
+module.exports = {
+  async headers() {
+    return [{ source: '/(.*)', headers: securityHeaders }];
+  },
+};
+```
+
+**Verify:** `curl -I https://localhost:3000/` — confirm headers are present.
+
+---
+
+## 4b. Content Security Policy (CSP)
+
+```javascript
+app.use(
+  helmet.contentSecurityPolicy({
+    directives: {
+      defaultSrc:             ["'self'"],
+      scriptSrc:              ["'self'"],       // no 'unsafe-inline' — use nonces
+      styleSrc:               ["'self'", "'unsafe-inline'"],
+      imgSrc:                 ["'self'", 'data:', 'https:'],
+      connectSrc:             ["'self'"],
+      fontSrc:                ["'self'"],
+      objectSrc:              ["'none'"],
+      frameAncestors:         ["'none'"],       // equivalent to X-Frame-Options: DENY
+      upgradeInsecureRequests: [],
+    },
+  })
+);
+```
+
+Validate your policy at `https://csp-evaluator.withgoogle.com/`.
+
+---
+
+## 4c. CSRF protection
+
+For cookie-based sessions (not pure JWT / Authorization header flows):
+
+```javascript
+// csrf-csrf (csurf is deprecated since March 2023)
+const { doubleCsrf } = require('csrf-csrf');
+
+const { generateToken, doubleCsrfProtection } = doubleCsrf({
+  getSecret:     () => process.env.CSRF_SECRET,
+  cookieName:    '__Host-psifi.x-csrf-token',
+  cookieOptions: { sameSite: 'strict', secure: true },
+});
+
+app.use(doubleCsrfProtection);
+app.get('/form', (req, res) => res.render('form', { csrfToken: generateToken(req, res) }));
+```
+
+For SPAs using `fetch`, set `SameSite=Strict` on the session cookie:
+
+```javascript
+res.cookie('session', token, { httpOnly: true, secure: true, sameSite: 'strict' });
+```
+
+---
+
+## 4d. Rate limiting
+
+| Route type | Recommended limit |
+|---|---|
+| `/login`, `/register`, `/forgot-password` | 10 requests / 15 min / IP |
+| `/api/` general endpoints | 100 requests / 1 min / IP |
+| File upload endpoints | 5 requests / 1 min / IP |
+| Password reset confirmation | 5 requests / 15 min / IP |
+
+```javascript
+const rateLimit = require('express-rate-limit');
+
+const authLimiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 10 });
+const apiLimiter  = rateLimit({ windowMs: 60 * 1000,      max: 100 });
+
+app.use('/api/', apiLimiter);
+app.post('/api/auth/login',    authLimiter, loginHandler);
+app.post('/api/auth/register', authLimiter, registerHandler);
+```
+
+Quick grep to find unprotected POST routes:
+
+```bash
+grep -rn "app\.post\|router\.post" src/ --include="*.js" | grep -v "limiter\|rateLimit"
+```
+
+---
+
+## 4e. Dependency vulnerability audit
+
+```bash
+# Node.js
+npm audit --audit-level=high
+npm audit fix   # auto-fix where safe
+
+# Python
+pip install pip-audit && pip-audit
+
+# Go
+go install golang.org/x/vuln/cmd/govulncheck@latest && govulncheck ./...
+
+# Flutter / Dart
+flutter pub outdated
+```
+
+The live `ci.yml` and `security-tests.yml` workflows both run `npm audit --audit-level=high` on every push and pull request (added in v1.8.0).
+
+---
+
+## 4f. Secret history scan
+
+```bash
+# trufflehog (recommended)
+npx trufflehog git file://. --only-verified
+
+# gitleaks
+brew install gitleaks
+gitleaks detect --source . -v
+```
+
+If secrets are found in history:
+1. Rotate the secret immediately — treat it as compromised
+2. Use `git filter-repo` to rewrite history
+3. Force-push and have all team members re-clone
+
+Prevent future secret commits via pre-commit hook:
+
+```bash
+npx gitleaks protect --staged -v
+# or use: npx @lhi/tdd-audit --with-hooks
+```
+
+---
+
+## 4g. Production error handling
+
+```javascript
+// Express — place last, after all routes
+app.use((err, req, res, next) => {
+  const isDev = process.env.NODE_ENV !== 'production';
+  console.error(err);  // log internally — never expose to client
+  res.status(err.status || 500).json({
+    error: isDev ? err.message : 'Internal server error',
+    ...(isDev && { stack: err.stack }),
+  });
+});
+```
+
+```python
+# FastAPI
+@app.exception_handler(Exception)
+async def generic_exception_handler(request, exc):
+    logger.error(f"Unhandled exception: {exc}", exc_info=True)
+    return JSONResponse(status_code=500, content={"error": "Internal server error"})
+```
+
+---
+
+## 4h. Subresource Integrity (SRI)
+
+For third-party scripts or stylesheets loaded via CDN:
+
+```html
+<script
+  src="https://cdn.example.com/lib.min.js"
+  integrity="sha384-<hash>"
+  crossorigin="anonymous"
+></script>
+```
+
+Generate integrity hashes at `https://www.srihash.org/`.
+
+---
+
+## 4i. GitHub Actions supply chain hardening
+
+Pin every `uses:` to a full commit SHA:
+
+```yaml
+# Vulnerable — mutable tag
+- uses: actions/checkout@v4
+
+# Safe — SHA-locked, tag as comment
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+```
+
+Grep for unpinned actions:
+
+```bash
+grep -rn "uses:.*@v\|uses:.*@main\|uses:.*@master" .github/workflows/
+```
+
+Workflow inputs that inject into `run:` steps:
+
+```yaml
+# Vulnerable
+run: echo "${{ github.event.pull_request.title }}"
+
+# Safe
+env:
+  PR_TITLE: ${{ github.event.pull_request.title }}
+run: echo "$PR_TITLE"
+```
+
+---
+
+## 4j. Agentic AI controls
+
+- `CLAUDE.md` under version control; reviewed on every commit; no user-supplied content
+- MCP servers pinned to exact versions or local installs (see [ASI03](agentic-ai-security.md#asi03--mcp-server-supply-chain-risk))
+- Agent tool permissions scoped to minimum required; no `bash` when only `read` is needed
+- Tool outputs sanitized before injecting into prompt context (see [ASI01](agentic-ai-security.md#asi01--prompt-injection-via-tool-output))
+
+---
+
+## Hardening verification checklist
+
+- [ ] `helmet()` applied before all routes; `X-Content-Type-Options: nosniff` in every response
+- [ ] CSP header present; validated with csp-evaluator
+- [ ] CSRF protection on all state-mutating routes (or `SameSite=Strict` cookies)
+- [ ] Rate limiting on auth routes — 429 returned after threshold
+- [ ] `npm audit` / `pip-audit` / `govulncheck` shows 0 HIGH/CRITICAL findings
+- [ ] `gitleaks` / `trufflehog` shows no verified secrets in history
+- [ ] Production error handler returns generic messages; no stack traces in 5xx responses
+- [ ] SRI hashes on all third-party CDN resources
+- [ ] `*.env` in `.gitignore`; no `.env` committed to git
+- [ ] All cookies: `httpOnly: true`, `secure: true`, `sameSite: 'strict'` or `'lax'`
+- [ ] All GitHub Actions `uses:` pinned to full commit SHAs
+- [ ] No `github.event.*` interpolated directly into `run:` steps
+- [ ] No secrets inline in workflow `run:` commands or URLs
+- [ ] `CLAUDE.md` in version control and reviewed; no user-supplied content
+- [ ] MCP servers pinned to exact versions or local installs
+- [ ] Agent tool permissions scoped to minimum required

package/docs/scanner.md

@@ -0,0 +1,161 @@
+# Scanner Architecture
+
+`lib/scanner.js` is the core engine behind `npx @lhi/tdd-audit --scan` and the auto-audit skill. It is a pure Node.js module with no runtime dependencies — only `fs` and `path`.
+
+---
+
+## Entry points
+
+| Export | Purpose |
+|---|---|
+| `quickScan(projectDir)` | Walk all source files and return a findings array |
+| `scanPromptFiles(projectDir)` | Walk all `.md` prompt/skill files and check for prompt-specific patterns |
+| `scanAppConfig(projectDir)` | Check `app.json` / `app.config.*` for embedded secrets |
+| `scanAndroidManifest(projectDir)` | Check `AndroidManifest.xml` for `android:debuggable="true"` |
+| `printFindings(findings, exempted)` | Format and print a findings report to stdout |
+| `detectFramework(dir)` | Detect the test framework (`jest`, `vitest`, `mocha`, `pytest`, `go`, `flutter`) |
+| `detectAppFramework(dir)` | Detect the UI framework (`nextjs`, `expo`, `react-native`, `react`, `flutter`) |
+| `detectTestBaseDir(dir, framework)` | Locate the test root (`__tests__`, `tests`, `test`, `spec`) |
+
+---
+
+## How `quickScan` works
+
+```
+projectDir
+  └─ walkFiles()          — yields .js/.ts/.jsx/.tsx/.mjs/.py/.go/.dart files
+       └─ for each file:
+            1. Read file content (read-first, check length after — no TOCTOU)
+            2. Skip if content.length > 512 KB
+            3. Skip if file contains null bytes (binary guard)
+            4. For each line × each VULN_PATTERN:
+                 – If pattern matches, push finding with severity / name / file / line / snippet
+                 – inTestFile: true if path is under a test directory
+                 – likelyFalsePositive: true if inTestFile && pattern.skipInTests
+  └─ scanAppConfig()      — checks app.json / app.config.* for secret patterns
+  └─ scanAndroidManifest() — checks android:debuggable
+  └─ scanPromptFiles()    — walks .md files in prompt directories
+```
+
+All four result sets are merged into one array and returned to the caller.
+
+---
+
+## File walking
+
+### `walkFiles(dir)`
+
+Yields scannable source files (`SCAN_EXTENSIONS`). Skips:
+
+- **`SKIP_DIRS`**: `node_modules`, `.git`, `dist`, `build`, `.next`, `out`, `__pycache__`, `venv`, `.venv`, `vendor`, `.expo`, `.dart_tool`, `.pub-cache`
+- **Symlinks** — never followed, preventing escape from the project root on shared/M-series filesystems
+
+### `walkMdFiles(dir)`
+
+Same skip rules, yields `.md` files only. Used by `scanPromptFiles`.
+
+---
+
+## Scanned extensions
+
+`.js` `.ts` `.jsx` `.tsx` `.mjs` `.py` `.go` `.dart`
+
+YAML, JSON, XML, and shell files are not scanned by the code scanner. CI workflow files (`.yml`) are scanned separately when explicitly passed to the ASI08/ASI09 grep patterns during an agent-driven audit.
+
+---
+
+## Test file detection
+
+`isTestFile(filePath, projectDir)` returns `true` for any file that matches:
+
+| Pattern | Example |
+|---|---|
+| `*.test.js` / `*.spec.ts` | `auth.test.ts` |
+| `*_test.dart` | `login_test.dart` |
+| Path contains `__tests__/` or `tests/` | `__tests__/unit/scanner.test.js` |
+| Path contains `spec/` | `spec/api/users_spec.rb` |
+| Filename starts with `test_` | `test_helpers.js` |
+
+Findings in test files are always reported (they may contain real vulnerabilities), but:
+- They carry `inTestFile: true` in the finding object
+- If the matched pattern has `skipInTests: true`, `likelyFalsePositive` is set to `true` and the finding is separated into a secondary "verify manually" section of the report
+
+---
+
+## Prompt file detection
+
+`isPromptFile(filePath, projectDir)` returns `true` for:
+
+| Condition | Example |
+|---|---|
+| Filename is in `PROMPT_FILE_NAMES` | `CLAUDE.md`, `SKILL.md`, `.cursorrules`, `.clinerules` |
+| First path segment is in `PROMPT_DIRS` | `prompts/`, `skills/`, `.claude/`, `workflows/` |
+
+### `audit_status: safe` exemption
+
+If a prompt file's YAML frontmatter contains `audit_status: safe`, it is skipped entirely. The relative path is collected into an `exempted` array and displayed at the bottom of the `printFindings` report so you can verify exemptions are intentional.
+
+```markdown
+---
+name: my-prompt
+audit_status: safe
+---
+```
+
+This mechanism allows prompt authors to document intentional examples of vulnerable patterns (e.g., showing what `csurf` looks like before migration) without generating false positives on every scan.
+
+### Backtick suppression
+
+Matches inside a properly closed backtick code span on the same line are suppressed. This prevents table rows like:
+
+```markdown
+| `"command": "npx"` in MCP config | HIGH | ...
+```
+
+from triggering the `Unpinned npx MCP Server` pattern.
+
+The rule: suppress when there is an **odd** number of backticks before the match AND at least one closing backtick after it on the same line.
+
+---
+
+## Finding object schema
+
+```javascript
+{
+  severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW',
+  name: string,           // pattern display name, e.g. "SQL Injection"
+  file: string,           // relative path from projectDir
+  line: number,           // 1-indexed line number
+  snippet: string,        // first 80 chars of the matched line (trimmed)
+  inTestFile: boolean,
+  likelyFalsePositive: boolean,
+}
+```
+
+---
+
+## Adding a new pattern
+
+All vulnerability patterns live in the `VULN_PATTERNS` array in `lib/scanner.js`. Each entry is:
+
+```javascript
+{
+  name: 'Display Name',    // shown in the report
+  severity: 'HIGH',        // CRITICAL | HIGH | MEDIUM | LOW
+  pattern: /regex/i,       // matched against each line of each file
+  skipInTests: true,       // optional — mark likelyFalsePositive when matched in test files
+}
+```
+
+Prompt-specific patterns live in `PROMPT_PATTERNS`:
+
+```javascript
+{
+  name: 'Display Name',
+  severity: 'HIGH',
+  pattern: /regex/,
+  skipCommentLine: true,   // optional — suppress matches on lines starting with // or #
+}
+```
+
+After adding a pattern, add a corresponding unit test in `__tests__/unit/scanner.test.js` with both a true-positive and a false-positive case.

package/docs/tdd-protocol.md

@@ -0,0 +1,184 @@
+# TDD Remediation Protocol
+
+Security patching without tests is guesswork. The Red-Green-Refactor loop turns every vulnerability into a provable, reproducible closure: you prove the hole exists, you close it, and you prove it is closed.
+
+---
+
+## The three phases
+
+```
+RED   → write the exploit test   → it MUST fail   (vulnerability confirmed)
+GREEN → apply the patch          → test MUST pass  (vulnerability closed)
+REFACTOR → run the full suite    → all MUST pass   (no regressions)
+```
+
+**Do not move to the next vulnerability until the current one completes all three phases.**
+
+---
+
+## Phase 1 — Red (Exploit)
+
+Write a test that actively attempts the breach. The test must fail on the **security assertion**, not just crash the app.
+
+```javascript
+// Wrong Red: test fails because the app throws 500
+expect(res.status).toBe(403); // ← fails because app returned 500
+
+// Correct Red: test fails because the vulnerability is open
+expect(res.status).toBe(403); // ← fails because app returned 200 with data
+```
+
+Place the test in your security test directory (`__tests__/security/`, `tests/security/`, or `test/security/`) so it is picked up by the `test:security` CI job.
+
+### Framework templates
+
+**Jest / Supertest (Node.js)**
+```javascript
+const request = require('supertest');
+const app = require('../../app');
+
+describe('[VulnType] — Red Phase', () => {
+  it('SHOULD block [exploit description]', async () => {
+    const res = await request(app)
+      .post('/api/vulnerable-endpoint')
+      .send({ input: '<exploit payload>' });
+
+    expect(res.status).toBe(403); // currently 200 — MUST fail (Red)
+    expect(res.body.data).not.toContain('<exploit payload>');
+  });
+});
+```
+
+**PyTest (Python)**
+```python
+def test_exploit_blocked(client, attacker_token):
+    response = client.post(
+        '/api/vulnerable-endpoint',
+        json={'input': '<exploit payload>'},
+        headers={'Authorization': f'Bearer {attacker_token}'}
+    )
+    assert response.status_code == 403  # currently 200 — RED
+```
+
+**Vitest + Testing Library (React / Next.js)**
+```typescript
+test('SHOULD NOT store auth token in localStorage', async () => {
+  render(<LoginForm />);
+  fireEvent.submit(screen.getByRole('form'));
+  await waitFor(() => {
+    expect(localStorage.getItem('token')).toBeNull(); // currently set — RED
+  });
+});
+```
+
+**flutter_test (Flutter)**
+```dart
+test('SHOULD NOT store auth token in SharedPreferences', () async {
+  SharedPreferences.setMockInitialValues({});
+  await simulateLogin(username: 'user', password: 'password');
+  final prefs = await SharedPreferences.getInstance();
+  expect(prefs.getString('token'), isNull); // currently stored — RED
+});
+```
+
+See [`prompts/red-phase.md`](../prompts/red-phase.md) for vulnerability-specific exploit strategies.
+
+---
+
+## Phase 2 — Green (Patch)
+
+Apply the **minimum code change** that makes the exploit test pass. A targeted fix is safer than a rewrite.
+
+1. Identify the root cause — a 500 error is not a security fix
+2. Apply the narrowest patch that closes the vulnerability
+3. Run `npm run test:security` — the exploit test must now pass
+4. If the test still fails, the patch is incomplete — do not advance
+
+See [`prompts/green-phase.md`](../prompts/green-phase.md) for vulnerability-specific patch strategies with before/after code examples covering:
+
+- IDOR / tenant isolation
+- XSS and `dangerouslySetInnerHTML`
+- SQL injection (parameterized queries)
+- Command injection (argument arrays)
+- Path traversal (resolve + bounds check)
+- Broken auth (JWT middleware)
+- Next.js API route auth
+- React Native / Expo sensitive storage migration
+- Flutter sensitive storage migration
+- SSRF (URL allowlist)
+- Open redirect (relative-only)
+- NoSQL injection (operator sanitization)
+- Mass assignment (field allowlisting)
+- Prototype pollution (key sanitization)
+- Weak crypto (bcrypt/argon2)
+- Missing rate limiting
+- Missing security headers (Helmet)
+- TLS bypass removal
+
+---
+
+## Phase 3 — Refactor (Regression)
+
+Run the **full** test suite — security tests plus all pre-existing functional and integration tests.
+
+```bash
+npm test          # Node.js
+pytest            # Python
+go test ./...     # Go
+flutter test      # Flutter
+```
+
+**If any pre-existing test now fails, stop and revert.** Return to Phase 2 with a narrower approach. A security fix that breaks functionality is a failed fix.
+
+### Regression checklist
+
+- [ ] Happy-path flows still work — legitimate users can access their own resources
+- [ ] Error messages are safe — no stack traces or internal paths in error responses
+- [ ] Auth bypass not introduced — the fix doesn't open a new unprotected code path
+- [ ] No secrets committed — patch doesn't hardcode keys or tokens
+- [ ] No debug logging left — remove any `console.log` added during patching
+
+See [`prompts/refactor-phase.md`](../prompts/refactor-phase.md) for the full framework-specific regression checklist.
+
+---
+
+## Phase 4 — Hardening (Proactive)
+
+After all vulnerabilities are remediated, apply defence-in-depth controls that make future vulnerabilities harder to introduce. See [`docs/hardening.md`](hardening.md) for the full guide.
+
+Summary of controls:
+- **Security headers** — `helmet()` applied before all routes; explicit CSP
+- **CSRF protection** — `csrf-csrf` double-submit pattern (not deprecated `csurf`)
+- **Rate limiting** — `express-rate-limit` on auth routes
+- **Dependency audit** — `npm audit --audit-level=high` in CI
+- **Secret history scan** — `gitleaks` / `trufflehog` to catch committed secrets
+- **Error handling** — generic 500 messages in production, no stack traces
+- **SRI** — subresource integrity hashes on third-party CDN assets
+- **GitHub Actions pinning** — every `uses:` locked to a full commit SHA
+
+---
+
+## When to revert and retry
+
+Revert the patch (`git checkout -- <file>`) and return to Phase 2 if:
+
+- A functional test fails after applying the security fix
+- The fix introduces a new 401/403 for a legitimate user flow
+- Performance degrades measurably (e.g., O(n) queries replacing O(1))
+
+When you retry, describe the constraint: *"The previous fix broke X — find a narrower approach that still closes the vulnerability."*
+
+---
+
+## Remediation Summary format
+
+After all vulnerabilities are addressed, the agent outputs a table:
+
+```
+## Remediation Summary
+
+| Vulnerability | File | Status | Test File | Fix Applied |
+|---|---|---|---|---|
+| SQLi | src/routes/users.js:34 | ✅ Fixed | __tests__/security/sqli-users.test.js | Parameterized query |
+| IDOR | src/controllers/docs.js:87 | ✅ Fixed | __tests__/security/idor-docs.test.js | Ownership check added |
+```