cleartoship 0.7.0 → 0.9.0

package/action.yml

@@ -27,9 +27,12 @@ inputs:
     required: false
     default: 'false'
   version:
-    description: Version of the cleartoship npm package to run.
+    description: >-
+      Version of the cleartoship npm package to run. Defaults to the version this
+      action's own ref declares, so `uses: …@v0.9.0` runs cleartoship@0.9.0. Set
+      `latest` to always track the newest release, or `local` to build from the checkout.
     required: false
-    default: latest
+    default: ''
   working-directory:
     description: Directory to run the scan from.
     required: false
@@ -49,9 +52,18 @@ outputs:
   high:
     description: Number of high findings.
     value: ${{ steps.scan.outputs.high }}
+  medium:
+    description: Number of medium findings.
+    value: ${{ steps.scan.outputs.medium }}
+  low:
+    description: Number of low findings.
+    value: ${{ steps.scan.outputs.low }}
   total:
     description: Total number of findings.
     value: ${{ steps.scan.outputs.total }}
+  blocking:
+    description: Number of findings at or above the fail-on severity.
+    value: ${{ steps.scan.outputs.blocking }}
 
 runs:
   using: composite
@@ -59,17 +71,28 @@ runs:
     - name: Resolve ClearToShip
       id: resolve
       shell: bash
+      env:
+        INPUT_VERSION: ${{ inputs.version }}
       run: |
-        # Prefer the published npm package. If it cannot be resolved — which is
-        # the case before the first publish, or when a pinned version is not on
-        # the registry — fall back to building from this action's own checkout,
-        # so `uses: <owner>/cleartoship@ref` works with no npm dependency.
-        ver="${{ inputs.version }}"
+        # With no version pinned, run the exact version this action's checkout
+        # declares. That keeps the action ref and the scanner in lockstep:
+        # `uses: <owner>/cleartoship@v0.9.0` runs cleartoship@0.9.0 instead of
+        # whatever npm happens to tag `latest` at the time.
+        ver="$INPUT_VERSION"
+        if [ -z "$ver" ]; then
+          ver=$(node -p "require('${GITHUB_ACTION_PATH}/package.json').version")
+          echo "No version pinned; matching this action's checkout: ${ver}"
+        fi
+
+        # Prefer the published npm package. If it cannot be resolved — an
+        # unpublished version, or a pinned version that is not on the registry —
+        # fall back to building from this action's own checkout, so
+        # `uses: <owner>/cleartoship@ref` works with no npm dependency.
         if [ "$ver" != "local" ] && npm view "cleartoship@${ver}" version >/dev/null 2>&1; then
           echo "cmd=npx --yes cleartoship@${ver}" >> "$GITHUB_OUTPUT"
           echo "Using published cleartoship@${ver}"
         else
-          echo "Published package not found; building from the action checkout."
+          echo "cleartoship@${ver} not on the registry; building from the action checkout."
           ( cd "$GITHUB_ACTION_PATH" && npm ci --silent && npm run build --silent )
           echo "cmd=node ${GITHUB_ACTION_PATH}/dist/cli.js" >> "$GITHUB_OUTPUT"
         fi
@@ -78,30 +101,56 @@ runs:
       id: scan
       shell: bash
       working-directory: ${{ inputs.working-directory }}
+      env:
+        # Inputs are read through the environment rather than interpolated into
+        # the script body, so a caller's value is never parsed as shell.
+        CTS: ${{ steps.resolve.outputs.cmd }}
+        INPUT_PATHS: ${{ inputs.paths }}
+        INPUT_OFFLINE: ${{ inputs.offline }}
+        INPUT_SARIF: ${{ inputs.sarif }}
+        INPUT_FAIL_ON: ${{ inputs.fail-on }}
       run: |
         set -o pipefail
-        CTS="${{ steps.resolve.outputs.cmd }}"
         args=()
-        [ -n "${{ inputs.paths }}" ] && args+=(${{ inputs.paths }})
-        [ "${{ inputs.offline }}" = "true" ] && args+=(--offline)
+        if [ -n "$INPUT_PATHS" ]; then read -ra args <<< "$INPUT_PATHS"; fi
+        if [ "$INPUT_OFFLINE" = "true" ]; then args+=(--offline); fi
 
         # The gate is applied at the end so the report and comment are produced
         # regardless of pass/fail; --fail-on=none keeps this step from aborting early.
         $CTS "${args[@]}" --json --fail-on=none > cleartoship.json
         $CTS "${args[@]}" --markdown --fail-on=none > cleartoship.md || true
