plumber-linter 1.1.2 → 1.3.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 +196 -142
  2. package/bin/plumber.js +922 -709
  3. package/package.json +46 -41
package/README.md CHANGED
@@ -1,142 +1,196 @@
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, plus SARIF output for GitHub code scanning.
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, JSON, or SARIF 2.1.0
36
+ npx plumber-linter scan . --format md
37
+ npx plumber-linter scan . --format json
38
+ npx plumber-linter scan . --format sarif
39
+
40
+ # View all 26 inspection rules
41
+ npx plumber-linter rules
42
+ ```
43
+
44
+ ### In GitHub Actions
45
+
46
+ ```yaml
47
+ - name: Run Plumber Linter
48
+ run: npx plumber-linter scan . --fail-on high
49
+ ```
50
+
51
+ ### In GitLab CI
52
+
53
+ ```yaml
54
+ plumber-lint:
55
+ image: node:18
56
+ script:
57
+ - npx plumber-linter scan . --fail-on high
58
+ ```
59
+
60
+ ### Git Pre-Commit Hook
61
+
62
+ Install a pre-commit hook that blocks commits containing secrets, `.env` files, or dead code:
63
+
64
+ ```bash
65
+ # Install hook (blocks staged secrets and issues >= HIGH)
66
+ npx plumber-linter install-hook --fail-on high
67
+
68
+ # Uninstall hook
69
+ npx plumber-linter uninstall-hook
70
+ ```
71
+
72
+ ### SARIF output for GitHub code scanning
73
+
74
+ `plumber scan . --format sarif` writes SARIF 2.1.0 JSON to stdout. The file contains one run for `plumber-linter` 1.3.0, every inspection rule (id, name, description, and the plain-English fix in `help.text`), and one result per finding. Each result's `message.text` repeats that finding's explanation and fix. Paths are relative to the scanned directory, and the line is included when the engine recorded one.
75
+
76
+ ```bash
77
+ npx plumber-linter scan . --format sarif > results.sarif
78
+ ```
79
+
80
+ Upload `results.sarif` with GitHub's `upload-sarif` action. The action name, the `sarif_file` input, and the `security-events: write` permission below are taken from GitHub's [Uploading a SARIF file to GitHub](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file) guide. `partialFingerprints` is left unset; that same action calculates it when the repository contains both the SARIF file and the scanned source.
81
+
82
+ ```yaml
83
+ name: Plumber code scanning
84
+ on:
85
+ push:
86
+ jobs:
87
+ plumber:
88
+ runs-on: ubuntu-latest
89
+ permissions:
90
+ security-events: write
91
+ actions: read
92
+ contents: read
93
+ steps:
94
+ - name: Checkout repository
95
+ uses: actions/checkout@v6
96
+ - name: Run Plumber
97
+ run: npx plumber-linter scan . --format sarif > results.sarif
98
+ - name: Upload SARIF file
99
+ uses: github/codeql-action/upload-sarif@v4
100
+ with:
101
+ sarif_file: results.sarif
102
+ ```
103
+
104
+ ---
105
+
106
+ ## What It Checks
107
+
108
+ ### 1. Leaked Secrets & API Keys (`leak/api-key`, `leak/hardcoded-secret`)
109
+ Detects exposed OpenAI (`sk-...`), GitHub (`ghp_...`), AWS (`AKIA...`), Slack tokens, and database credentials.
110
+ - **Vulnerable:** `const client = new OpenAI({ apiKey: "sk-live1234567890abcdef1234567890" });`
111
+ - **Fixed:** `const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });`
112
+
113
+ ### 2. Committed Environment Files (`leak/committed-env`)
114
+ Prevents committing `.env` files containing live secrets to version control.
115
+ - **Vulnerable:** `.env` committed with production credentials.
116
+ - **Fixed:** Add `.env` to `.gitignore` and commit `.env.example` with blank placeholders.
117
+
118
+ ### 3. Swallowed Exceptions (`clog/swallowed-error`)
119
+ Flags silent failure blocks that swallow exceptions and hide failures in CI/CD pipelines.
120
+ - **Vulnerable:** `try { doWork(); } catch (err) {}`
121
+ - **Fixed:** `try { doWork(); } catch (err) { logger.error(err); throw err; }`
122
+
123
+ ### 4. Unreachable Dead Code (`clog/dead-code`)
124
+ Detects unreachable statements following returns or inside constant-false branches.
125
+ - **Vulnerable:** `return result; console.log("Done");`
126
+ - **Fixed:** Delete unreachable statement (or run `npx plumber-linter clean . --write`).
127
+
128
+ ### 5. AI-Elided Code Snippets (`clog/elided-code`)
129
+ Flags lazy AI elision comments like `// ... existing code ...` left behind in source files.
130
+ - **Vulnerable:** `// ... existing code ...`
131
+ - **Fixed:** Restore the full function or component implementation.
132
+
133
+ ### 6. Non-Semantic / Inaccessible Elements (`joint/clickable-div`)
134
+ Identifies non-semantic clickable elements lacking accessible keyboard and screen-reader controls.
135
+ - **Vulnerable:** `<div onClick={handleClick}>Submit</div>`
136
+ - **Fixed:** `<button type="button" onClick={handleClick}>Submit</button>`
137
+
138
+ ### 7. Hallucinated / Undeclared Dependencies (`pipe/phantom-import`)
139
+ Spots hallucinated library imports invented by LLMs or packages missing from project manifests.
140
+ - **Vulnerable:** `import { useFeature } from "next-auth-v5-helpers";`
141
+ - **Fixed:** Use standard verified libraries and declare dependencies in manifests.
142
+
143
+ ### 8. CI/CD Supply-Chain & Pipeline Rules (v1.2.0)
144
+ - `pipe/docker-unpinned` — Flags unpinned Docker images (missing tag or `:latest`) in CI jobs or Dockerfiles (`MEDIUM`).
145
+ - `sec/curl-pipe-shell` — Flags `curl ... | bash` / `wget ... | sh` remote script execution in run steps (`CRITICAL`).
146
+ - `sec/permissions-write-all` — Flags overly broad workflow permissions (`permissions: write-all` or top-level `contents: write`) (`HIGH`).
147
+ - `leak/slack-webhook` — Flags hardcoded Slack or tokenized webhook URLs in workflow and source files (`CRITICAL`).
148
+ - `pipe/npm-unpinned` — Flags `npm install` steps in CI without `--save-exact` or `npm ci` lockfile enforcement (`MEDIUM`).
149
+
150
+ ---
151
+
152
+ ## Example Output
153
+
154
+ ```text
155
+ ================================================================
156
+ PLUMBER INSPECTION REPORT: my-service
157
+ Health Score: 87.4/100 | Grade: B | Files: 18
158
+ Issues Detected: 2
159
+ ================================================================
160
+
161
+ [FILE] src/config.ts
162
+ L14 [CRITICAL] Leaked OpenAI / Model API Key
163
+ Found: const key = "sk-live9876543210..."
164
+ Fix: Move secret to environment variable (.env).
165
+
166
+ [FILE] src/pipeline.ts
167
+ L58 [HIGH] Swallowed Exception (Silent Failure)
168
+ Found: catch (e) {}
169
+ Fix: Log the error or properly re-raise/handle it.
170
+
171
+ ================================================================
172
+
173
+ [FAILED] Found issues at or above severity: HIGH
174
+ ```
175
+
176
+ ---
177
+
178
+ ## Links
179
+
180
+ - **npm Package:** [https://www.npmjs.com/package/plumber-linter](https://www.npmjs.com/package/plumber-linter)
181
+ - **Website & Documentation:** [https://plumber-7dv.pages.dev/](https://plumber-7dv.pages.dev/)
182
+ - **GitHub Repository:** [https://github.com/parasraju/plumber](https://github.com/parasraju/plumber)
183
+
184
+ ---
185
+
186
+ ## Changelog
187
+
188
+ ## 1.3.0
189
+ SARIF output (`--format sarif`) for GitHub code scanning.
190
+
191
+ ## 1.2.0
192
+ - `pipe/docker-unpinned`: Flag unpinned Docker images (no tag or `:latest`) in CI jobs and Dockerfiles (`MEDIUM`).
193
+ - `sec/curl-pipe-shell`: Flag `curl | bash` and `wget | sh` remote script execution in CI run steps (`CRITICAL`).
194
+ - `sec/permissions-write-all`: Flag overly broad workflow write permissions (`permissions: write-all`, `contents: write`) (`HIGH`).
195
+ - `leak/slack-webhook`: Flag hardcoded Slack and tokenized webhook URLs in workflows and code (`CRITICAL`).
196
+ - `pipe/npm-unpinned`: Flag `npm install` in CI steps without `--save-exact` or `npm ci` lockfile enforcement (`MEDIUM`).