@safetnsr/vet 1.3.0 → 1.5.0

package/README.md

@@ -1,26 +1,63 @@
 # vet
 
-vet your AI-generated code. one command, nine checks, zero config.
+your AI coding agent doesn't know what it broke. you need a second opinion.
 
 ```bash
 npx @safetnsr/vet
 ```
 
+vet checks your codebase **before** and **after** AI coding sessions. before: is your repo set up so the agent does good work? after: did it leave behind anti-patterns, stale tests, leaked secrets, or technical debt?
+
 works with Claude Code, Cursor, Copilot, Codex, Aider, Windsurf, Cline — anything that writes code in a git repo.
 
-## what it checks
+## two flows, one command
+
+`npx @safetnsr/vet` runs everything. but the checks split into two categories:
+
+### before the session — is your codebase ready?
+
+| check | what it does |
+|-------|-------------|
+| **ready** | scores your codebase structure: docs, types, tests, AI-friendliness |
+| **config** | deep analysis of CLAUDE.md, .cursorrules, copilot-instructions — completeness, consistency, specificity |
+| **scan** | detects prompt injection, shell injection, exfiltration in agent config files |
+| **permissions** | flags MCP servers with dangerous filesystem access (writes to ~/.ssh, /etc, outside cwd) |
+| **models** | finds deprecated/sunset model strings across OpenAI, Anthropic, Google, Cohere |
+| **map** | verifies your codebase has navigable structure for agents |
+| **memory** | catches stale facts, contradictions, and drift in CLAUDE.md, AGENTS.md, memory/ files |
+
+a codebase that scores well here gives AI agents better context, fewer hallucinations, and less cleanup.
+
+### after the session — did the AI leave problems?
+
+| check | what it does |
+|-------|-------------|
+| **diff** | AI-specific anti-patterns: wholesale rewrites, orphaned imports, catch-all error handling, over-commenting |
+| **tests** | test theater: tautological assertions, empty test bodies, tests that prove nothing |
+| **debt** | near-duplicate functions, orphaned exports, wrapper pass-throughs, naming drift |
+| **secrets** | scans dist/, build/, .next/ + .env files for leaked API keys using pattern + entropy analysis |
+| **history** | git commit churn, AI attribution ratios, suspiciously large changes |
+| **receipt** | parses Claude Code session logs — files changed, commands run, packages installed, SHA256 integrity hash |
+
+plus: **integrity** (hallucinated imports), **deps** (unused/phantom dependencies), **owasp** (OWASP Top 10 for AI agents), **verify** (validates agent claims against actual changes).
+
+## output
+
+```
+  my-project  B  75/100
+
+  security     ████████░░  82   scan ✓  secrets ✓  config 3/10  owasp ✓
+  integrity    ███████░░░  68   diff: 3 issues  integrity ✓  memory: 1 stale
+  debt         ██████░░░░  58   ready 4/10  history ✓  debt: 2 duplicates
+  deps         ██████████  98   all clean
+
+  ✗ no README — AI agents have no project context
+  ✗ [ai] wholesale rewrite: 40 lines removed, 45 added in utils.ts
+  ! config: "strict TS" but tsconfig.strict is false
+  ! memory: CLAUDE.md references vitest but package.json uses jest
 
-| check | what | how |
-|-------|------|-----|
-| **ready** | is your codebase AI-friendly? | scans structure, docs, types, tests |
-| **diff** | did the AI leave anti-patterns? | AI-specific patterns: wholesale rewrites, orphaned imports, catch-alls, over-commenting, plus secrets & stubs |
-| **models** | using deprecated AI models? | scans code for sunset model strings across OpenAI, Anthropic, Google, Cohere |
-| **config** | agent configs in place? | deep analysis of CLAUDE.md, .cursorrules, copilot-instructions — checks completeness, consistency, and specificity against your actual codebase |
-| **history** | git patterns healthy? | analyzes commit churn, AI attribution, large changes |
-| **scan** | malicious patterns in agent configs? | scans .claude/, .cursorrules, CLAUDE.md, .mcp/ for prompt injection, shell injection, exfiltration endpoints |
-| **secrets** | leaked secrets in build output? | scans dist/, build/, .next/ + .env files for API keys, tokens, connection strings using pattern + entropy analysis |
-| **receipt** | what did the last agent session do? | parses ~/.claude/projects/ JSONL session logs — files changed, commands run, packages installed, SHA256 integrity hash |
-| **debt** | AI-generated technical debt (duplicates, orphans, wrappers) | detects near-duplicate functions, orphaned exports, wrapper pass-throughs, naming drift |
+  run --fix to auto-repair 4 issues
+```
 
 ## usage
 