-        if [ "${{ inputs.sarif }}" = "true" ]; then
+        if [ "$INPUT_SARIF" = "true" ]; then
           $CTS "${args[@]}" --sarif --fail-on=none > results.sarif || true
         fi
 
-        node -e '
-          const r = require("./cleartoship.json");
-          const out = process.env.GITHUB_OUTPUT;
-          const fs = require("fs");
-          fs.appendFileSync(out, `verdict=${r.verdict}\n`);
-          fs.appendFileSync(out, `critical=${r.counts.critical}\n`);
-          fs.appendFileSync(out, `high=${r.counts.high}\n`);
-          fs.appendFileSync(out, `total=${r.findings.length}\n`);
-        '
+        # Counting blocking findings here — off the full report, which carries every
+        # severity — is what makes `fail-on: medium` and `fail-on: low` mean what they
+        # say. A gate rebuilt from the critical/high outputs alone silently cannot.
+        # Fed to node over stdin with a quoted heredoc: nothing here is parsed by
+        # bash, so an apostrophe in a comment cannot silently truncate the script.
+        node <<'NODE'
+        const fs = require("fs");
+        const r = JSON.parse(fs.readFileSync("cleartoship.json", "utf8"));
+        const rank = { critical: 4, high: 3, medium: 2, low: 1, info: 0 };
+        const gate = process.env.INPUT_FAIL_ON;
+        if (gate !== "none" && !(gate in rank)) {
+          console.error(`::error::Unknown fail-on value "${gate}". Use critical, high, medium, low or none.`);
+          process.exit(2);
+        }
+        const blocking = gate === "none"
+          ? 0
+          : r.findings.filter((f) => rank[f.severity] >= rank[gate]).length;
+        // Written out one by one rather than in a loop, so every declared output
+        // stays greppable and the action test can prove each one is produced.
+        const out = process.env.GITHUB_OUTPUT;
+        fs.appendFileSync(out, `verdict=${r.verdict}\n`);
+        fs.appendFileSync(out, `critical=${r.counts.critical}\n`);
+        fs.appendFileSync(out, `high=${r.counts.high}\n`);
+        fs.appendFileSync(out, `medium=${r.counts.medium}\n`);
+        fs.appendFileSync(out, `low=${r.counts.low}\n`);
+        fs.appendFileSync(out, `total=${r.findings.length}\n`);
+        fs.appendFileSync(out, `blocking=${blocking}\n`);
+        NODE
 
         # Job summary — always shown on the run.
         cat cleartoship.md >> "$GITHUB_STEP_SUMMARY"
@@ -113,6 +162,7 @@ runs:
       env:
         GH_TOKEN: ${{ inputs.github-token }}
         PR: ${{ github.event.pull_request.number }}
+        REPO: ${{ github.repository }}
       run: |
         # A sticky comment: find a previous ClearToShip comment and edit it, so
         # re-runs update in place instead of piling up.
@@ -120,12 +170,12 @@ runs:
         printf '%s\n\n' "$marker" > body.md
         cat cleartoship.md >> body.md
 
