plumber-linter 1.1.2 → 1.2.0

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 (3) hide show
  1. package/README.md +160 -142
  2. package/bin/plumber.js +830 -709
  3. package/package.json +44 -41
package/README.md CHANGED
@@ -1,142 +1,160 @@
1
- # Plumber
2
-
3
- CI/CD pipeline linter that flags hardcoded secrets, leaked credentials, and dead code — with fixes in plain English.
4
-
5
- [![npm version](https://img.shields.io/npm/v/plumber-linter.svg)](https://www.npmjs.com/package/plumber-linter)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/parasraju/plumber/blob/main/LICENSE)
7
-
8
- Plumber inspects codebases and git repositories in milliseconds without requiring an LLM. It enforces quality and security gates in CI/CD pipelines and git pre-commit hooks, exiting with non-zero status when critical or high-severity issues are found.
9
-
10
- ---
11
-
12
- ## Installation
13
-
14
- ```bash
15
- # Local project dependency
16
- npm install --save-dev plumber-linter
17
-
18
- # Global installation
19
- npm install -g plumber-linter
20
- ```
21
-
22
- ---
23
-
24
- ## Quick Start
25
-
26
- Run instantly with `npx` (no install required):
27
-
28
- ```bash
29
- # Scan current repository
30
- npx plumber-linter scan .
31
-
32
- # Enforce quality gate in CI (exit 1 on HIGH or CRITICAL issues)
33
- npx plumber-linter scan . --fail-on high
34
-
35
- # Export report as Markdown or JSON
36
- npx plumber-linter scan . --format md
37
- npx plumber-linter scan . --format json
38
-
39
- # View all 21 inspection rules
40
- npx plumber-linter rules
41
- ```
42
-
43
- ### In GitHub Actions
44
-
45
- ```yaml
46
- - name: Run Plumber Linter
47
- run: npx plumber-linter scan . --fail-on high
48
- ```
49
-
50
- ### In GitLab CI
51
-
52
- ```yaml
53
- plumber-lint:
54
- image: node:18
55
- script:
56
- - npx plumber-linter scan . --fail-on high
57
- ```
58
-
59
- ### Git Pre-Commit Hook
60
-
61
- Install a pre-commit hook that blocks commits containing secrets, `.env` files, or dead code:
62
-
63
- ```bash
64
- # Install hook (blocks staged secrets and issues >= HIGH)
65
- npx plumber-linter install-hook --fail-on high
66
-
67
- # Uninstall hook
68
- npx plumber-linter uninstall-hook
69
- ```
70
-
71
- ---
72
-
73
- ## What It Checks
74
-
75
- ### 1. Leaked Secrets & API Keys (`leak/api-key`, `leak/hardcoded-secret`)
76
- Detects exposed OpenAI (`sk-...`), GitHub (`ghp_...`), AWS (`AKIA...`), Slack tokens, and database credentials.
77
- - **Vulnerable:** `const client = new OpenAI({ apiKey: "sk-live1234567890abcdef1234567890" });`
78
- - **Fixed:** `const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });`
79
-
80
- ### 2. Committed Environment Files (`leak/committed-env`)
81
- Prevents committing `.env` files containing live secrets to version control.
82
- - **Vulnerable:** `.env` committed with production credentials.
83
- - **Fixed:** Add `.env` to `.gitignore` and commit `.env.example` with blank placeholders.
84
-
85
- ### 3. Swallowed Exceptions (`clog/swallowed-error`)
86
- Flags silent failure blocks that swallow exceptions and hide failures in CI/CD pipelines.
87
- - **Vulnerable:** `try { doWork(); } catch (err) {}`
88
- - **Fixed:** `try { doWork(); } catch (err) { logger.error(err); throw err; }`
89
-
90
- ### 4. Unreachable Dead Code (`clog/dead-code`)
91
- Detects unreachable statements following returns or inside constant-false branches.
92
- - **Vulnerable:** `return result; console.log("Done");`
93
- - **Fixed:** Delete unreachable statement (or run `npx plumber-linter clean . --write`).
94
-
95
- ### 5. AI-Elided Code Snippets (`clog/elided-code`)
96
- Flags lazy AI elision comments like `// ... existing code ...` left behind in source files.
97
- - **Vulnerable:** `// ... existing code ...`
98
- - **Fixed:** Restore the full function or component implementation.
99
-
100
- ### 6. Non-Semantic / Inaccessible Elements (`joint/clickable-div`)
101
- Identifies non-semantic clickable elements lacking accessible keyboard and screen-reader controls.
102
- - **Vulnerable:** `<div onClick={handleClick}>Submit</div>`
103
- - **Fixed:** `<button type="button" onClick={handleClick}>Submit</button>`
104
-
105
- ### 7. Hallucinated / Undeclared Dependencies (`pipe/phantom-import`)
106
- Spots hallucinated library imports invented by LLMs or packages missing from project manifests.
107
- - **Vulnerable:** `import { useFeature } from "next-auth-v5-helpers";`
108
- - **Fixed:** Use standard verified libraries and declare dependencies in manifests.
109
-
110
- ---
111
-
112
- ## Example Output
113
-
114
- ```text
115
- ================================================================
116
- PLUMBER INSPECTION REPORT: my-service
117
- Health Score: 87.4/100 | Grade: B | Files: 18
118
- Issues Detected: 2
119
- ================================================================
120
-
121
- [FILE] src/config.ts
122
- L14 [CRITICAL] Leaked OpenAI / Model API Key
123
- Found: const key = "sk-live9876543210..."
124
- Fix: Move secret to environment variable (.env).
125
-
126
- [FILE] src/pipeline.ts
127
- L58 [HIGH] Swallowed Exception (Silent Failure)
128
- Found: catch (e) {}
129
- Fix: Log the error or properly re-raise/handle it.
130
-
131
- ================================================================
132
-
133
- [FAILED] Found issues at or above severity: HIGH
134
- ```
135
-
136
- ---
137
-
138
- ## Links
139
-
140
- - **npm Package:** [https://www.npmjs.com/package/plumber-linter](https://www.npmjs.com/package/plumber-linter)
141
- - **Website & Documentation:** [https://plumber-7dv.pages.dev/](https://plumber-7dv.pages.dev/)
142
- - **GitHub Repository:** [https://github.com/parasraju/plumber](https://github.com/parasraju/plumber)
1
+ # Plumber
2
+
3
+ CI/CD pipeline linter that flags hardcoded secrets, leaked credentials, and dead code — with fixes in plain English.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/plumber-linter.svg)](https://www.npmjs.com/package/plumber-linter)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/parasraju/plumber/blob/main/LICENSE)
7
+
8
+ Plumber inspects codebases and git repositories in milliseconds without requiring an LLM. It enforces quality and security gates in CI/CD pipelines and git pre-commit hooks, exiting with non-zero status when critical or high-severity issues are found.
9
+
10
+ ---
11
+
12
+ ## Installation
13
+
14
+ ```bash
15
+ # Local project dependency
16
+ npm install --save-dev plumber-linter
17
+
18
+ # Global installation
19
+ npm install -g plumber-linter
20
+ ```
21
+
22
+ ---
23
+
24
+ ## Quick Start
25
+
26
+ Run instantly with `npx` (no install required):
27
+
28
+ ```bash
29
+ # Scan current repository
30
+ npx plumber-linter scan .
31
+
32
+ # Enforce quality gate in CI (exit 1 on HIGH or CRITICAL issues)
33
+ npx plumber-linter scan . --fail-on high
34
+
35
+ # Export report as Markdown or JSON
36
+ npx plumber-linter scan . --format md
37
+ npx plumber-linter scan . --format json
38
+
39
+ # View all 26 inspection rules
40
+ npx plumber-linter rules
41
+ ```
42
+
43
+ ### In GitHub Actions
44
+
45
+ ```yaml
46
+ - name: Run Plumber Linter
47
+ run: npx plumber-linter scan . --fail-on high
48
+ ```
49
+
50
+ ### In GitLab CI
51
+
52
+ ```yaml
53
+ plumber-lint:
54
+ image: node:18
55
+ script:
56
+ - npx plumber-linter scan . --fail-on high
57
+ ```
58
+
59
+ ### Git Pre-Commit Hook
60
+
61
+ Install a pre-commit hook that blocks commits containing secrets, `.env` files, or dead code:
62
+
63
+ ```bash
64
+ # Install hook (blocks staged secrets and issues >= HIGH)
65
+ npx plumber-linter install-hook --fail-on high
66
+
67
+ # Uninstall hook
68
+ npx plumber-linter uninstall-hook
69
+ ```
70
+
71
+ ---
72
+
73
+ ## What It Checks
74
+
75
+ ### 1. Leaked Secrets & API Keys (`leak/api-key`, `leak/hardcoded-secret`)
76
+ Detects exposed OpenAI (`sk-...`), GitHub (`ghp_...`), AWS (`AKIA...`), Slack tokens, and database credentials.
77
+ - **Vulnerable:** `const client = new OpenAI({ apiKey: "sk-live1234567890abcdef1234567890" });`
78
+ - **Fixed:** `const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });`
79
+
80
+ ### 2. Committed Environment Files (`leak/committed-env`)
81
+ Prevents committing `.env` files containing live secrets to version control.
82
+ - **Vulnerable:** `.env` committed with production credentials.
83
+ - **Fixed:** Add `.env` to `.gitignore` and commit `.env.example` with blank placeholders.
84
+
85
+ ### 3. Swallowed Exceptions (`clog/swallowed-error`)
86
+ Flags silent failure blocks that swallow exceptions and hide failures in CI/CD pipelines.
87
+ - **Vulnerable:** `try { doWork(); } catch (err) {}`
88
+ - **Fixed:** `try { doWork(); } catch (err) { logger.error(err); throw err; }`
89
+
90
+ ### 4. Unreachable Dead Code (`clog/dead-code`)
91
+ Detects unreachable statements following returns or inside constant-false branches.
92
+ - **Vulnerable:** `return result; console.log("Done");`
93
+ - **Fixed:** Delete unreachable statement (or run `npx plumber-linter clean . --write`).
94
+
95
+ ### 5. AI-Elided Code Snippets (`clog/elided-code`)
96
+ Flags lazy AI elision comments like `// ... existing code ...` left behind in source files.
97
+ - **Vulnerable:** `// ... existing code ...`
98
+ - **Fixed:** Restore the full function or component implementation.
99
+
100
+ ### 6. Non-Semantic / Inaccessible Elements (`joint/clickable-div`)
101
+ Identifies non-semantic clickable elements lacking accessible keyboard and screen-reader controls.
102
+ - **Vulnerable:** `<div onClick={handleClick}>Submit</div>`
103
+ - **Fixed:** `<button type="button" onClick={handleClick}>Submit</button>`
104
+
105
+ ### 7. Hallucinated / Undeclared Dependencies (`pipe/phantom-import`)
106
+ Spots hallucinated library imports invented by LLMs or packages missing from project manifests.
107
+ - **Vulnerable:** `import { useFeature } from "next-auth-v5-helpers";`
108
+ - **Fixed:** Use standard verified libraries and declare dependencies in manifests.
109
+
110
+ ### 8. CI/CD Supply-Chain & Pipeline Rules (v1.2.0)
111
+ - `pipe/docker-unpinned` — Flags unpinned Docker images (missing tag or `:latest`) in CI jobs or Dockerfiles (`MEDIUM`).
112
+ - `sec/curl-pipe-shell` — Flags `curl ... | bash` / `wget ... | sh` remote script execution in run steps (`CRITICAL`).
113
+ - `sec/permissions-write-all` — Flags overly broad workflow permissions (`permissions: write-all` or top-level `contents: write`) (`HIGH`).
114
+ - `leak/slack-webhook` — Flags hardcoded Slack or tokenized webhook URLs in workflow and source files (`CRITICAL`).
115
+ - `pipe/npm-unpinned` — Flags `npm install` steps in CI without `--save-exact` or `npm ci` lockfile enforcement (`MEDIUM`).
116
+
117
+ ---
118
+
119
+ ## Example Output
120
+
121
+ ```text
122
+ ================================================================
123
+ PLUMBER INSPECTION REPORT: my-service
124
+ Health Score: 87.4/100 | Grade: B | Files: 18
125
+ Issues Detected: 2
126
+ ================================================================
127
+
128
+ [FILE] src/config.ts
129
+ L14 [CRITICAL] Leaked OpenAI / Model API Key
130
+ Found: const key = "sk-live9876543210..."
131
+ Fix: Move secret to environment variable (.env).
132
+
133
+ [FILE] src/pipeline.ts
134
+ L58 [HIGH] Swallowed Exception (Silent Failure)
135
+ Found: catch (e) {}
136
+ Fix: Log the error or properly re-raise/handle it.
137
+
138
+ ================================================================
139
+
140
+ [FAILED] Found issues at or above severity: HIGH
141
+ ```
142
+
143
+ ---
144
+
145
+ ## Links
146
+
147
+ - **npm Package:** [https://www.npmjs.com/package/plumber-linter](https://www.npmjs.com/package/plumber-linter)
148
+ - **Website & Documentation:** [https://plumber-7dv.pages.dev/](https://plumber-7dv.pages.dev/)
149
+ - **GitHub Repository:** [https://github.com/parasraju/plumber](https://github.com/parasraju/plumber)
150
+
151
+ ---
152
+
153
+ ## Changelog
154
+
155
+ ## 1.2.0
156
+ - `pipe/docker-unpinned`: Flag unpinned Docker images (no tag or `:latest`) in CI jobs and Dockerfiles (`MEDIUM`).
157
+ - `sec/curl-pipe-shell`: Flag `curl | bash` and `wget | sh` remote script execution in CI run steps (`CRITICAL`).
158
+ - `sec/permissions-write-all`: Flag overly broad workflow write permissions (`permissions: write-all`, `contents: write`) (`HIGH`).
159
+ - `leak/slack-webhook`: Flag hardcoded Slack and tokenized webhook URLs in workflows and code (`CRITICAL`).
160
+ - `pipe/npm-unpinned`: Flag `npm install` in CI steps without `--save-exact` or `npm ci` lockfile enforcement (`MEDIUM`).