goodvibesonly-cc 0.3.1 → 0.4.0

package/README.md

@@ -15,19 +15,21 @@
 
 # GoodVibesOnly
 
-**Security scanner for vibe-coded projects.** A Claude Code extension that automatically scans for vulnerabilities before you commit.
+**Security scanner for vibe-coded projects.** A Claude Code extension that automatically scans for vulnerabilities when Claude Code commits on your behalf.
 
 ## How It Works
 
-GoodVibesOnly uses Claude Code's hooks system to intercept git commands:
+GoodVibesOnly uses Claude Code's [hooks system](https://docs.anthropic.com/en/docs/claude-code/hooks) to intercept git commands **within Claude Code sessions**. It does not hook into git directly — it only triggers when Claude Code itself runs a Bash command.
 
-1. **Hooks into git commit/push** - Automatically runs before any `git commit` or `git push`
-2. **Scans changed files** - Checks for hardcoded secrets, injection vulnerabilities, XSS, and more
-3. **Blocks on critical issues** - Prevents commits with critical vulnerabilities (exit code 2)
+1. **Intercepts Claude Code's Bash calls** - A `PreToolUse` hook runs the scanner whenever Claude Code is about to execute a Bash command
+2. **Checks for git commit/push** - If the command is a `git commit` or `git push`, it scans staged files for hardcoded secrets, injection vulnerabilities, XSS, and more
+3. **Blocks on critical issues** - Prevents Claude Code from executing the commit by exiting with code 2
 4. **Allows warnings through** - High/medium issues are reported but don't block
 
+> **Note:** This only works when committing through Claude Code. Running `git commit` directly in your terminal will not trigger the scan. For terminal-level git hooks, consider a traditional pre-commit hook tool.
+
 ```
-You: git commit -m "add user api"
+You (in Claude Code): commit my changes
 
 🛡️  GoodVibesOnly Security Scan
 
@@ -42,7 +44,7 @@ You: git commit -m "add user api"
      db.query("SELECT * FROM users WHERE id = " + id)
 
 Found 2 critical, 0 high, 0 medium issues.
-Commit blocked. Fix critical issues or use --no-verify to bypass.
+Commit blocked — fix critical issues before committing.
 ```
 
 ## Installation
@@ -92,11 +94,11 @@ node bin/install.js --uninstall   # Remove GoodVibesOnly
 
 ### Automatic (via hooks)
 
-Just use git normally. GoodVibesOnly runs automatically:
+When working inside Claude Code, GoodVibesOnly runs automatically whenever Claude executes a git commit or push:
 
-```bash
-git commit -m "message"    # Scans before commit
-git push                   # Scans before push
+```
+You: commit my changes        # Scans before Claude runs git commit
+You: push to origin            # Scans before Claude runs git push
 ```
 
 ### Manual Scan
@@ -158,23 +160,72 @@ goodvibesonly/
 └── README.md
 ```
 
+## Allowlist
+
+Suppress specific findings by adding a `.goodvibesonly.json` file to your project root:
+
+```json
+{
+  "allow": [
+    { "pattern": "XSS via dangerouslySetInnerHTML", "reason": "Sanitized with DOMPurify" },
+    { "path": "test/**", "reason": "Test files contain intentional patterns" },
+    { "pattern": "SQL Injection", "path": "src/db/raw.js", "reason": "Parameterized at call site" }
+  ]
+}
+```
+
+Each entry in the `allow` array supports:
+
+| Fields | Effect |
+|--------|--------|
+| `pattern` only | Suppress that pattern in all files |
+| `path` only | Suppress all patterns in matching files |
+| `pattern` + `path` | Suppress specific pattern in specific files |
+
+- `reason` is expected on every entry (warns if missing)
+- Pattern names must match exactly — run `node bin/scan.js --list-patterns` to see all names
+- `path` supports glob patterns (`*` for single directory, `**` for recursive)
+
+### Conversational Flow
+
+When GoodVibesOnly flags a finding in Claude Code, you can tell Claude to allow it:
+
+```
+You: allow the dangerouslySetInnerHTML one
+Claude: One-time (this commit only) or permanent?
+You: permanent
+Claude: What's the reason?
+You: sanitized with DOMPurify
+```
+
+- **One-time**: temporarily adds the entry, commits, then removes it
+- **Permanent**: adds the entry to `.goodvibesonly.json` for you to commit later
+
+### List All Patterns
+
+```bash
+node bin/scan.js --list-patterns
+```
+
 ## How It's Different
 
-- **Actually enforces** - Uses Claude Code hooks to block commits, not just advisory
+- **Actually enforces** - Uses Claude Code's PreToolUse hooks to block commits, not just advisory
 - **Real scanning** - Node.js script with regex patterns, not just instructions for Claude
-- **Zero config** - Installs hooks automatically
+- **Zero config** - Installs hooks automatically into Claude Code's settings
 - **Uninstall support** - Clean removal with `--uninstall`
 
 ## Technical Details
 