-        id=$(gh api "repos/${{ github.repository }}/issues/${PR}/comments" \
+        id=$(gh api "repos/${REPO}/issues/${PR}/comments" \
               --jq "map(select(.body | contains(\"$marker\"))) | .[0].id // empty" 2>/dev/null || true)
         if [ -n "$id" ]; then
-          gh api -X PATCH "repos/${{ github.repository }}/issues/comments/${id}" -F body=@body.md >/dev/null
+          gh api -X PATCH "repos/${REPO}/issues/comments/${id}" -F body=@body.md >/dev/null
         else
-          gh api -X POST "repos/${{ github.repository }}/issues/${PR}/comments" -F body=@body.md >/dev/null
+          gh api -X POST "repos/${REPO}/issues/${PR}/comments" -F body=@body.md >/dev/null
         fi
 
     - name: Upload SARIF
@@ -136,19 +186,12 @@ runs:
 
     - name: Apply severity gate
       shell: bash
+      env:
+        GATE: ${{ inputs.fail-on }}
+        BLOCKING: ${{ steps.scan.outputs.blocking }}
       run: |
-        gate="${{ inputs.fail-on }}"
-        [ "$gate" = "none" ] && exit 0
-        declare -A rank=( [critical]=4 [high]=3 [medium]=2 [low]=1 )
-        floor=${rank[$gate]:-4}
-        crit=${{ steps.scan.outputs.critical }}
-        high=${{ steps.scan.outputs.high }}
-        # Only critical and high are wired as outputs; medium/low never block by default.
-        blocking=0
-        [ "$floor" -le 4 ] && blocking=$((blocking + crit))
-        [ "$floor" -le 3 ] && blocking=$((blocking + high))
-        if [ "$blocking" -gt 0 ]; then
-          echo "::error::ClearToShip found $blocking finding(s) at or above '$gate'."
+        if [ "$BLOCKING" -gt 0 ]; then
+          echo "::error::ClearToShip found ${BLOCKING} finding(s) at or above '${GATE}'."
           exit 1
         fi
-        echo "ClearToShip: clear to ship at '$gate'."
+        echo "ClearToShip: clear to ship at '${GATE}'."

package/dist/scanners/auth-helpers.d.ts

@@ -0,0 +1,16 @@
+import type { ModuleIndex } from '../utils/modules.js';
+import type { File } from '@babel/types';
+export interface AuthHelperOptions {
+    /** Callee names that prove the caller's identity was checked. */
+    authCalls: string[];
+    /** Higher-order wrappers that apply auth for the function they wrap. */
+    authWrappers: string[];
+    index: ModuleIndex;
+    /** Per-scan memo, keyed by absolute file path. */
+    cache: Map<string, ReadonlySet<string>>;
+}
+/**
+ * Names that mean "authenticated" when used inside `file`. Includes helpers
+ * defined in the file and symbols imported from first-party modules.
+ */
+export declare function authNamesFor(file: string, opts: AuthHelperOptions, preparsed?: File | null, depth?: number, stack?: Set<string>): ReadonlySet<string>;

package/dist/scanners/auth-helpers.js

@@ -0,0 +1,169 @@
+import { read } from '../utils/files.js';
+import { parseSource, calleeName, calleeTail } from '../utils/ast.js';
+/**
+ * Recognising an authenticated caller only when the check is written inline
+ * inside the action is wrong for the way real apps are built: session
+ * verification is factored into `lib/auth.ts` (or a framework helper such as
+ * Shopify's `handleSessionToken`) and every action calls that. Reading only the
+ * action body then reports each of them as unauthenticated — four false
+ * criticals on one dogfooded Shopify app, which is exactly the kind of finding
+ * that teaches people to ignore the tool.
+ *
+ * This module answers the narrower question the scanner actually needs: which
+ * *names*, as spelled in this file, stand for "the caller was authenticated"?
+ * A name qualifies when the function behind it — defined here, or exported by a
+ * first-party module this file imports — itself performs a recognised auth call,
+ * directly or through another such helper. Third-party packages are never
+ * followed, so a call into `node_modules` still proves nothing on its own.
+ */
+/** How many import hops to follow before giving up. */
+const MAX_DEPTH = 3;
+/** Rounds of the same-file fixed point — helpers calling helpers calling helpers. */
+const MAX_ROUNDS = 4;
+const EMPTY = new Set();
+function matchesAny(name, list) {
+    for (const candidate of list) {
+        if (name === candidate || name.endsWith('.' + candidate))
+            return true;
+    }
+    return false;
+}
+/** Every callee name (dotted and bare) reachable inside one function body. */
+function callNamesIn(node, out, depth = 0) {
+    if (!node || typeof node !== 'object' || depth > 400)
+        return;
+    if (Array.isArray(node)) {
+        for (const child of node)
+            callNamesIn(child, out, depth + 1);
+        return;
+    }
+    if (typeof node.type !== 'string')
+        return;
+    if (node.type === 'CallExpression' || node.type === 'OptionalCallExpression') {
+        const full = calleeName(node.callee);
+        if (full) {
+            out.add(full);
+            out.add(calleeTail(node.callee));
+        }
+    }
+    for (const key of Object.keys(node)) {
+        if (key === 'loc' || key === 'leadingComments' || key === 'trailingComments')
+            continue;
+        const value = node[key];
+        if (value && typeof value === 'object')
+            callNamesIn(value, out, depth + 1);
+    }
+}
+/** Top-level `function f()` / `const f = () => {}`, exported or not. */
+function collectFunctions(ast) {
+    const found = new Map();
+    const addFunction = (name, body) => {
+        if (!name || !body)
+            return;
+        const calls = new Set();
+        callNamesIn(body, calls);
+        found.set(name, calls);
+    };
+    const fromDeclaration = (decl) => {
+        if (!decl)
+            return;
+        if (decl.type === 'FunctionDeclaration') {
+            addFunction(decl.id?.name, decl.body);
+            return;
+        }
+        if (decl.type !== 'VariableDeclaration')
+            return;
+        for (const d of decl.declarations ?? []) {
+            if (d?.id?.type !== 'Identifier')
+                continue;
+            const init = d.init;
+            if (init?.type === 'ArrowFunctionExpression' || init?.type === 'FunctionExpression') {
+                addFunction(d.id.name, init.body);
+            }
+        }
+    };
+    for (const stmt of ast.program.body) {
+        if (stmt.type === 'ExportNamedDeclaration')
+            fromDeclaration(stmt.declaration);
+        else
+            fromDeclaration(stmt);
+    }
+    return found;
+}
+/**
+ * Names that mean "authenticated" when used inside `file`. Includes helpers
+ * defined in the file and symbols imported from first-party modules.
+ */
+export function authNamesFor(file, opts, preparsed, depth = 0, stack = new Set()) {
+    const memo = opts.cache.get(file);
+    if (memo)
+        return memo;
+    // A cycle (a imports b imports a) resolves to nothing rather than looping.
+    if (stack.has(file) || depth > MAX_DEPTH)
+        return EMPTY;
+    let ast = preparsed ?? null;
+    if (!ast) {
+        const source = read(file);
+        if (source === null)
+            return EMPTY;
+        // Cheap bail-out: a file that mentions none of the auth vocabulary cannot
+        // define an auth helper, and most files in a repo are that file.
+        if (!opts.authCalls.some((c) => source.includes(c.split('.').pop()))) {
+            opts.cache.set(file, EMPTY);
+            return EMPTY;
+        }
+        ast = parseSource(source, file);
+        if (!ast) {
+            opts.cache.set(file, EMPTY);
+            return EMPTY;
+        }
+    }
+    stack.add(file);
+    const credited = new Set();
+    for (const stmt of ast.program.body) {
+        if (stmt.type !== 'ImportDeclaration')
+            continue;
+        const spec = stmt.source?.value;
+        const target = typeof spec === 'string' ? opts.index.resolve(spec, file) : null;
+        if (!target)
+            continue;
+        const exported = authNamesFor(target, opts, null, depth + 1, stack);
+        if (exported.size === 0)
+            continue;
+        for (const s of stmt.specifiers ?? []) {
+            const local = s.local?.name;
+            if (!local)
+                continue;
+            const imported = s.type === 'ImportSpecifier'
+                ? (s.imported.name ?? s.imported.value)
+                : s.type === 'ImportDefaultSpecifier'
+                    ? 'default'
+                    : null;
+            if (imported && exported.has(imported))
+                credited.add(local);
+        }
+    }
+    const functions = collectFunctions(ast);
+    for (let round = 0; round < MAX_ROUNDS; round++) {
+        let changed = false;
+        for (const [name, calls] of functions) {
+            if (credited.has(name))
+                continue;
+            for (const call of calls) {
+                if (matchesAny(call, opts.authCalls) ||
+                    matchesAny(call, opts.authWrappers) ||
+                    credited.has(call)) {
+                    credited.add(name);
+                    changed = true;
+                    break;
+                }
+            }
+        }
+        if (!changed)
+            break;
+    }
+    stack.delete(file);
+    const result = credited;
+    opts.cache.set(file, result);
+    return result;
+}

package/dist/scanners/community.js

@@ -65,12 +65,48 @@ const WITHHELD = new Map([
         'a packaging lint (missing "files" field), not a security finding, and wrong for apps ' +
             'rather than published libraries',
     ],
+    [
+        'VG865',
+        'declares itself a `.npmignore` lint but is registered for the `shell` language, so it ' +
+            'matches almost every line of every shell script — 6 hits on two `scripts/*.sh` files, ' +
+            'all false, and it is a packaging lint rather than a security finding either way',
+    ],
     [
         'VG1004',
         'matches every `use server` module with an exported function; it asserts "no rate limiting" ' +
             'without ever checking for it',
     ],
 ]);
