@lhi/tdd-audit 1.8.3 → 1.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +27 -153
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,182 +1,56 @@
1
1
  # @lhi/tdd-audit
2
2
 
3
- > **v1.8.3** — 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.
3
+ > **v1.8.4** — Security skill installer for **Claude Code, Gemini CLI, Cursor, Codex, and OpenCode**. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol — prove the hole exists, apply the fix, prove it's closed.
4
4
 
5
- ## What happens on install
6
-
7
- Running the installer does five things immediately:
8
-
9
- 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
10
- 2. **Scaffolds `__tests__/security/`** with a framework-matched boilerplate exploit test
11
- 3. **Adds `test:security`** to your `package.json` scripts (Node.js projects)
12
- 4. **Creates `.github/workflows/security-tests.yml`** so the CI gate exists from day one
13
- 5. **Installs the `/tdd-audit` skill** for your AI coding agent
14
-
15
- ## Installation
5
+ ## Install
16
6
 
17
7
  ```bash
18
8
  npx @lhi/tdd-audit
19
9
  ```
20
10
 
21
- Or clone and run directly:
22
-
23
- ```bash
24
- node index.js
25
- ```
26
-
27
- ### Platform-specific flags
11
+ On first run the installer:
28
12
 
29
- | Platform | Command |
30
- |---|---|
31
- | Claude Code | `npx @lhi/tdd-audit --local --claude` |
32
- | Gemini CLI / Codex / OpenCode | `npx @lhi/tdd-audit --local` |
33
- | With pre-commit hook | add `--with-hooks` |
34
- | Scan only (no install) | `npx @lhi/tdd-audit --scan` |
13
+ 1. Scans your codebase for **34 vulnerability patterns** and prints a severity-ranked report
14
+ 2. Scaffolds `__tests__/security/` with a framework-matched exploit test boilerplate
15
+ 3. Adds `test:security` to `package.json`
16
+ 4. Creates `.github/workflows/security-tests.yml` with SHA-pinned actions and `npm audit`
17
+ 5. Installs the `/tdd-audit` skill for your AI agent
35
18
 
36
- ### All flags
19
+ ### Flags
37
20
 
38
21
  | Flag | Description |
39
22
  |---|---|
40
- | `--local` | Install skill files into the current project instead of `~` |
41
- | `--claude` | Use `.claude/` instead of `.agents/` as the skill directory |
42
- | `--with-hooks` | Install a pre-commit hook that blocks commits if security tests fail |
43
- | `--skip-scan` | Skip the automatic vulnerability scan on install |
44
- | `--scan` / `--scan-only` | Run the vulnerability scan without installing anything |
45
-
46
- ### Framework detection
23
+ | `--local` | Install into the current project instead of `~` |
24
+ | `--claude` | Use `.claude/` instead of `.agents/` |
25
+ | `--with-hooks` | Add a pre-commit hook that blocks commits on failing security tests |
26
+ | `--skip-scan` | Skip the vulnerability scan on install |
27
+ | `--scan` / `--scan-only` | Scan only — no install, no code changes |
47
28
 
48
- The installer automatically detects your project's test framework and scaffolds the right boilerplate:
29
+ ### Platform
49
30
 
50
- | Detected | Boilerplate | `test:security` command |
51
- |---|---|---|
52
- | `jest` / `supertest` | `sample.exploit.test.js` | `jest --testPathPatterns=__tests__/security` |
53
- | `vitest` | `sample.exploit.test.vitest.js` | `vitest run __tests__/security` |
54
- | `mocha` | `sample.exploit.test.js` | `mocha '__tests__/security/**/*.spec.js'` |
55
- | `pytest.ini` / `pyproject.toml` | `sample.exploit.test.pytest.py` | `pytest tests/security/ -v` |
56
- | `go.mod` | `sample.exploit.test.go` | `go test ./security/... -v` |
57
- | `pubspec.yaml` | `sample_exploit_test.dart` | `flutter test test/security/` |
31
+ | Platform | Command |
32
+ |---|---|
33
+ | Claude Code | `npx @lhi/tdd-audit --local --claude` |
34
+ | Gemini CLI / Codex / OpenCode | `npx @lhi/tdd-audit --local` |
58
35
 