-GoodVibesOnly installs a `PreToolUse` hook that intercepts Bash commands. When it detects `git commit` or `git push`:
+GoodVibesOnly installs a `PreToolUse` hook in Claude Code's settings. This hook runs before every Bash tool call that Claude Code makes. When the scanner detects the command is a `git commit` or `git push`:
 
 1. Reads staged files via `git diff --cached --name-only`
 2. Scans each file against vulnerability patterns
 3. Outputs findings to stderr
-4. Exits with code 2 to block (critical issues) or 0 to allow
+4. Exits with code 2 to block Claude Code from running the command (critical issues) or 0 to allow it
+
+For non-git commands, the scanner exits immediately with code 0 (allow).
 
-The hook is configured in `~/.claude/settings.json`:
+The hook is configured in Claude Code's `settings.json`:
 
 ```json
 {

package/bin/scan.js

@@ -95,6 +95,58 @@ const SCANNABLE_EXTENSIONS = new Set([
   '.config', '.conf', '.cfg', '.ini'
 ]);
 
+function matchGlob(filePath, globPattern) {
+  // Convert glob pattern to regex
+  let regex = globPattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape special regex chars (not * and ?)
+    .replace(/\*\*/g, '\0')               // Temp placeholder for **
+    .replace(/\*/g, '[^/]*')              // * matches anything except /
+    .replace(/\0/g, '.*')                 // ** matches anything including /
+    .replace(/\?/g, '[^/]');              // ? matches single non-/ char
+  return new RegExp(`^${regex}$`).test(filePath);
+}
+
+function loadAllowlist() {
+  const configPath = path.join(process.cwd(), '.goodvibesonly.json');
+  try {
+    if (!fs.existsSync(configPath)) return { allow: [] };
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const config = JSON.parse(raw);
+    if (!Array.isArray(config.allow)) {
+      console.error('Warning: .goodvibesonly.json "allow" is not an array, ignoring');
+      return { allow: [] };
+    }
+    for (const entry of config.allow) {
+      if (!entry.reason) {
+        console.error(`Warning: allowlist entry missing "reason": ${JSON.stringify(entry)}`);
+      }
+    }
+    return config;
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      console.error(`Warning: .goodvibesonly.json has invalid JSON, ignoring: ${err.message}`);
+    }
+    return { allow: [] };
+  }
+}
+
+function isAllowed(patternName, filePath, allowlist) {
+  if (!allowlist || !allowlist.allow) return false;
+  for (const entry of allowlist.allow) {
+    const hasPattern = 'pattern' in entry;
+    const hasPath = 'path' in entry;
+
+    if (hasPattern && hasPath) {
+      if (entry.pattern === patternName && matchGlob(filePath, entry.path)) return true;
+    } else if (hasPattern) {
+      if (entry.pattern === patternName) return true;
+    } else if (hasPath) {
+      if (matchGlob(filePath, entry.path)) return true;
+    }
+  }
+  return false;
+}
+
 function shouldScanFile(filePath) {
   const ext = path.extname(filePath).toLowerCase();
   const basename = path.basename(filePath).toLowerCase();
@@ -108,7 +160,7 @@ function shouldScanFile(filePath) {
   return SCANNABLE_EXTENSIONS.has(ext);
 }
 
-function scanFile(filePath) {
+function scanFile(filePath, allowlist) {
   const findings = [];
 
   if (!fs.existsSync(filePath)) return findings;
@@ -137,6 +189,8 @@ function scanFile(filePath) {
         const matches = line.match(regex);
 
         if (matches) {
+          if (isAllowed(name, filePath, allowlist)) return;
+
           findings.push({
             severity,
             type: name,
@@ -165,7 +219,7 @@ function getChangedFiles(staged = true) {
   }
 }
 
-function formatFindings(findings) {
+function formatFindings(findings, allowlist) {
   const bySeverity = { critical: [], high: [], medium: [] };
 
   for (const f of findings) {
@@ -177,6 +231,9 @@ function formatFindings(findings) {
   const total = findings.length;
   if (total === 0) {
     output += '✓ No security issues found\n';
+    if (allowlist && allowlist.allow.length > 0) {
+      output += `  (${allowlist.allow.length} allowlist rule${allowlist.allow.length === 1 ? '' : 's'} active)\n`;
+    }
     return output;
   }
 
@@ -208,11 +265,34 @@ function formatFindings(findings) {
 
   output += `Found ${bySeverity.critical.length} critical, ${bySeverity.high.length} high, ${bySeverity.medium.length} medium issues.\n`;
 
+  if (allowlist && allowlist.allow.length > 0) {
+    output += `(${allowlist.allow.length} allowlist rule${allowlist.allow.length === 1 ? '' : 's'} active — some findings may be suppressed)\n`;
+  }
+
   return output;
 }
 
+function listPatterns() {
+  let output = 'GoodVibesOnly Scanner — All Pattern Names\n\n';
+  for (const [severity, patterns] of Object.entries(PATTERNS)) {
+    output += `${severity.toUpperCase()}:\n`;
+    for (const { name } of patterns) {
+      output += `  - ${name}\n`;
+    }
+    output += '\n';
+  }
+  output += `Total: ${Object.values(PATTERNS).reduce((sum, p) => sum + p.length, 0)} patterns\n`;
+  console.log(output);
+}
+
 async function main() {
   const args = process.argv.slice(2);
+
+  if (args.includes('--list-patterns')) {
+    listPatterns();
+    process.exit(0);
+  }
+
   let files = [];
   let isHook = false;
 
@@ -278,15 +358,18 @@ async function main() {
     process.exit(0);
   }
 
+  // Load allowlist
+  const allowlist = loadAllowlist();
+
   // Scan all files
   const allFindings = [];
   for (const file of files) {
-    const findings = scanFile(file);
+    const findings = scanFile(file, allowlist);
     allFindings.push(...findings);
   }
 
   // Output results
-  const output = formatFindings(allFindings);
+  const output = formatFindings(allFindings, allowlist);
 
   const criticalCount = allFindings.filter(f => f.severity === 'critical').length;
 

package/commands/goodvibesonly.md

@@ -81,6 +81,39 @@ If clean:
 ✓ GoodVibesOnly passed - no security issues found in [N] files
 ```
 