@@ -28,19 +65,19 @@ works with Claude Code, Cursor, Copilot, Codex, Aider, Windsurf, Cline — anyth
 # run all checks
 npx @safetnsr/vet
 
-# check a specific directory
+# specific directory
 npx @safetnsr/vet ./my-project
 
 # auto-fix: generate CLAUDE.md, .cursorrules, fix deprecated models
 npx @safetnsr/vet --fix
 
-# check specific commit range
+# specific commit range
 npx @safetnsr/vet --since HEAD~5
 
 # live monitoring during AI sessions
 npx @safetnsr/vet --watch
 
-# CI mode — exit code 1 if score below threshold
+# CI mode — exit 1 if score below threshold
 npx @safetnsr/vet --ci
 
 # JSON output
@@ -49,78 +86,72 @@ npx @safetnsr/vet --json
 # generate configs + pre-commit hook
 npx @safetnsr/vet init
 
-# show last agent session receipt (ASCII or JSON)
+# agent session receipt
 npx @safetnsr/vet receipt
 npx @safetnsr/vet receipt --json
 ```
 
-## output
-
-```
-  my-project  7.5/10
-
-  ready       ████░░░░░░   4    3 readiness issues
-  diff        ████████░░   8    3 issues (2 AI-specific) in 5 files
-  models      ██████████  10    all models current
-  config      ███░░░░░░░   3    Cursor — needs work (3/10)
-  history     █████████░   9    41 commits (~15% AI-attributed)
-  scan        ██████████  10    no malicious patterns found
-  secrets     ██████████  10    no leaked secrets
-  receipt     ██████████  10    last session: 3 files, 2 commands
-
-  ✗ no README — AI agents have no project context
-  ✗ no tests — AI agents produce better code when tests exist
-  ! [ai] wholesale rewrite: 40 lines removed, 45 added in utils.ts
-  ! [ai] imported "lodash" but never used in new code
-
-  run --fix to auto-repair 4 issues
-```
-
 ## --fix
 
-`vet --fix` analyzes your codebase and generates project-specific configs:
+analyzes your codebase and generates project-specific configs:
 
 ```bash
 $ npx @safetnsr/vet --fix
 
   vet --fix
 
-  + CLAUDE.md (generated from codebase: Next.js + React, Vitest, Tailwind CSS, TypeScript)
+  + CLAUDE.md (generated: Next.js + React, Vitest, Tailwind CSS, TypeScript)
   + .cursorrules (generated)
   ✓ src/api.ts: "gpt-3.5-turbo" → "gpt-4o-mini"
 
   fixed 3 issues
 ```
 
-the generated CLAUDE.md includes your actual stack, directory structure, and framework-specific rules.
+the generated CLAUDE.md includes your actual stack, directory structure, and framework-specific rules — not a template.
 
-## AI-specific diff patterns
+## --watch
 
-| pattern | what it catches |
-|---------|----------------|
-| `[ai] wholesale rewrite` | AI rewrote an entire function when a small edit would suffice |
-| `[ai] orphaned imports` | AI added imports it never uses |
-| `[ai] catch-all handling` | `catch(e) { console.error(e) }` instead of specific error handling |
-| `[ai] comment density` | AI over-commented obvious code |
-| `[ai] empty test body` | AI stubbed a test without implementation |
-| `[ai] trivial assertion` | `expect(true).toBe(true)` — test proves nothing |
+monitors your repo during an active AI session. re-runs checks on every file change:
 
-## config analysis
+```bash
+npx @safetnsr/vet --watch
+```
 
-the config check does deep analysis — not just "does CLAUDE.md exist":
+catch problems as the agent creates them, not after it's done.
 
-```
-config score breakdown:
-  completeness:  4/10 — mentions typescript but not react, vitest
-  consistency:   7/10 — "strict TS" but tsconfig.strict is false
-  specificity:   3/10 — generic rules, nothing project-specific
+## CI/CD
+
+```yaml
+# .github/workflows/vet.yml
+name: vet
+on: [pull_request]
+jobs:
+  vet:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 50
+      - run: npx @safetnsr/vet --ci
 ```
 