+/**
+ * Machine-generated dependency lockfiles. Their entries describe the *transitive*
+ * graph, which nobody in this repo wrote or can edit directly.
+ */
+const LOCKFILE = /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|composer\.lock|Pipfile\.lock|poetry\.lock)$/i;
+/**
+ * Rules whose signal only exists in a hand-authored manifest. The same JSON
+ * shapes appear all over a lockfile describing packages a dependency chose, so
+ * a hit there is both unactionable and, measured on the dogfooding corpus,
+ * wrong: `fast-glob`, `fast-deep-equal`, `common-tags`, `core-js` and
+ * `simple-statistics` all trip the deceptive-prefix list, and the "wildcard
+ * version" rule fires on transitive `"node": ">=16"` engine constraints.
+ * Declared package names are covered properly by CTS020-CTS027, which ask the
+ * registry rather than matching a prefix.
+ */
+const MANIFEST_ONLY = new Map([
+    ['VG872', 'internal-name heuristic; in a lockfile it names a transitive dependency'],
+    ['VG873', 'deceptive-prefix heuristic; matches ordinary transitive package names'],
+    ['VG020', 'wildcard version; a transitive range is the dependency author\'s choice'],
+]);
+/**
+ * Per-rule filters for a match shape the upstream regex cannot exclude on its
+ * own. Applied to the matched text, not the whole file.
+ */
+const MATCH_GUARDS = {
+    // A `"link": true` entry is a workspace or pnpm symlink resolved to a path on
+    // disk rather than a tarball, so it has no integrity hash by design. Thirty of
+    // them in one pnpm-managed lockfile, every one reported as a false critical.
+    VG870: (match) => !/"link"\s*:\s*true/.test(match),
+};
 /** Paths where a match is a fixture or documentation rather than shipped code. */
 const NON_PRODUCTION_PATH = /(^|\/)(tests?|__tests__|__mocks__|__fixtures__|fixtures?|spec|specs|examples?|docs?|demo|samples?|e2e|cypress|playwright|stories)(\/|$)|\.(test|spec|stories|fixture)\.[a-z]+$/i;
 /** Regexes over very large files are where catastrophic backtracking bites. */
