@parasraju/plumber-mcp 1.0.1 → 1.2.0

package/README.md

@@ -83,15 +83,15 @@ Add to `.vscode/mcp.json`:
 
 | Tool | Description |
 | --- | --- |
-| `plumber_scan` | Scan a local directory or file. Returns a score, grade, file count, and one line per issue with its fix. |
-| `plumber_list_rules` | List all 21 inspection rules with id, severity, title, and fix. |
-| `plumber_scan_text` | Scan a pasted code or config snippet. `filename` is optional and only selects the applicable rules. |
+| `plumber_scan` | Scan a local directory or file. Returns a score, grade, file count, and one line per issue with its fix. Optional `rulesFile`, or `.plumber-rules.json` in the target, adds a rule pack. |
+| `plumber_list_rules` | List all 26 inspection rules with id, severity, title, and fix. Optional `rulesFile` appends pack rules marked `source: pack`. |
+| `plumber_scan_text` | Scan a pasted code or config snippet. `filename` is optional and only selects the applicable rules. Optional `rulesFile` adds a rule pack. |
 
 Tool inputs are deliberately small so they cost few tokens:
 
-- `plumber_scan`: `target` (string, default `"."`)
-- `plumber_list_rules`: none
-- `plumber_scan_text`: `text` (string, required), `filename` (string, optional)
+- `plumber_scan`: `target` (string, default `"."`), `rulesFile` (string, optional)
+- `plumber_list_rules`: `rulesFile` (string, optional)
+- `plumber_scan_text`: `text` (string, required), `filename` (string, optional), `rulesFile` (string, optional)
 
 ## Example session
 
@@ -103,6 +103,94 @@ Tool inputs are deliberately small so they cost few tokens:
 >
 > **Agent:** I moved the key into `.env`, replaced it with `process.env.OPENAI_API_KEY`, and added `.env` to `.gitignore`. You should revoke the exposed key.
 