-## subcommands
+GitHub Action: [`safetnsr/vet-action`](https://github.com/safetnsr/vet-action) (coming soon)
 
-### `vet receipt`
+## config
 
-Shows a receipt for the last Claude Code agent session — what files it touched, what commands it ran, what packages it installed, plus a SHA256 integrity hash:
+optional `.vetrc` in your project root:
+
+```json
+{
+  "checks": ["ready", "diff", "models", "config", "scan", "secrets"],
+  "ignore": ["vendor/", "generated/"],
+  "thresholds": { "min": 60 }
+}
+```
+
+## receipt
+
+shows what the last Claude Code session actually did — files touched, commands run, packages installed, with a SHA256 integrity hash:
 
 ```
 ╔══════════════════════════════════════════════╗
@@ -139,34 +170,6 @@ Shows a receipt for the last Claude Code agent session — what files it touched
 ╚══════════════════════════════════════════════╝
 ```
 
-## config
-
-create `.vetrc` in your project root (optional):
-
-```json
-{
-  "checks": ["ready", "diff", "models", "config", "history", "scan", "secrets", "receipt"],
-  "ignore": ["vendor/", "generated/"],
-  "thresholds": { "min": 6 }
-}
-```
-
-## ci
-
-```yaml
-# .github/workflows/vet.yml
-name: vet
-on: [pull_request]
-jobs:
-  vet:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 50
-      - run: npx @safetnsr/vet --ci
-```
-
 ## zero dependencies
 
 vet uses only Node.js built-ins. no runtime dependencies. works with Node 18+.

package/dist/checks/permissions.d.ts

@@ -0,0 +1,2 @@
+import type { CheckResult } from '../types.js';
+export declare function checkPermissions(cwd: string): CheckResult;

package/dist/checks/permissions.js

@@ -0,0 +1,248 @@
+import { join, resolve, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { readFile, fileExists } from '../util.js';
+// ── Sensitive directories that trigger DANGER if MCP server writes there ──
+const SENSITIVE_DIRS = [
+    '~/.ssh',
+    '~/.aws',
+    '/etc',
+    '/var/www',
+];
+function expandHome(p) {
+    if (p.startsWith('~/'))
+        return join(homedir(), p.slice(2));
+    if (p === '~')
+        return homedir();
+    return p;
+}
+function isSensitiveDir(p) {
+    const expanded = expandHome(p);
+    return SENSITIVE_DIRS.some(d => {
+        const expandedSensitive = expandHome(d);
+        return expanded === expandedSensitive || expanded.startsWith(expandedSensitive + '/');
+    });
+}
+function isOutsideCwd(p, cwd) {
+    const expanded = expandHome(p);
+    const abs = isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
+    const resolvedCwd = resolve(cwd);
+    return !abs.startsWith(resolvedCwd + '/') && abs !== resolvedCwd;
+}
+/** Score helper */
+function applyPenalty(score, severity) {
+    const penalties = { error: 30, warning: 15, info: 5 };
+    return Math.max(0, score - penalties[severity]);
+}
+// ── A. Scan .claude/settings.json ─────────────────────────────────────────
+function checkSettingsJson(cwd, issues) {
+    const settingsPath = join(cwd, '.claude', 'settings.json');
+    if (!fileExists(settingsPath))
+        return;
+    const raw = readFile(settingsPath);
+    if (!raw)
+        return;
+    let settings;
+    try {
+        settings = JSON.parse(raw);
+    }
+    catch {
+        issues.push({
+            severity: 'warning',
+            message: '.claude/settings.json is not valid JSON — cannot audit permissions',
+            file: '.claude/settings.json',
+            fixable: false,
+        });
+        return;
+    }
+    // allowedTools containing bare "Bash" or "Bash(*)"
+    const allowedTools = settings.allowedTools;
+    if (Array.isArray(allowedTools)) {
+        for (const tool of allowedTools) {
+            if (typeof tool === 'string') {
+                if (tool === 'Bash' || tool === 'Bash(*)') {
+                    issues.push({
+                        severity: 'error',
+                        message: `allowedTools contains "${tool}" without path restrictions — unrestricted shell access`,
+                        file: '.claude/settings.json',
+                        fixable: true,
+                        fixHint: `Replace "${tool}" with specific allowed commands, e.g. "Bash(npm run *)"`,
+                    });
+                }
+            }
+        }
+    }
+    // permissions.allow with wildcards
+    const permissions = settings.permissions;
+    if (permissions && Array.isArray(permissions.allow)) {
+        for (const rule of permissions.allow) {
+            if (typeof rule === 'string' && (rule === 'Bash(*)' || rule === '**' || rule.includes('**'))) {
+                issues.push({
+                    severity: 'error',
+                    message: `permissions.allow contains wildcard "${rule}" — grants broad access`,
+                    file: '.claude/settings.json',
+                    fixable: true,
+                    fixHint: 'Remove wildcard rules and enumerate specific allowed operations',
+                });
+            }
+        }
+    }
+    // defaultMode: "bypassPermissions"
+    if (settings.defaultMode === 'bypassPermissions') {
+        issues.push({
+            severity: 'error',
+            message: 'defaultMode is "bypassPermissions" — skips all permission checks',
+            file: '.claude/settings.json',
+            fixable: true,
+            fixHint: 'Remove defaultMode or set to "default"',
+        });
+    }
+    // No blockedTools or deny list
+    const hasBlockedTools = Array.isArray(settings.blockedTools) && settings.blockedTools.length > 0;
+    const hasDenyList = permissions && Array.isArray(permissions.deny) && permissions.deny.length > 0;
+    if (!hasBlockedTools && !hasDenyList) {
+        issues.push({
+            severity: 'warning',
+            message: 'No blockedTools or deny list defined — all unlisted tools remain available',
+            file: '.claude/settings.json',
+            fixable: true,
+            fixHint: 'Add blockedTools: ["Bash", "Write"] to restrict dangerous operations',
+        });
+    }
+    // ── B. MCP server configs ────────────────────────────────────────────────
+    checkMcpServers(cwd, settings, '.claude/settings.json', issues);
+}
+// ── B. MCP server analysis ─────────────────────────────────────────────────
+function checkMcpServers(cwd, settings, filePath, issues) {
+    const mcpServers = settings.mcpServers;
+    if (!mcpServers || typeof mcpServers !== 'object')
+        return;
+    for (const [serverName, serverConfig] of Object.entries(mcpServers)) {
+        if (typeof serverConfig !== 'object' || serverConfig === null)
+            continue;
+        const config = serverConfig;
+        // Check server args for filesystem paths
+        const args = config.args;
+        const isFilesystemServer = (typeof config.command === 'string' && config.command.includes('filesystem')) ||
+            (Array.isArray(args) && args.some((a) => typeof a === 'string' && a.includes('filesystem')));
+        // Detect if server is read-only
+        const isReadOnly = Array.isArray(args) && args.some((a) => typeof a === 'string' && (a === '--read-only' || a === 'readonly' || a === '--readonly'));
+        // Collect root paths from args
+        const rootPaths = [];
+        if (Array.isArray(args)) {
+            for (const arg of args) {
+                if (typeof arg === 'string' && !arg.startsWith('-') && (arg.startsWith('/') || arg.startsWith('~/') || arg.startsWith('.'))) {
+                    rootPaths.push(arg);
+                }
+            }
+        }
+        // Also check explicit root config
+        if (typeof config.root === 'string') {
+            rootPaths.push(config.root);
+        }
+        if (Array.isArray(config.roots)) {
+            for (const r of config.roots) {
+                if (typeof r === 'string')
+                    rootPaths.push(r);
+            }
+        }
+        if (rootPaths.length === 0) {
+            // No path restrictions at all
+            issues.push({
+                severity: 'warning',
+                message: `MCP server "${serverName}" has no explicit path restrictions`,
+                file: filePath,
+                fixable: true,
+                fixHint: `Add root path restriction to "${serverName}" in mcpServers config`,
+            });
+            continue;
+        }
+        for (const rootPath of rootPaths) {
+            // Check sensitive directory access
+            if (isSensitiveDir(rootPath)) {
+                issues.push({
+                    severity: 'error',
+                    message: `MCP server "${serverName}" has access to sensitive directory: ${rootPath}`,
+                    file: filePath,
+                    fixable: true,
+                    fixHint: `Remove sensitive path "${rootPath}" from MCP server config`,
+                });
+                continue;
+            }
+            // Check if root is outside cwd and not read-only
+            if (isOutsideCwd(rootPath, cwd) && !isReadOnly) {
+                issues.push({
+                    severity: 'error',
+                    message: `MCP server "${serverName}" has write access outside project dir: ${rootPath}`,
+                    file: filePath,
+                    fixable: true,
+                    fixHint: `Restrict to project directory or add --read-only flag`,
+                });
+            }
+        }
+    }
+}
+// ── C. CLAUDE.md and AGENTS.md text heuristics ────────────────────────────
+const DANGEROUS_PHRASES = [
+    /full\s+access/i,
+    /unrestricted/i,
+    /\bsudo\b/i,
+    /skip\s+confirmation/i,
+    /no\s+restrictions/i,
+];
+function checkMarkdownFiles(cwd, issues) {
+    for (const filename of ['CLAUDE.md', 'AGENTS.md']) {
+        const filePath = join(cwd, filename);
+        if (!fileExists(filePath))
+            continue;
+        const content = readFile(filePath);
+        if (!content)
+            continue;
+        const lines = content.split('\n');
+        for (const pattern of DANGEROUS_PHRASES) {
+            for (let i = 0; i < lines.length; i++) {
+                if (pattern.test(lines[i])) {
+                    const matchText = lines[i].match(pattern)?.[0] ?? pattern.source;
+                    issues.push({
+                        severity: 'warning',
+                        message: `${filename} contains potentially dangerous instruction: "${matchText.trim()}"`,
+                        file: filename,
+                        line: i + 1,
+                        fixable: false,
+                        fixHint: `Review line ${i + 1} in ${filename} — ensure it doesn't grant unintended permissions`,
+                    });
+                    break; // one issue per pattern per file
+                }
+            }
+        }
+    }
+}
+// ── Main export ────────────────────────────────────────────────────────────
+export function checkPermissions(cwd) {
+    const issues = [];
+    checkSettingsJson(cwd, issues);
+    checkMarkdownFiles(cwd, issues);
+    // Score: start at 100, deduct per issue
+    let score = 100;
+    for (const issue of issues) {
+        score = applyPenalty(score, issue.severity);
+    }
+    const errorCount = issues.filter(i => i.severity === 'error').length;
+    const warnCount = issues.filter(i => i.severity === 'warning').length;
+    let summary;
+    if (issues.length === 0) {
+        summary = 'no dangerous permission grants detected';
+    }
+    else if (errorCount > 0) {
+        summary = `${errorCount} dangerous grant${errorCount !== 1 ? 's' : ''} detected — review before running agent`;
+    }
+    else {
+        summary = `${warnCount} permission warning${warnCount !== 1 ? 's' : ''} — tighten config before agent session`;
+    }
+    return {
+        name: 'permissions',
+        score,
+        maxScore: 100,
+        issues,
+        summary,
+    };
+}

package/dist/cli.js

@@ -18,6 +18,7 @@ import { checkMemory } from './checks/memory.js';
 import { checkVerify } from './checks/verify.js';
 import { checkTests } from './checks/tests.js';
 import { checkMap, renderMapReport } from './checks/map.js';
+import { checkPermissions } from './checks/permissions.js';
 import { score } from './scorer.js';
 import { reportPretty, reportJSON, reportBadge } from './reporter.js';
 const args = process.argv.slice(2);
@@ -49,6 +50,7 @@ if (flags.has('--help') || flags.has('-h')) {
     npx @safetnsr/vet init               generate configs + hooks
     npx @safetnsr/vet receipt            show last agent session receipt
     npx @safetnsr/vet map [dir]          show agent visibility map
+    npx @safetnsr/vet permissions [dir]  audit Claude Code config for dangerous grants
 
   ${c.dim}categories:${c.reset}
     security   (30%)  scan, secrets, config, model usage
@@ -83,7 +85,7 @@ if (flags.has('--version') || flags.has('-v')) {
     }
     process.exit(0);
 }
-const COMMANDS = ['init', 'receipt', 'map'];
+const COMMANDS = ['init', 'receipt', 'map', 'permissions'];
 const command = COMMANDS.includes(positional[0]) ? positional[0] : undefined;
 const cwd = resolve(positional.find(p => !COMMANDS.includes(p)) || '.');
 const isCI = flags.has('--ci');
@@ -123,6 +125,30 @@ if (command === 'map') {
     }
     process.exit(0);
 }
+if (command === 'permissions') {
+    const result = checkPermissions(cwd);
+    if (isJSON) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(`\n  ${c.bold}vet permissions${c.reset} — ${result.summary}\n`);
+        console.log(`  score: ${result.score}/100\n`);
+        if (result.issues.length === 0) {
+            console.log(`  ${c.green}no issues found${c.reset}\n`);
+        }
+        else {
+            for (const issue of result.issues) {
+                const icon = issue.severity === 'error' ? c.red + '✗' : issue.severity === 'warning' ? c.yellow + '⚠' : c.dim + 'i';
+                const loc = issue.file ? ` ${c.dim}(${issue.file}${issue.line ? `:${issue.line}` : ''})${c.reset}` : '';
+                console.log(`  ${icon}${c.reset} ${issue.message}${loc}`);
+                if (issue.fixHint)
+                    console.log(`    ${c.dim}→ ${issue.fixHint}${c.reset}`);
+            }
+            console.log('');
+        }
+    }
+    process.exit(result.score < 60 ? 1 : 0);
+}
 if (!isGitRepo(cwd)) {
     console.error(`${c.red}not a git repository${c.reset}. vet operates on git repos.`);
     process.exit(1);
@@ -145,7 +171,7 @@ if (isFix) {
 }
 async function runChecks() {
     // Run all checks, grouped into categories
-    // Security: scan, secrets, config, models, owasp
+    // Security: scan, secrets, config, models, owasp, permissions
     const [scanResult, secretsResult, configResult, modelsResult, owaspResult] = await Promise.all([
         Promise.resolve(checkScan(cwd)),
         checkSecrets(cwd),
@@ -153,6 +179,7 @@ async function runChecks() {
         checkModels(cwd, ignore),
         Promise.resolve(checkOwasp(cwd)),
     ]);
+    const permissionsResult = checkPermissions(cwd);
     // Integrity: diff, integrity checks
     const diffResult = checkDiff(cwd, { since });
     const integrityResult = await checkIntegrity(cwd, ignore);
@@ -173,7 +200,7 @@ async function runChecks() {
     // Tests: test theater detection
     const testsResult = checkTests(cwd, ignore);
     return score(cwd, {
-        security: [scanResult, secretsResult, configResult, modelsResult, owaspResult],
+        security: [scanResult, secretsResult, configResult, modelsResult, owaspResult, permissionsResult],
         integrity: [diffResult, integrityResult, receiptResult, memoryResult, verifyResult, testsResult],
         debt: [readyResult, historyResult, debtResult],
         deps: [depsResult],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@safetnsr/vet",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "vet your AI-generated code — one command, one score card, one letter grade",
   "type": "module",
   "bin": {