shipready 1.5.0 → 1.5.2

package/README.md

@@ -4,7 +4,6 @@
 
 [![CI](https://github.com/formalness/shipready/actions/workflows/ci.yml/badge.svg)](https://github.com/formalness/shipready/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/shipready.svg)](https://www.npmjs.com/package/shipready)
-[![tests](https://img.shields.io/badge/tests-179%20passing-brightgreen.svg)](https://github.com/formalness/shipready/tree/main/tests)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
 
@@ -215,7 +214,8 @@ The scanner combines provider-specific patterns with **Shannon entropy analysis*
 | Stripe (test) | `sk_test_`, `pk_test_` |
 | JWT | `eyJ...` with valid structure |
 | Generic credential | `API_KEY=`, `SECRET=`, `PASSWORD=` assignments — only when the value has high entropy |
-| Any finding in test/fixture/mock files | automatically downgraded |
+| Generic-pattern findings (opaque assignments, URLs, JWTs) in test/fixture/mock files | automatically downgraded |
+| Provider-prefixed keys (`AKIA...`, `ghp_...`, `sk-ant-...`) in test files | kept at full severity |
 
 False-positive protection:
 
@@ -363,13 +363,26 @@ pnpm dev      # run the CLI from source (tsx)
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for project structure and how to add new checks or secret patterns.
 
+## How does it compare to gitleaks?
+
+Measured head-to-head on a corpus of 7 real-format leaks and 10 false-positive baits (gitleaks v8.24.3):
+
+| | shipready | gitleaks |
+| --- | --- | --- |
+| Real leaks caught | **7 / 7** | 4 / 7 |
+| Error-level false positives | **0** | 1 |
+| Newer key formats (`sk-proj-`, `sk-ant-`) | ✓ | missed |
+| Committed `.env.backup` | ✓ | partial |
+
+gitleaks remains more battle-tested for deep git-history forensics with hundreds of rules. shipready covers the leaks that actually happen in modern AI-assisted projects — plus README, env hygiene, and code hygiene that gitleaks doesn't check at all. Full methodology, fairness notes, and reproduction steps: [BENCHMARK.md](./BENCHMARK.md).
+
 ## Roadmap
 
 - [x] `shipready staged` for pre-commit hooks
 - [x] SARIF report output for GitHub code scanning
 - [x] Git history scanning (`--history`)
 - [x] Live key verification (`--verify`)
-- [ ] Benchmark against gitleaks/trufflehog with published numbers
+- [x] Benchmark against gitleaks with published numbers ([BENCHMARK.md](./BENCHMARK.md))
 - [ ] Framework-aware scoring (Next.js vs Vite vs Python have different needs)
 - [ ] Optional AI-powered fix suggestions (bring your own key)
 

package/dist/checks/secrets.js

@@ -76,11 +76,13 @@ const PATTERNS = [
     },
     {
         kind: "Twilio credential",
+        generic: true,
         re: /\b(?:AC|SK)[a-f0-9]{32}\b/,
         confidence: "high",
     },
     {
         kind: "Telegram bot token",
+        generic: true,
         re: /\b\d{8,10}:[A-Za-z0-9_-]{35}\b/,
         confidence: "high",
     },
@@ -107,11 +109,13 @@ const PATTERNS = [
     },
     {
         kind: "Mailchimp key",
+        generic: true,
         re: /\b[a-f0-9]{32}-us\d{1,2}\b/,
         confidence: "high",
     },
     {
         kind: "Mailgun key",
+        generic: true,
         re: /\bkey-[a-f0-9]{32}\b/,
         confidence: "high",
     },
@@ -189,6 +193,7 @@ const PATTERNS = [
     },
     {
         kind: "Discord bot token",
+        generic: true,
         re: /\b[MNO][A-Za-z\d_-]{23,25}\.[A-Za-z\d_-]{6}\.[A-Za-z\d_-]{27,}\b/,
         confidence: "medium",
         minEntropy: 4.0,
@@ -198,6 +203,7 @@ const PATTERNS = [
         // documentation hosts like db.example.com don't suppress real leaks.
         // The host (group 2) downgrades localhost URLs to medium confidence.
         kind: "Database URL with password",
+        generic: true,
         re: /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|rediss|amqp):\/\/[^:\s"'@/]+:([^@\s"']+)@([^\s"'/:?]+)/,
         confidence: "high",
         group: 1,
@@ -205,6 +211,7 @@ const PATTERNS = [
     },
     {
         kind: "Basic auth in URL",
+        generic: true,
         re: /https?:\/\/[^:\s"'/@]{3,}:([^@\s"']{8,})@([^\s"'/:?]+)/,
         confidence: "medium",
         group: 1,
@@ -213,12 +220,14 @@ const PATTERNS = [
     },
     {
         kind: "JWT",
+        generic: true,
         re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/,
         confidence: "medium",
         minEntropy: 4.0,
     },
     {
         kind: "Authorization header",
+        generic: true,
         re: /\b(?:authorization|x-api-key)["']?\s*[:=]\s*["']?(?:Bearer|Basic|token)\s+([A-Za-z0-9+/_.=-]{20,})\b/i,
         confidence: "medium",
         group: 1,
@@ -227,11 +236,24 @@ const PATTERNS = [
     {
         // Credential-style assignment with a long opaque quoted value
         kind: "Hardcoded credential",
+        generic: true,
         re: /\b[A-Z0-9_]*(?:API_?KEY|SECRET(?:_KEY)?|ACCESS_TOKEN|AUTH_TOKEN|PASSWORD|PASSWD|CREDENTIALS?)[A-Z0-9_]*\s*[=:]\s*["']([A-Za-z0-9+/_.=-]{16,})["']/i,
         confidence: "medium",
         group: 1,
         minEntropy: 3.8,
     },
+    {
+        // Unquoted dotenv-style assignment (KEY=value at line start). Catches
+        // committed .env backups where values carry no quotes - a gap found by
+        // benchmarking against gitleaks. Anchored to line start so ordinary
+        // code assignments (always quoted) don't double-match.
+        kind: "Hardcoded credential",
+        generic: true,
+        re: /^[A-Z0-9_]*(?:API_?KEY|SECRET(?:_KEY)?|ACCESS_TOKEN|AUTH_TOKEN|PASSWORD|PASSWD|CREDENTIALS?)[A-Z0-9_]*=([A-Za-z0-9+/_.=-]{16,})\s*$/,
+        confidence: "medium",
+        group: 1,
+        minEntropy: 3.8,
+    },
 ];
 /** Words and shapes that indicate a placeholder, not a real secret. */
 const PLACEHOLDER_VALUE_RE = /your[-_ ]?|example|sample|placeholder|change[-_ ]?me|dummy|fake|insert|replace|redacted|deadbeef|lorem|goes[-_ ]?here|test[-_ ]?key|x{4,}|\*{3,}|\.\.\.|123456|abcdef/i;
@@ -273,6 +295,15 @@ export function maskSecret(secret) {
     const suffix = secret.slice(-4);
     return `${prefix}...${suffix}`;
 }
+/**
+ * Global-flag copies of each pattern for matchAll. Compiled once - the
+ * originals stay non-global so .test()/.match() callers keep working.
+ */
+const GLOBAL_PATTERN_RES = PATTERNS.map((p) => new RegExp(p.re.source, p.re.flags.includes("g") ? p.re.flags : `${p.re.flags}g`));
+/** Credential-keyword assignment with no value on the same line. */
+const DANGLING_ASSIGNMENT_RE = /\b[A-Z0-9_]*(?:API_?KEY|SECRET(?:_KEY)?|ACCESS_TOKEN|AUTH_TOKEN|PASSWORD|PASSWD|CREDENTIALS?)[A-Z0-9_]*\s*[=:]\s*$/i;
+/** Quoted opaque value at the start of a continuation line. */
+const CONTINUATION_VALUE_RE = /^\s*["']([A-Za-z0-9+/_.=-]{16,})["']/;
 /** Scans a single file's content for potential secrets. */
 export function scanContentForSecrets(content, file, allowlist = []) {
     const found = [];
@@ -286,43 +317,81 @@ export function scanContentForSecrets(content, file, allowlist = []) {
         // Documentation/example lines are not real leaks.
         if (PLACEHOLDER_LINE_RE.test(line))
             continue;
-        for (const pattern of PATTERNS) {
-            const match = line.match(pattern.re);
-            if (!match)
-                continue;
-            const value = match[pattern.group ?? 0];
-            if (!pattern.skipValueChecks) {
-                if (isPlaceholderValue(value))
+        // Character spans already claimed by a more specific pattern. Patterns
+        // are ordered most specific first, so the first pattern to claim a span
+        // wins - but distinct secrets elsewhere on the same line (e.g. two keys
+        // in one config object) are still reported.
+        const claimed = [];
+        const overlapsClaimed = (start, end) => claimed.some(([s, e]) => start < e && end > s);
+        for (let pi = 0; pi < PATTERNS.length; pi++) {
+            const pattern = PATTERNS[pi];
+            for (const match of line.matchAll(GLOBAL_PATTERN_RES[pi])) {
+                const start = match.index ?? 0;
+                const end = start + match[0].length;
+                if (overlapsClaimed(start, end))
                     continue;
-                if (pattern.minEntropy !== undefined &&
-                    shannonEntropy(value) < pattern.minEntropy) {
+                const value = match[pattern.group ?? 0];
+                if (!pattern.skipValueChecks) {
+                    if (isPlaceholderValue(value))
+                        continue;
+                    if (pattern.minEntropy !== undefined &&
+                        shannonEntropy(value) < pattern.minEntropy) {
+                        continue;
+                    }
+                }
+                // User-configured false positives (substring match on the value or line)
+                if (allowlist.some((a) => match[0].includes(a) || line.includes(a))) {
                     continue;
                 }
+                let effective = pattern.confidence;
+                if (pattern.hostGroup !== undefined) {
+                    // Scaffolding defaults like root:password@localhost are not leaks.
+                    if (COMMON_DEV_PASSWORD_RE.test(value))
+                        continue;
+                    const host = match[pattern.hostGroup] ?? "";
+                    if (LOCAL_HOST_RE.test(host))
+                        effective = "medium";
+                }
+                // Test paths only downgrade shape-based patterns. A provider-prefixed
+                // key that survived the entropy/placeholder gates looks real, and a
+                // real key in a test fixture is just as leaked as one in src/.
+                const confidence = isTestPath && pattern.generic ? "medium" : effective;
+                claimed.push([start, end]);
+                found.push({
+                    kind: pattern.kind,
+                    file,
+                    line: i + 1,
+                    masked: maskSecret(value),
+                    confidence,
+                    // Raw value stays in memory only; used by --verify, never printed.
+                    raw: value,
+                });
             }
-            // User-configured false positives (substring match on the value or line)
-            if (allowlist.some((a) => match[0].includes(a) || line.includes(a))) {
-                continue;
-            }
-            let effective = pattern.confidence;
-            if (pattern.hostGroup !== undefined) {
-                // Scaffolding defaults like root:password@localhost are not leaks.
-                if (COMMON_DEV_PASSWORD_RE.test(value))
-                    continue;
-                const host = match[pattern.hostGroup] ?? "";
-                if (LOCAL_HOST_RE.test(host))
-                    effective = "medium";
+        }
+        // Multiline credential assignment: keyword on one line, quoted value on
+        // the next (formatters wrap long lines this way). Only runs when the
+        // value line alone matches no pattern - provider-prefixed values are
+        // caught by the normal per-line scan on the next iteration.
+        if (i + 1 < lines.length && DANGLING_ASSIGNMENT_RE.test(line)) {
+            const next = lines[i + 1];
+            const valueMatch = next.match(CONTINUATION_VALUE_RE);
+            if (valueMatch &&
+                !PLACEHOLDER_LINE_RE.test(next) &&
+                !PATTERNS.some((p) => p.re.test(valueMatch[1]))) {
+                const value = valueMatch[1];
+                if (!isPlaceholderValue(value) &&
+                    shannonEntropy(value) >= 3.8 &&
+                    !allowlist.some((a) => value.includes(a) || next.includes(a))) {
+                    found.push({
+                        kind: "Hardcoded credential",
+                        file,
+                        line: i + 2,
+                        masked: maskSecret(value),
+                        confidence: "medium",
+                        raw: value,
+                    });
+                }
             }
-            const confidence = isTestPath ? "medium" : effective;
-            found.push({
-                kind: pattern.kind,
-                file,
-                line: i + 1,
-                masked: maskSecret(value),
-                confidence,
-                // Raw value stays in memory only; used by --verify, never printed.
-                raw: value,
-            });
-            break; // one finding per line is enough
         }
     }
     return found;

package/dist/scanner.js

@@ -42,11 +42,18 @@ export function scanFiles(root, files, secretAllowlist = []) {
      * an example is just as dangerous - but hygiene noise is skipped.
      */
     const HYGIENE_EXEMPT_RE = /(?:^|\/)(?:examples?|demos?|benchmarks?|scripts?|playground)\//;
+    /**
+     * Standard env file names that legitimately hold real values and are
+     * expected to be gitignored - the env check owns those. Anything else
+     * that merely starts with ".env" (.env.backup, .env.old, .env.prod)
+     * is a copy someone made and MUST be scanned: benchmark testing showed
+     * gitleaks catches committed .env backups while we used to skip them.
+     */
+    const STANDARD_ENV_RE = /^\.env(?:\.(?:local|development|production|test|staging))?(?:\.local)?$/;
     for (const file of files) {
         const base = path.basename(file);
-        // Never flag .env files themselves for secrets/todos; they are expected
-        // to contain real values and are handled by the env check.
-        const isEnvFile = base.startsWith(".env");
+        const isStandardEnv = STANDARD_ENV_RE.test(base);
+        const isEnvTemplate = base === ".env.example" || base === ".env.sample" || base === ".env.template";
         const ext = path.extname(file).toLowerCase();
         const isCode = CODE_ONLY.has(ext);
         if (isProbablyBinary(root, file))
@@ -60,7 +67,7 @@ export function scanFiles(root, files, secretAllowlist = []) {
                 todos.push(...scanContentForTodos(content, file));
             }
         }
-        if (!isEnvFile && base !== ".env.example" && base !== ".env.sample") {
+        if (!isStandardEnv && !isEnvTemplate) {
             secrets.push(...scanContentForSecrets(content, file, secretAllowlist));
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipready",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Pre-flight check for your repo before shipping. Scans AI-coded projects for secrets, env issues, debug leftovers, and generates AI-agent instruction files.",
   "type": "module",
   "license": "MIT",