+### Scan GitHub Actions workflows
+
+`plumber_scan` reads `.github/workflows/*.yml` and `*.yaml`. `plumber_scan_text` applies the same rules when the filename is under a `workflows` path, or when the snippet parses as a workflow (`on:` and `jobs:`).
+
+- `sec/pull-request-target` (CRITICAL) — a `pull_request_target` workflow checks out untrusted pull request code or grants write permissions.
+- `sec/expression-injection` (CRITICAL) — `${{ github.event.* }}`, `${{ github.head_ref }}`, or `${{ inputs.* }}` is interpolated into a `run` script.
+- `pipe/action-unpinned` (MEDIUM) — a third-party `uses:` action is pinned to a branch or version tag instead of a full commit SHA.
+- `sec/job-permissions` (HIGH) — a job that pushes, releases, or deploys has no permissions block, uses `write-all`, or sets `contents: write` where a narrower scope would do.
+- `sec/secret-to-untrusted` (HIGH) — a secret is passed through `env` or an argument to a third-party action.
+
+> **Agent:** *(calls `plumber_scan` with `target: "."` on a repo whose `.github/workflows/pr.yml` checks out the pull request head from `pull_request_target`)*
+>
+> `- [CRITICAL] Untrusted pull_request_target Checkout or Write Permission (Use pull_request, or check out the base ref read-only with no secrets.) — .github/workflows/pr.yml:9`
+
+### Workflow YAML rules
+
+- `sec/pull-request-target` [CRITICAL] Untrusted pull_request_target Checkout or Write Permission (Use pull_request, or check out the base ref read-only with no secrets.)
+- `sec/expression-injection` [CRITICAL] Expression Injection in Workflow run Step (Pass the value through an env: variable and reference that variable in the script.)
+- `pipe/action-unpinned` [MEDIUM] Unpinned Third-Party Action (Pin the action to a full commit SHA.)
+- `sec/job-permissions` [HIGH] Job Writes Without Least-Privilege Permissions (Set least-privilege permissions on the job.)
+- `sec/secret-to-untrusted` [HIGH] Secret Passed to Untrusted Step (Scope the secret to the trusted step that needs it.)
+
+### Custom rule packs — bring your own rules
+
+Bring rule packs when you need custom rules the built-in set does not ship: an internal secret format, a banned pattern, or a house naming rule. A pack is one local JSON file. This release does not read YAML packs, and it does not download a pack from a URL.
+
+The file is a top-level object `{ "rules": [...] }`. Each rule uses these fields:
+
+- `id` (string, required) — must start with `custom/`, for example `custom/no-internal-api-key`. Any other id is rejected. An id that matches a built-in rule, or another rule in the same pack, is rejected. The built-in rule is left unchanged.
+- `severity` (string, required) — one of `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`. Anything else is rejected.
+- `title` (string, required) — short name, for example `Internal API key format`.
+- `pattern` (string, required) — a JavaScript regular expression, matched against the file text. A pattern that does not compile rejects that rule.
+- `files` (array of glob strings, optional) — for example `["**/*.js", "**/*.ts"]`. The rule runs only on files that match one of these globs. Omit it to use every file Plumber already scans. Globs support `*`, `?`, and `**`. `*` does not cross a `/`; use `**/*.js` to match JavaScript in any directory.
+- `fix` (string, required) — the plain-English fix, in the same voice as the built-in rules. A rule with no fix is rejected.
+
+On `plumber_scan`, globs only filter files the scanner already opens: `.py`, `.js`, `.jsx`, `.ts`, `.tsx`, `.html`, `.htm`, `.css`, `.scss`, `.env*`, and GitHub Actions workflow YAML. `plumber_scan_text` applies the same globs to the `filename` you pass.
+
+A bad rule is dropped. The tool result includes a `Pack error:` line that names the rule and the problem (invalid JSON names the pack file, because there is no rule yet). The 26 built-in rules still run. A broken pack does not wipe the report and does not stop the server.
+
+One pack is loaded, in this order:
+
+1. `rulesFile`, when the tool call includes it. A relative path is resolved from the server's working directory.
+2. Auto-load, only for `plumber_scan`, and only when `rulesFile` is omitted. Plumber reads `.plumber-rules.json` in the directory passed as `target`. A file target uses the directory that contains that file. Parent folders and subfolders are not searched. `plumber_scan_text` and `plumber_list_rules` do not auto-load.
+3. When both are present, `rulesFile` is the pack that runs. The two files are not merged.
+
+The scan result names the pack on one line: the file path and how many pack rules loaded, for example `Pack: /repo/.plumber-rules.json (2 pack rules loaded)`.
+
+`plumber_list_rules` with no `rulesFile` returns the 26 built-in rules. With `rulesFile`, the pack rules follow the built-ins and each one ends with `source: pack`.
+
+Save this file as `.plumber-rules.json` in the directory you scan, or pass the path as `rulesFile`. The same example ships at `examples/custom-rules.example.json`.
+
+```json
+{
+  "rules": [
+    {
+      "id": "custom/no-internal-api-key",
+      "severity": "CRITICAL",
+      "title": "Internal API key format",
+      "pattern": "\\bINT_[A-Z0-9]{16}\\b",
+      "files": ["**/*.js", "**/*.ts"],
+      "fix": "Move the internal key to an environment variable and rotate it."
+    },
+    {
+      "id": "custom/no-banned-marker",
+      "severity": "MEDIUM",
+      "title": "Banned ship marker",
+      "pattern": "\\bDO_NOT_SHIP\\b",
+      "files": ["**/*.js", "**/*.py"],
+      "fix": "Remove the banned marker before committing this file."
+    }
+  ]
+}
+```
+
+Three ways to run that pack:
+
+1. Auto-load: write it to `.plumber-rules.json`, then call `plumber_scan` with `{ "target": "." }`.
+2. `rulesFile` on `plumber_scan`: `{ "target": ".", "rulesFile": "examples/custom-rules.example.json" }`. This is the pack that runs when `.plumber-rules.json` is also present.
+3. `rulesFile` on `plumber_scan_text`: `{ "text": "const internal = \"INT_ABCDEFGHIJ123456\";\n", "filename": "src/config.js", "rulesFile": "examples/custom-rules.example.json" }`. A snippet that does not match the pattern produces no pack finding.
+
+`src/config.js` containing `INT_ABCDEFGHIJ123456` then reports:
+
+```
+- [CRITICAL] Internal API key format (Move the internal key to an environment variable and rotate it.) — src/config.js:1
+```
+
+The secret-format rule above does not check Python files. The banned-marker rule does, because its `files` list says so.
+
 ## Links
 
 - CLI: [plumber-linter](https://www.npmjs.com/package/plumber-linter)
@@ -112,6 +200,12 @@ Tool inputs are deliberately small so they cost few tokens:
 
 ## Changelog
 
+## 1.2.0
+- Custom rule packs: load your own rules from `.plumber-rules.json` or a `rulesFile`, ids under `custom/`.
+
+## 1.1.0
+- Workflow YAML rules: sec/pull-request-target, sec/expression-injection, pipe/action-unpinned, sec/job-permissions, sec/secret-to-untrusted.
+
 ## 1.0.1
 - Fix false-positive test path matching that skipped secrets in files containing "test" or "spec" substrings (e.g. `latest.js`, `inspector.js`).
 - Fix directory scan skipping target path when root directory name matches skip list or begins with a dot (e.g. `dist`, `.hidden`).

package/bin/plumber-mcp.js

@@ -5,9 +5,13 @@
  *
  * Tools:
  *   plumber_scan        scan a local directory or file
- *   plumber_list_rules  list the 21 inspection rules
+ *   plumber_list_rules  list every inspection rule
  *   plumber_scan_text   scan a pasted snippet
  *
+ * Each tool accepts an optional rulesFile path to one local JSON rule pack.
+ * plumber_scan also reads .plumber-rules.json in the target when rulesFile is omitted.
+ * Packs are never fetched from a URL.
+ *
  * Only JSON-RPC goes to stdout. Diagnostics go to stderr.
  */
 
@@ -21,7 +25,7 @@ const {
   ErrorCode,
   McpError
 } = require('@modelcontextprotocol/sdk/types.js');
-const { RULES, SCANNABLE_EXTS, scanLocalDirectory, scanText } = require('../src/engine.js');
+const { RULES, SCANNABLE_EXTS, scanLocalDirectory, scanText, loadRulePack, resolveScanPack } = require('../src/engine.js');
 
 // v1.0.1 fix: read the version from package.json so serverInfo never drifts.
 // Repro (v1.0.0): initialize -> serverInfo.version was hardcoded to "1.0.0".
@@ -34,7 +38,8 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        target: { type: 'string', description: 'Directory or file path to scan (default ".")' }
+        target: { type: 'string', description: 'Directory or file path to scan (default ".")' },
+        rulesFile: { type: 'string', description: 'Optional path to a local JSON rule pack. When omitted, .plumber-rules.json is loaded from the scan target if that file exists.' }
       },
       additionalProperties: false
     }