59
36
  ## Usage
60
37
 
61
- Once installed, trigger the autonomous audit in your agent:
62
-
63
38
  ```text
64
39
  /tdd-audit
65
40
  ```
66
41
 
67
- The agent will:
68
-
69
- 1. Detect your tech stack and scope the scan to relevant patterns only
70
- 2. Scan the codebase and present a severity-ranked findings report (CRITICAL / HIGH / MEDIUM / LOW)
71
- 3. **Wait for your confirmation** before making any changes
72
- 4. For each confirmed vulnerability, apply the full Red-Green-Refactor loop:
73
- - **Red** — write an exploit test that fails, proving the vulnerability exists
74
- - **Green** — apply the targeted patch, making the test pass
75
- - **Refactor** — run the full suite to confirm no regressions
76
- 5. Apply proactive hardening controls (security headers, rate limiting, `npm audit`, secret history scan)
77
- 6. Deliver a final Remediation Summary table
78
-
79
- The agent works one vulnerability at a time and does not advance until the current one is fully proven closed.
80
-
81
- Pass `--scan` in your prompt to get the Audit Report only, without any code changes.
82
-
83
- ## Vulnerability scanner
84
-
85
- The built-in scanner catches **34 patterns** across OWASP Top 10, mobile, agentic AI, and prompt/skill files:
86
-
87
- | Category | Patterns |
88
- |---|---|
89
- | Injection | SQL Injection, Command Injection, NoSQL Injection, Template Injection |
90
- | Broken Auth | JWT Alg None, Broken Auth, Timing-Unsafe Comparison, Hardcoded Secret, Secret Fallback |
91
- | XSS / Output | XSS, eval() Injection, Open Redirect |
92
- | Crypto | Weak Crypto (MD5/SHA1), Insecure Random, TLS Bypass |
93
- | Server-side | SSRF, Path Traversal, XXE, Insecure Deserialization |
94
- | Assignment | Mass Assignment, Prototype Pollution |
95
- | Mobile | Sensitive Storage, WebView JS Bridge, Deep Link Injection, Android Debuggable |
96
- | Config / Infra | CORS Wildcard, Cleartext Traffic, Config Secrets, ReDoS |
97
- | Agentic / Prompt | Deprecated CSRF Package (`csurf`), Unpinned npx MCP Server, Cleartext URL in Prompt |
98
-
99
- ### Scanner behaviour
100
-
101
- - **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.
102
- - **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.
103
- - **`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.
104
- - **Binary and oversized files skipped** — files larger than 512 KB or containing null bytes are skipped to prevent OOM.
105
- - **Symlinks skipped** — symlinks are never followed, preventing directory-escape on M-series Macs and shared filesystems.
106
-
107
- ## Running security tests
108
-
109
- ```bash
110
- # Node.js
111
- npm run test:security
112
-
113
- # Python
114
- pytest tests/security/ -v
115
-
116
- # Go
117
- go test ./security/... -v
118
-
119
- # Flutter
120
- flutter test test/security/
121
- ```
122
-
123
- ## CI/CD
124
-
125
- The installer creates framework-matched workflow files under `.github/workflows/`. Both `security-tests.yml` and `ci.yml` include:
126
-
127
- - SHA-pinned `uses:` references on every action (supply chain hardening)
128
- - `npm audit --audit-level=high` (or equivalent) to catch vulnerable dependencies
129
- - The security exploit test suite on every push and pull request
130
-
131
- To add the security gate to an existing pipeline manually:
132
-
133
- ```yaml
134
- - name: Dependency audit
135
- run: npm audit --audit-level=high
136
-
137
- - name: Run security exploit tests
138
- run: npm run test:security # or pytest tests/security/, flutter test test/security/
139
- ```
140
-
141
- ## Pre-commit hook
142
-
143
- The `--with-hooks` flag appends a security gate to `.git/hooks/pre-commit`. Commits are blocked if any exploit test fails:
144
-
145
- ```
146
- ❌ Security tests failed. Commit blocked.
147
- ```
148
-
149
- The hook is non-destructive — it appends to existing hook content rather than overwriting it.
150
-
151
- ## Agentic AI security (ASI01–ASI10)
152
-
153
- When the project contains AI agent code, MCP configurations, or `CLAUDE.md` files, the scanner also checks for agentic-specific vulnerabilities:
154
-
155
- | ID | Vulnerability | Risk |
156
- |---|---|---|
157
- | ASI01 | Prompt injection via tool output | Malicious content in web/file reads hijacks agent behaviour |
158
- | ASI02 | CLAUDE.md / instructions file injection | Attacker-controlled system prompts override agent identity |
159
- | ASI03 | MCP server supply chain (unpinned `npx`) | Compromised package version exfiltrates secrets |
160
- | ASI04 | Excessive tool permissions | Agent can write files or run shell when only read is needed |
161
- | ASI05 | Secrets in tool call arguments | Tokens/passwords logged by external tools |
162
- | ASI06 | Unvalidated agent action execution | Agent runs irreversible actions without user confirmation |
163
- | ASI07 | Insecure direct agent communication | Sub-agent messages trusted without verification |
164
- | ASI08 | GitHub Actions command injection | `github.event.*` interpolated directly into `run:` steps |
165
- | ASI09 | Unpinned GitHub Actions (supply chain) | Mutable `@v4` / `@main` tags can be hijacked |
166
- | ASI10 | Secrets in workflow environment | Secrets printed to logs or embedded in curl URLs |
167
-
168
- See [`docs/agentic-ai-security.md`](docs/agentic-ai-security.md) for grep patterns, examples, and fixes.
42
+ The agent detects your stack, presents a CRITICAL → LOW findings report, waits for confirmation, then works through each vulnerability one at a time using Red-Green-Refactor. Pass `--scan` for a report-only run with no code changes.
169
43
 
170
44
  ## Documentation
171
45
 
172
- | File | Contents |
46
+ | | |
173
47
  |---|---|
174
- | [`docs/scanner.md`](docs/scanner.md) | How the scanner works — architecture, detection logic, false-positive handling |
175
- | [`docs/vulnerability-patterns.md`](docs/vulnerability-patterns.md) | All 34 patterns with descriptions, grep signatures, and fix pointers |
176
- | [`docs/tdd-protocol.md`](docs/tdd-protocol.md) | The Red-Green-Refactor protocol in full, with framework templates |
177
- | [`docs/agentic-ai-security.md`](docs/agentic-ai-security.md) | ASI01–ASI10 agentic AI vulnerability reference |
178
- | [`docs/hardening.md`](docs/hardening.md) | Phase 4 proactive hardening controls |
179
- | [`docs/ci-cd.md`](docs/ci-cd.md) | CI/CD integration guide for all supported stacks |
48
+ | [Scanner](docs/scanner.md) | Architecture, detection logic, false-positive handling, how to add patterns |
49
+ | [Vulnerability Patterns](docs/vulnerability-patterns.md) | All 34 patterns — descriptions, grep signatures, fix pointers |
50
+ | [TDD Protocol](docs/tdd-protocol.md) | Red-Green-Refactor in full, with framework templates for all 6 stacks |
51
+ | [Agentic AI Security](docs/agentic-ai-security.md) | ASI01–ASI10 — prompt injection, MCP supply chain, Actions injection |
52
+ | [Hardening](docs/hardening.md) | Phase 4 controls — Helmet, CSP, CSRF, rate limiting, gitleaks, SRI |
53
+ | [CI/CD](docs/ci-cd.md) | Workflow templates, existing pipeline integration, secret leak prevention |
180
54
 
181
55
  ## License
182
56
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lhi/tdd-audit",
3
- "version": "1.8.3",
3
+ "version": "1.8.4",
4
4
  "description": "Security skill installer for Claude Code, Gemini CLI, Cursor, Codex, and OpenCode. Patches vulnerabilities using a Red-Green-Refactor exploit-test protocol.",
5
5
  "main": "index.js",
6
6
  "bin": {