@@ -100,11 +136,15 @@ export const communityScanner = {
                 continue;
             const relPath = rel(ctx.root, file);
             const fixture = NON_PRODUCTION_PATH.test(relPath);
+            const lockfile = LOCKFILE.test(relPath);
             const suppress = new Suppressions(source);
             filesScanned++;
             for (const rule of active) {
                 if (!rule.languages.some((l) => languages.includes(l)))
                     continue;
+                if (lockfile && MANIFEST_ONLY.has(rule.id))
+                    continue;
+                const guard = MATCH_GUARDS[rule.id];
                 const re = rule.pattern;
                 re.lastIndex = 0;
                 let m;
@@ -115,6 +155,13 @@ export const communityScanner = {
                         re.lastIndex++;
                         continue;
                     }
+                    // Skipping a match must not skip the non-global `break` below, or a
+                    // rule without /g would rescan from zero forever.
+                    if (guard && !guard(m[0])) {
+                        if (!re.global)
+                            break;
+                        continue;
+                    }
                     const line = lineAt(source, m.index);
                     const key = `${relPath}:${line}:${rule.id}`;
                     if (!seen.has(key) && !suppress.suppressed(line, rule.id)) {
@@ -148,7 +195,8 @@ export const communityScanner = {
         result.checks.push({
             label: `Community ruleset (${active.length} rules over ${filesScanned} files)`,
             passed: result.findings.every((f) => f.severity !== 'critical'),
-            note: `${SUPERSEDED.size} superseded by ClearToShip's AST checks, ${WITHHELD.size} withheld as noisy`,
+            note: `${SUPERSEDED.size} superseded by ClearToShip's AST checks, ${WITHHELD.size} withheld as noisy, ` +
+                `${MANIFEST_ONLY.size} manifest-only (not run over lockfiles)`,
         });
         return result;
     },

package/dist/scanners/index.d.ts

@@ -3,6 +3,7 @@ import { rlsScanner } from './rls.js';
 import { dependencyScanner } from './dependencies.js';
 import { secretsScanner } from './secrets.js';
 import { communityScanner } from './community.js';
+import { logicScanner } from './logic.js';
 import type { Scanner } from '../types.js';
 export declare const SCANNERS: Scanner[];
-export { serverActionsScanner, rlsScanner, dependencyScanner, secretsScanner, communityScanner, };
+export { serverActionsScanner, rlsScanner, dependencyScanner, secretsScanner, communityScanner, logicScanner, };

package/dist/scanners/index.js

@@ -3,11 +3,13 @@ import { rlsScanner } from './rls.js';
 import { dependencyScanner } from './dependencies.js';
 import { secretsScanner } from './secrets.js';
 import { communityScanner } from './community.js';
+import { logicScanner } from './logic.js';
 export const SCANNERS = [
     dependencyScanner,
     serverActionsScanner,
     rlsScanner,
     secretsScanner,
+    logicScanner,
     communityScanner,
 ];
-export { serverActionsScanner, rlsScanner, dependencyScanner, secretsScanner, communityScanner, };
+export { serverActionsScanner, rlsScanner, dependencyScanner, secretsScanner, communityScanner, logicScanner, };

package/dist/scanners/logic.d.ts

@@ -0,0 +1,2 @@
+import type { Scanner } from '../types.js';
+export declare const logicScanner: Scanner;