@@ -44,7 +49,9 @@ const TOOLS = [
     description: 'List all Plumber inspection rules with severity, title, and recommended fix.',
     inputSchema: {
       type: 'object',
-      properties: {},
+      properties: {
+        rulesFile: { type: 'string', description: 'Optional path to a local JSON rule pack. Pack rules are listed after the built-in rules and marked as custom.' }
+      },
       additionalProperties: false
     }
   },
@@ -55,7 +62,8 @@ const TOOLS = [
       type: 'object',
       properties: {
         text: { type: 'string', description: 'Code or config snippet to scan' },
-        filename: { type: 'string', description: 'Optional filename used to select applicable rules (e.g. app.js)' }
+        filename: { type: 'string', description: 'Optional filename used to select applicable rules (e.g. app.js)' },
+        rulesFile: { type: 'string', description: 'Optional path to a local JSON rule pack applied to this snippet. Pasted snippets do not auto-load a pack.' }
       },
       required: ['text'],
       additionalProperties: false
@@ -63,22 +71,47 @@ const TOOLS = [
   }
 ];
 
+function packLoadedLine(pack) {
+  const count = Array.isArray(pack.rules) ? pack.rules.length : 0;
+  const label = count === 1 ? 'pack rule' : 'pack rules';
+  return `Pack: ${pack.path} (${count} ${label} loaded)`;
+}
+
+function formatPackBanner(pack) {
+  if (!pack) return '';
+  const lines = [packLoadedLine(pack)];
+  const errors = Array.isArray(pack.errors) ? pack.errors : [];
+  for (let i = 0; i < errors.length; i++) {
+    lines.push(`Pack error: ${errors[i]}`);
+  }
+  return lines.join('\n');
+}
+
+function formatListedRule(rule) {
+  const severity = rule.sev || rule.severity;
+  const line = `${rule.id} [${severity}] ${rule.title} (${rule.fix})`;
+  if (rule.source === 'pack') return `${line} source: pack`;
+  return line;
+}
+
 function formatReport(report) {
   const header = [
     `Plumber Health Report for ${report.repo_name}`,
     report.total_files === 0 ? 'Score: n/a' : `Score: ${report.score}/100 (Grade ${report.grade})`,
     `Files: ${report.total_files} | Issues: ${report.issues.length}`
   ].join('\n');
+  const banner = formatPackBanner(report.pack);
+  const top = banner ? `${header}\n${banner}` : header;
 
   // v1.0.1 fix: do not report "No issues found." when nothing was scanned.
   // Repro (v1.0.0): plumber_scan { target: ".github/workflows/ci.yml" } (or a
   //   Dockerfile, or an empty dir) -> "Score: 100/100 (Grade A) ... No issues found."
   if (report.total_files === 0) {
-    return `${header}\n\nNo scannable files found, so nothing was checked. Supported: ${SCANNABLE_EXTS.join(' ')} and .env* files.`;
+    return `${top}\n\nNo scannable files found, so nothing was checked. Supported: ${SCANNABLE_EXTS.join(' ')} and .env* files.`;
   }
 
   if (report.issues.length === 0) {
-    return `${header}\n\nNo issues found.`;
+    return `${top}\n\nNo issues found.`;
   }
 
   const locations = new Map();
@@ -94,7 +127,7 @@ function formatReport(report) {
     return `- [${issue.severity}] ${issue.title} (${issue.fix})${suffix}`;
   });
 