+## Allowlist: `.goodvibesonly.json`
+
+Users can suppress specific findings by adding entries to `.goodvibesonly.json` in the project root:
+
+```json
+{
+  "allow": [
+    { "pattern": "XSS via dangerouslySetInnerHTML", "reason": "Sanitized with DOMPurify" },
+    { "path": "test/**", "reason": "Test files contain intentional patterns" },
+    { "pattern": "SQL Injection", "path": "src/db/raw.js", "reason": "Parameterized at call site" }
+  ]
+}
+```
+
+- `pattern` only: suppress that pattern in all files
+- `path` only: suppress all patterns in matching files (supports `*` and `**` globs)
+- `pattern` + `path`: suppress specific pattern in specific files
+- Every entry should have a `reason`
+- Pattern names must match exactly — run `node bin/scan.js --list-patterns` to see all names
+
+### Allowing Findings in Conversation
+
+When a user wants to allow a finding:
+
+1. Ask: **one-time** (this commit only) or **permanent**?
+2. Ask for a reason
+
+**One-time**: Write entry to `.goodvibesonly.json` (don't stage it), re-run commit, then remove the entry afterward.
+
+**Permanent**: Write entry to `.goodvibesonly.json`, re-run commit, leave the file for user to commit later.
+
+Always show the user exactly what was added to the config.
+
 ## After Scanning
 
 - If CRITICAL issues: Offer to fix them automatically

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goodvibesonly-cc",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Security scanner for vibe-coded projects - Claude Code extension",
   "type": "module",
   "bin": {

package/skills/goodvibesonly/SKILL.md

@@ -91,6 +91,56 @@ http://(?!localhost)              # Non-HTTPS
 1. Brief summary
 2. Proceed with the requested action
 
+## Allowlist Flow
+
+When a user wants to suppress a specific finding, follow this flow:
+
+1. **User says** something like "allow the dangerouslySetInnerHTML one" or "ignore the XSS finding"
+2. **Ask**: "One-time (this commit only) or permanent?"
+3. **Ask for reason**: "What's the reason for allowing this?" (e.g., "Sanitized with DOMPurify")
+
+### One-Time Allow
+
+1. Read existing `.goodvibesonly.json` (or create `{ "allow": [] }` if missing)
+2. Add the temporary entry to the `allow` array
+3. Write the file (**do not** stage it with `git add`)
+4. Re-run the commit command
+5. After commit completes, remove the temporary entry from `.goodvibesonly.json`
+6. If the file is now empty (`{ "allow": [] }`), delete it
+
+### Permanent Allow
+
+1. Read existing `.goodvibesonly.json` (or create `{ "allow": [] }` if missing)
+2. Add the entry to the `allow` array with the user's reason
+3. Write the file (leave it for the user to commit when ready)
+4. Re-run the commit command
+5. Tell the user: "Added permanent allowlist rule. You can commit `.goodvibesonly.json` when ready."
+
+### Config Format: `.goodvibesonly.json`
+
+```json
+{
+  "allow": [
+    { "pattern": "XSS via dangerouslySetInnerHTML", "reason": "Sanitized with DOMPurify" },
+    { "path": "test/**", "reason": "Test files contain intentional patterns" },
+    { "pattern": "SQL Injection", "path": "src/db/raw.js", "reason": "Parameterized at call site" }
+  ]
+}
+```
+
+- `pattern` only: suppress that pattern in all files
+- `path` only: suppress all patterns in matching files (supports `*` and `**` globs)
+- `pattern` + `path`: suppress specific pattern in specific files
+- Pattern names must match exactly — run `node bin/scan.js --list-patterns` to see all names
+
+### Show the User What Changed
+
+After adding an entry, show the user what was added:
+```
+Added to .goodvibesonly.json:
+  { "pattern": "XSS via dangerouslySetInnerHTML", "reason": "Sanitized with DOMPurify" }
+```
+
 ## Example Output
 
 ```