-  return `${header}\n\n${lines.join('\n')}`;
+  return `${top}\n\n${lines.join('\n')}`;
 }
 
 function requireString(value, name) {
@@ -114,15 +147,29 @@ function requireText(text) {
 
 function runScanTool(args) {
   const target = requireString(args.target, 'target') || '.';
+  const rulesFile = requireString(args.rulesFile, 'rulesFile');
   const absolute = path.resolve(target);
 
   if (!fs.existsSync(absolute)) {
     throw new McpError(ErrorCode.InvalidParams, `Target path does not exist: ${absolute}`);
   }
 
+  let pack = null;
   try {
-    return formatReport(scanLocalDirectory(absolute));
+    pack = resolveScanPack(absolute, rulesFile);
   } catch (err) {
+    pack = {
+      path: rulesFile || absolute,
+      rules: [],
+      errors: [`Pack failed to load: ${err.message}`],
+      broken: true
+    };
+  }
+
+  try {
+    return formatReport(scanLocalDirectory(absolute, pack ? { pack } : undefined));
+  } catch (err) {
+    if (err instanceof McpError) throw err;
     throw new McpError(ErrorCode.InternalError, `Scan failed: ${err.message}`);
   }
 }
@@ -130,16 +177,55 @@ function runScanTool(args) {
 function runScanTextTool(args) {
   const text = requireText(args.text);
   const filename = requireString(args.filename, 'filename');
+  const rulesFile = requireString(args.rulesFile, 'rulesFile');
+  let pack = null;
+  if (rulesFile) {
+    try {
+      pack = loadRulePack(rulesFile);
+    } catch (err) {
+      pack = {
+        path: rulesFile,
+        rules: [],
+        errors: [`Pack ${rulesFile} failed to load: ${err.message}`],
+        broken: true
+      };
+    }
+  }
 
   try {
-    return formatReport(scanText(text, filename));
+    return formatReport(scanText(text, filename, pack ? { pack } : undefined));
   } catch (err) {
+    if (err instanceof McpError) throw err;
     throw new McpError(ErrorCode.InternalError, `Scan failed: ${err.message}`);
   }
 }
 
-function runListRulesTool() {
-  return RULES.map((rule) => `${rule.id} [${rule.sev}] ${rule.title} (${rule.fix})`).join('\n');
+function runListRulesTool(args) {
+  const rulesFile = requireString(args && args.rulesFile, 'rulesFile');
+  let pack = null;
+  if (rulesFile) {
+    try {
+      pack = loadRulePack(rulesFile);
+    } catch (err) {
+      pack = {
+        path: rulesFile,
+        rules: [],
+        errors: [`Pack ${rulesFile} failed to load: ${err.message}`],
+        broken: true
+      };
+    }
+  }
+  const lines = RULES.map((rule) => formatListedRule(rule));
+  if (!pack) return lines.join('\n');
+  for (let i = 0; i < pack.rules.length; i++) {
+    lines.push(formatListedRule(pack.rules[i]));
+  }
+  lines.push(packLoadedLine(pack));
+  const errors = pack.errors || [];
+  for (let i = 0; i < errors.length; i++) {
+    lines.push(`Pack error: ${errors[i]}`);
+  }
+  return lines.join('\n');
 }
 
 async function main() {
@@ -155,7 +241,7 @@ async function main() {
     if (name === 'plumber_scan') {
       text = runScanTool(args);
     } else if (name === 'plumber_list_rules') {
-      text = runListRulesTool();
+      text = runListRulesTool(args);
     } else if (name === 'plumber_scan_text') {
       text = runScanTextTool(args);
     } else {

package/examples/custom-rules.example.json

@@ -0,0 +1,20 @@
+{
+  "rules": [
+    {
+      "id": "custom/no-internal-api-key",
+      "severity": "CRITICAL",
+      "title": "Internal API key format",
+      "pattern": "\\bINT_[A-Z0-9]{16}\\b",
+      "files": ["**/*.js", "**/*.ts"],
+      "fix": "Move the internal key to an environment variable and rotate it."
+    },
+    {
+      "id": "custom/no-banned-marker",
+      "severity": "MEDIUM",
+      "title": "Banned ship marker",
+      "pattern": "\\bDO_NOT_SHIP\\b",
+      "files": ["**/*.js", "**/*.py"],
+      "fix": "Remove the banned marker before committing this file."
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@parasraju/plumber-mcp",
-  "version": "1.0.1",
-  "description": "Plumber as an MCP server — let your AI coding agent scan repos for leaked secrets, dead code, and AI slop, with fixes in plain English.",
+  "version": "1.2.0",
+  "description": "Plumber as an MCP server — let your AI coding agent scan repos and GitHub Actions workflows for leaked secrets, dead code, and AI slop, with fixes in plain English. Add your own checks with custom rule packs.",
   "main": "src/engine.js",
   "bin": {
     "plumber-mcp": "bin/plumber-mcp.js"
@@ -15,6 +15,7 @@
   "files": [
     "bin",
     "src",
+    "examples",
     "README.md"
   ],
   "keywords": [
@@ -27,7 +28,13 @@
     "security",
     "secrets-detection",
     "code-quality",
-    "linter"
+    "linter",
+    "github-actions",
+    "ci-cd",
+    "workflow",
+    "yaml",
+    "custom-rules",
+    "rule-packs"
   ],
   "repository": {
     "type": "git",
@@ -40,6 +47,7 @@
   "license": "MIT",
   "author": "Paras Raju",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.32.2"
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "js-yaml": "^4.3.2"
   }
 }