@reneturcios/hookcheck 0.1.3 → 0.1.5

package/dist/core.js

@@ -6,7 +6,7 @@
  */
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
-export const VERSION = "0.1.3";
+export const VERSION = "0.1.5";
 export const RISKY_RULES = [
     { id: "DECODE-PIPE-SH", pattern: /\bbase64\s+(-d|--decode|-D)\b[^|]*\|\s*(sudo\s+)?(sh|bash|zsh|node|python3?|perl|ruby)\b/, evidence: "decodes a base64 payload and pipes it straight into an interpreter", severe: true, remote: true },
     { id: "CURL-PIPE-SH", pattern: /\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(sh|bash|zsh|node|python3?|perl|ruby)\b/, evidence: "pipes a network download straight into an interpreter", severe: true, remote: true },
@@ -29,7 +29,15 @@ const EXTRA_RULE_META = {
     "CRED-ACCESS": { credential: true },
     "ENV-ACCESS": { credential: true },
     "ENV-BULK": { credential: true },
-    "ENV-EXFIL": { credential: true, remote: true },
+    // ENV-EXFIL is severe since v0.1.4 (P-018): it no longer fires on
+    // co-occurrence of a credential shaped name and a URL, only when the
+    // credential value demonstrably flows into an outbound send, so on its
+    // own it is strong evidence. Token as authentication (an Authorization
+    // header, the userinfo of a push URL, a --token flag) never counts.
+    "ENV-EXFIL": { credential: true, remote: true, severe: true },
+    // CRED-EXFIL: credential store contents piped straight into a network
+    // tool. Severe for the same reason: the value flow is in the text.
+    "CRED-EXFIL": { credential: true, remote: true, severe: true },
 };
 function ruleMeta(id) {
     const r = RISKY_RULES.find((x) => x.id === id);
@@ -54,6 +62,420 @@ export function stripComments(text) {
     })
         .join("\n");
 }
+function langForFile(name) {
+    if (/\.py$/i.test(name))
+        return "python";
+    if (/\.(?:mjs|cjs|js|ts|tsx|jsx)$/i.test(name))
+        return "js";
+    return "shell";
+}
+function inRanges(idx, ranges) {
+    return ranges.some((r) => idx >= r.start && idx < r.end);
+}
+/**
+ * True when `name` is referenced at a code position inside `seg` (whose
+ * global start offset is `segStart`): at least one occurrence that does
+ * not begin inside a data literal. A variable merely NAMED in prose (help
+ * text, a banner string, a docstring) is mentioned, not used; the mention
+ * must not propagate taint or count as disclosure. Found in the v0.1.4
+ * re-validation on jpoley/flowspec: a kwarg default tainted the variable
+ * name `help` through its prose value ("GitHub token for API requests"),
+ * and a banner printing the word --help then read as credential
+ * disclosure next to the prose word "fetch" in a docstring.
+ */
+function refOutsideData(seg, name, segStart, dataRanges) {
+    const re = new RegExp(`\\b${name.replace(/\$/g, "\\$")}\\b`, "g");
+    for (const m of seg.matchAll(re)) {
+        if (!inRanges(segStart + (m.index ?? 0), dataRanges))
+            return true;
+    }
+    return false;
+}
+function blankRanges(text, ranges) {
+    if (ranges.length === 0)
+        return text;
+    const chars = text.split("");
+    for (const r of ranges) {
+        for (let i = r.start; i < r.end && i < chars.length; i++) {
+            if (chars[i] !== "\n")
+                chars[i] = " ";
+        }
+    }
+    return chars.join("");
+}
+/** Content ranges of a literal with its interpolation holes left visible. */
+function contentRanges(lit) {
+    const out = [];
+    let cur = lit.contentStart;
+    for (const h of lit.holes) {
+        if (h.start > cur)
+            out.push({ start: cur, end: h.start });
+        cur = Math.max(cur, h.end);
+    }
+    if (lit.contentEnd > cur)
+        out.push({ start: cur, end: lit.contentEnd });
+    return out;
+}
+function scanJsLiterals(text) {
+    const spans = [];
+    const n = text.length;
+    let i = 0;
+    let prevSig = "";
+    let prevWord = "";
+    const regexAfterChar = new Set("=({[,;:!&|?+-*%~^<>".split(""));
+    const regexAfterWord = new Set(["return", "typeof", "case", "in", "of", "new", "delete", "void", "instanceof", "yield", "await", "throw", "else", "do"]);
+    while (i < n) {
+        const ch = text[i];
+        if (ch === "/" && text[i + 1] === "/") {
+            const e = text.indexOf("\n", i);
+            i = e === -1 ? n : e;
+            continue;
+        }
+        if (ch === "/" && text[i + 1] === "*") {
+            const e = text.indexOf("*/", i + 2);
+            i = e === -1 ? n : e + 2;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            let j = i + 1;
+            while (j < n) {
+                if (text[j] === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (text[j] === ch || text[j] === "\n")
+                    break;
+                j++;
+            }
+            spans.push({ start: i, end: Math.min(j + 1, n), contentStart: i + 1, contentEnd: j, holes: [] });
+            i = Math.min(j + 1, n);
+            prevSig = ch;
+            prevWord = "";
+            continue;
+        }
+        if (ch === "`") {
+            let j = i + 1;
+            const holes = [];
+            while (j < n) {
+                if (text[j] === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (text[j] === "`")
+                    break;
+                if (text[j] === "$" && text[j + 1] === "{") {
+                    const holeStart = j;
+                    let depth = 1;
+                    j += 2;
+                    while (j < n && depth > 0) {
+                        if (text[j] === "{")
+                            depth++;
+                        else if (text[j] === "}")
+                            depth--;
+                        j++;
+                    }
+                    holes.push({ start: holeStart, end: j });
+                    continue;
+                }
+                j++;
+            }
+            spans.push({ start: i, end: Math.min(j + 1, n), contentStart: i + 1, contentEnd: j, holes });
+            i = Math.min(j + 1, n);
+            prevSig = "`";
+            prevWord = "";
+            continue;
+        }
+        if (ch === "/" && (prevSig === "" || regexAfterChar.has(prevSig) || regexAfterWord.has(prevWord))) {
+            let j = i + 1;
+            let inClass = false;
+            while (j < n) {
+                if (text[j] === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (text[j] === "[")
+                    inClass = true;
+                else if (text[j] === "]")
+                    inClass = false;
+                else if (text[j] === "/" && !inClass)
+                    break;
+                else if (text[j] === "\n")
+                    break;
+                j++;
+            }
+            let end = Math.min(j + 1, n);
+            while (end < n && /[a-z]/i.test(text[end]))
+                end++;
+            spans.push({ start: i, end, contentStart: i + 1, contentEnd: j, holes: [] });
+            i = end;
+            prevSig = "/";
+            prevWord = "";
+            continue;
+        }
+        if (/[A-Za-z0-9_$]/.test(ch)) {
+            prevWord += ch;
+            prevSig = ch;
+            i++;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            i++;
+            continue;
+        }
+        prevSig = ch;
+        prevWord = "";
+        i++;
+    }
+    return spans;
+}
+function scanPyLiterals(text) {
+    const spans = [];
+    const n = text.length;
+    let i = 0;
+    while (i < n) {
+        const ch = text[i];
+        if (ch === "#") {
+            const e = text.indexOf("\n", i);
+            i = e === -1 ? n : e;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            // String prefix letters (r, b, f, u) sit immediately before the quote.
+            let p = i - 1;
+            let prefix = "";
+            while (p >= 0 && /[rRbBfFuU]/.test(text[p])) {
+                prefix = text[p] + prefix;
+                p--;
+            }
+            const isF = /f/i.test(prefix);
+            const triple = text.startsWith(ch + ch + ch, i);
+            const qLen = triple ? 3 : 1;
+            let j = i + qLen;
+            const holes = [];
+            while (j < n) {
+                if (text[j] === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (triple ? text.startsWith(ch + ch + ch, j) : text[j] === ch || text[j] === "\n")
+                    break;
+                if (isF && text[j] === "{") {
+                    if (text[j + 1] === "{") {
+                        j += 2;
+                        continue;
+                    }
+                    const holeStart = j;
+                    let depth = 1;
+                    j++;
+                    while (j < n && depth > 0) {
+                        if (text[j] === "{")
+                            depth++;
+                        else if (text[j] === "}")
+                            depth--;
+                        j++;
+                    }
+                    holes.push({ start: holeStart, end: j });
+                    continue;
+                }
+                if (isF && text[j] === "}" && text[j + 1] === "}") {
+                    j += 2;
+                    continue;
+                }
+                j++;
+            }
+            spans.push({ start: i, end: Math.min(j + qLen, n), contentStart: i + qLen, contentEnd: j, holes });
+            i = Math.min(j + qLen, n);
+            continue;
+        }
+        i++;
+    }
+    return spans;
+}
+const EXEC_CALLS = ["eval", "exec", "execSync", "execFile", "execFileSync", "spawn", "spawnSync", "system", "popen", "Popen", "Function", "runInThisContext", "runInNewContext", "runInContext", "setTimeout", "setInterval", "compile"];
+const PATH_CALLS = ["readFileSync", "readFile", "createReadStream", "createWriteStream", "open", "join", "resolve", "Path", "expanduser", "homedir"];
+/**
+ * First argument spans of calls to the named functions. The matching
+ * close paren is found with a scan that jumps over literal spans, so
+ * parens inside strings do not unbalance it.
+ */
+function callFirstArgSpans(text, names, literals) {
+    const spans = [];
+    const litAt = new Map();
+    for (const l of literals)
+        litAt.set(l.start, l);
+    const re = new RegExp(`\\b(?:${names.join("|")})\\s*\\(`, "g");
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const open = m.index + m[0].length - 1;
+        let depth = 1;
+        let j = open + 1;
+        let firstArgEnd = -1;
+        while (j < text.length && depth > 0) {
+            const lit = litAt.get(j);
+            if (lit) {
+                j = lit.end;
+                continue;
+            }
+            const c = text[j];
+            if (c === "(")
+                depth++;
+            else if (c === ")") {
+                depth--;
+                if (depth === 0)
+                    break;
+            }
+            else if (c === "," && depth === 1 && firstArgEnd === -1)
+                firstArgEnd = j;
+            j++;
+        }
+        spans.push({ start: open + 1, end: firstArgEnd === -1 ? j : firstArgEnd });
+    }
+    return spans;
+}
+/**
+ * Split shell text into segments on the given separators, tracking
+ * single and double quotes so separators inside quoted strings do not
+ * split. Returns segment ranges in the original text.
+ */
+function splitShell(text, separators) {
+    const out = [];
+    let start = 0;
+    let i = 0;
+    let quote = "";
+    while (i < text.length) {
+        const c = text[i];
+        if (quote) {
+            if (c === "\\" && quote === '"') {
+                i += 2;
+                continue;
+            }
+            if (c === quote)
+                quote = "";
+            i++;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            quote = c;
+            i++;
+            continue;
+        }
+        const sep = separators.find((s) => text.startsWith(s, i));
+        if (sep) {
+            out.push({ start, end: i });
+            i += sep.length;
+            start = i;
+            continue;
+        }
+        i++;
+    }
+    out.push({ start, end: text.length });
+    return out;
+}
+function firstShellWord(segment) {
+    let s = segment.trim();
+    // Skip leading env assignments and sudo.
+    for (;;) {
+        const assign = s.match(/^[A-Za-z_][A-Za-z0-9_]*=\S+\s+/);
+        if (assign) {
+            s = s.slice(assign[0].length);
+            continue;
+        }
+        if (/^sudo\s+/.test(s)) {
+            s = s.replace(/^sudo\s+/, "");
+            continue;
+        }
+        break;
+    }
+    const w = s.match(/^[A-Za-z_][A-Za-z0-9_.-]*/);
+    return w ? w[0] : "";
+}
+/**
+ * Content ranges of echo and printf string arguments in shell text:
+ * output data, blanked in the code view, unless the pipeline ends in a
+ * bare interpreter (or a bare sh or bash), where the printed text is fed
+ * to the interpreter as its program.
+ */
+function shellEchoDataRanges(text) {
+    const ranges = [];
+    for (const stmt of splitShell(text, ["\n", ";", "&&", "||"])) {
+        const stmtText = text.slice(stmt.start, stmt.end);
+        if (!stmtText.trim())
+            continue;
+        const segments = splitShell(stmtText, ["|"]);
+        const lastText = stmtText.slice(segments[segments.length - 1].start, segments[segments.length - 1].end);
+        const lastWord = firstShellWord(lastText);
+        let execSink = ["sh", "bash", "zsh", "dash", "eval", "source"].includes(lastWord);
+        if (!execSink && ["python", "python3", "node", "perl", "ruby"].includes(lastWord)) {
+            const rest = lastText.trim().replace(/^[A-Za-z_][A-Za-z0-9_.-]*/, "").trim();
+            // Bare interpreter (optionally a lone "-") reads its program from stdin.
+            execSink = rest === "" || rest === "-";
+        }
+        if (execSink)
+            continue;
+        for (const seg of segments) {
+            const segText = stmtText.slice(seg.start, seg.end);
+            const word = firstShellWord(segText);
+            if (word !== "echo" && word !== "printf")
+                continue;
+            // Every quoted literal in an echo segment is printed data.
+            let j = 0;
+            while (j < segText.length) {
+                const c = segText[j];
+                if (c === "'" || c === '"') {
+                    let k = j + 1;
+                    while (k < segText.length) {
+                        if (segText[k] === "\\" && c === '"') {
+                            k += 2;
+                            continue;
+                        }
+                        if (segText[k] === c)
+                            break;
+                        k++;
+                    }
+                    ranges.push({ start: stmt.start + seg.start + j + 1, end: stmt.start + seg.start + k });
+                    j = k + 1;
+                    continue;
+                }
+                j++;
+            }
+        }
+    }
+    return ranges;
+}
+function buildViews(text, lang) {
+    if (lang === "shell") {
+        const dataRanges = shellEchoDataRanges(text);
+        return { codeText: blankRanges(text, dataRanges), credText: text, dataRanges };
+    }
+    const literals = lang === "python" ? scanPyLiterals(text) : scanJsLiterals(text);
+    const execSpans = callFirstArgSpans(text, EXEC_CALLS, literals);
+    const pathSpans = callFirstArgSpans(text, PATH_CALLS, literals);
+    const role = (lit) => {
+        if (execSpans.some((s) => lit.contentStart >= s.start && lit.contentEnd <= s.end))
+            return "code";
+        if (pathSpans.some((s) => lit.contentStart >= s.start && lit.contentEnd <= s.end))
+            return "path";
+        return "data";
+    };
+    const codeBlank = [];
+    const credBlank = [];
+    const dataRanges = [];
+    for (const lit of literals) {
+        const r = role(lit);
+        const contents = contentRanges(lit);
+        if (r === "data") {
+            codeBlank.push(...contents);
+            credBlank.push(...contents);
+            dataRanges.push(...contents);
+        }
+        else if (r === "path") {
+            codeBlank.push(...contents);
+        }
+        // "code" literals keep their contents in both views: the text is a
+        // program handed to an interpreter, and behavior rules should see it.
+    }
+    return { codeText: blankRanges(text, codeBlank), credText: blankRanges(text, credBlank), dataRanges };
+}
 const CRED_FILE_PATTERNS = [
     /~\/\.ssh(\/|\s|$|["'])/, /\$HOME\/\.ssh(\/|\s|$|["'])/, /(^|[\s"'(=])\.ssh\//,
     /\.aws\/credentials\b/, /\.aws\/config\b/,
@@ -83,10 +505,27 @@ const CRED_ENV_NAME = /(SECRET|TOKEN|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|ACCES
  * Only credential shaped names (token, secret, password, api key, and
  * friends, in any access syntax) and bulk access (whole object
  * serialization, printenv, bare env dumps, whole os.environ use) count.
+ *
+ * Round 2 (P-020): the rules must match reads, not any mention.
+ * os.environ.setdefault writes one named key with a default and
+ * os.environ.pop removes one; neither is bulk access, and the bare
+ * os.environ scan below excludes the accessor, subscript, and mutation
+ * forms explicitly. Passing the environment to a subprocess
+ * (env=os.environ) is inheritance, not a read. In shell text,
+ * `env -u NAME` unsets a variable for the subprocess, the opposite of a
+ * read, and a bare [ -n "$NAME" ] or [ -z "$NAME" ] test checks
+ * existence without reading the value into anything; matches inside
+ * those spans, and matches that start inside a quoted data literal
+ * (an echo string, a pattern list), are skipped.
  */
-function detectEnvAccess(cmd) {
+function detectEnvAccess(cmd, dataRanges) {
     let cred = false;
     let bulk = false;
+    const skipSpans = [
+        ...Array.from(cmd.matchAll(/\benv(?:\s+-u\s+[A-Za-z_][A-Za-z0-9_]*)+/g), (m) => ({ start: m.index, end: m.index + m[0].length })),
+        ...Array.from(cmd.matchAll(/\[\[?\s+-[nz]\s+"?\$\{?[A-Za-z_][A-Za-z0-9_]*\}?"?\s*\]\]?/g), (m) => ({ start: m.index, end: m.index + m[0].length })),
+    ];
+    const skipped = (idx) => inRanges(idx, dataRanges) || inRanges(idx, skipSpans);
     const nameRes = [
         /process\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
         /process\.env\[["']([A-Za-z_][A-Za-z0-9_]*)["']\]/g,
@@ -95,27 +534,325 @@ function detectEnvAccess(cmd) {
         /getenv\(["']([A-Za-z_][A-Za-z0-9_]*)["']/g,
         /Deno\.env\.get\(["']([A-Za-z_][A-Za-z0-9_]*)["']/g,
         /import\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)/g,
-        /\$\{?([A-Z][A-Z0-9_]{2,})\}?/g,
+        /\$(?:\{)?([A-Za-z_][A-Za-z0-9_]*)\}?/g,
     ];
     for (const re of nameRes) {
         let m;
         while ((m = re.exec(cmd)) !== null) {
+            if (m[0].startsWith("${#"))
+                continue; // ${#NAME} is a length, not a value
+            if (skipped(m.index))
+                continue;
             if (CRED_ENV_NAME.test(m[1]))
                 cred = true;
         }
     }
-    if (/(JSON\.stringify|Object\.(keys|values|entries|assign)|util\.inspect)\s*\([^)]*process\.env/.test(cmd))
+    if (/(JSON\.stringify|Object\.(keys|values|entries|assign)|util\.inspect)\s*\([^)]*(process\.env|os\.environ)/.test(cmd))
         bulk = true;
-    if (/\bprintenv\b/.test(cmd))
+    if (/\bprintenv\b/.test(cmd) && !inRanges(cmd.search(/\bprintenv\b/), dataRanges))
         bulk = true;
-    if (/(^|[;&|]\s*)env\s*($|[|>;])/.test(cmd))
+    if (/(^|[;&|]\s*)env\s*($|[|>;])/m.test(cmd))
         bulk = true;
     if (/\b(str|dict|list)\s*\(\s*os\.environ\s*\)/.test(cmd))
         bulk = true;
-    if (/\bos\.environ\b(?!\s*(\.get\s*\(|\[))/.test(cmd))
+    // Whole os.environ use (P-020): scan every occurrence and judge the
+    // operation that follows it, instead of one negative lookahead.
+    const envRe = /\bos\.environ\b/g;
+    let em;
+    while ((em = envRe.exec(cmd)) !== null) {
+        if (skipped(em.index))
+            continue;
+        const after = cmd.slice(em.index + em[0].length, em.index + em[0].length + 30);
+        if (/^\s*\.get\s*\(/.test(after))
+            continue; // named read, judged above
+        if (/^\s*\[/.test(after))
+            continue; // named subscript read
+        if (/^\s*\.(?:setdefault|pop|update)\s*\(/.test(after))
+            continue; // write or removal, not a read
+        if (/^\s*\.copy\s*\(/.test(after)) {
+            bulk = true;
+            continue;
+        } // whole copy is a bulk read
+        const before = cmd.slice(Math.max(0, em.index - 24), em.index);
+        if (/env\s*=\s*$/.test(before))
+            continue; // subprocess env inheritance
         bulk = true;
+    }
     return { cred, bulk };
 }
+/**
+ * Credential value atoms: text positions where a credential shaped env
+ * value, or the whole environment, is read. Atoms that start inside a
+ * quoted data literal are marked inData: a pattern list that MENTIONS
+ * process.env.SECRET is not reading it. Print disclosure is the one
+ * analysis that still uses inData atoms, because echoing a value prints
+ * it whether or not it was quoted.
+ */
+function findAtoms(text, dataRanges) {
+    const atoms = [];
+    const named = [
+        { re: /process\.env\.([A-Za-z_][A-Za-z0-9_]*)/g },
+        { re: /process\.env\[["']([A-Za-z_][A-Za-z0-9_]*)["']\]/g },
+        { re: /os\.environ\.get\(["']([A-Za-z_][A-Za-z0-9_]*)["']/g },
+        { re: /os\.environ\[["']([A-Za-z_][A-Za-z0-9_]*)["']\]/g },
+        { re: /getenv\(["']([A-Za-z_][A-Za-z0-9_]*)["']/g },
+        { re: /Deno\.env\.get\(["']([A-Za-z_][A-Za-z0-9_]*)["']/g },
+        { re: /import\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)/g },
+        { re: /\$(?:\{)?([A-Za-z_][A-Za-z0-9_]*)\}?/g },
+        { re: /\$\{\{\s*secrets\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g, always: true },
+        { re: /\$\{\{\s*env\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g },
+    ];
+    for (const { re, always } of named) {
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            if (m[0].startsWith("${#"))
+                continue;
+            if (!always && !CRED_ENV_NAME.test(m[1]))
+                continue;
+            atoms.push({ start: m.index, end: m.index + m[0].length, kind: "cred", inData: inRanges(m.index, dataRanges) });
+        }
+    }
+    const bulkRes = [
+        /(?:JSON\.stringify|util\.inspect|Object\.(?:keys|values|entries|assign))\s*\([^)]*(?:process\.env|os\.environ)/g,
+        /\bprintenv\b/g,
+        /\b(?:str|dict|list)\s*\(\s*os\.environ\s*\)/g,
+        /\bos\.environ\.copy\s*\(\s*\)/g,
+        /\bprocess\.env(?!\s*(?:\.|\[))/g,
+        /(^|[;&|]\s*)env\s*($|[|>;])/gm,
+    ];
+    for (const re of bulkRes) {
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            const rel = m[0].search(/process\.env|os\.environ|\benv\b|printenv/);
+            const at = m.index + (rel === -1 ? 0 : rel);
+            atoms.push({ start: at, end: at + 3, kind: "bulk", inData: inRanges(at, dataRanges) });
+        }
+    }
+    const envRe = /\bos\.environ\b/g;
+    let em;
+    while ((em = envRe.exec(text)) !== null) {
+        const after = text.slice(em.index + em[0].length, em.index + em[0].length + 30);
+        if (/^\s*(?:\.get|\[|\.setdefault|\.pop|\.update)/.test(after))
+            continue;
+        const before = text.slice(Math.max(0, em.index - 24), em.index);
+        if (/env\s*=\s*$/.test(before))
+            continue;
+        atoms.push({ start: em.index, end: em.index + em[0].length, kind: "bulk", inData: inRanges(em.index, dataRanges) });
+    }
+    return atoms;
+}
+/**
+ * Spans where a credential is used as authentication for the destination
+ * it belongs to: the userinfo of a URL (x-access-token pushes and clones
+ * to the repo's own host), the value of an Authorization header, and the
+ * value of a CLI auth flag (--token, --auth, --api-key). A token in one
+ * of these positions authenticates the send; it is not the payload, and
+ * Round 2 showed it driving false exfil verdicts on langfuse, PostHog,
+ * and cas release automation (P-018).
+ */
+function authRanges(text) {
+    const ranges = [];
+    for (const m of text.matchAll(/https?:\/\/[^\s"'`]+/g)) {
+        const url = m[0];
+        const schemeEnd = url.indexOf("://") + 3;
+        const authority = url.slice(schemeEnd).split("/")[0];
+        const at = authority.lastIndexOf("@");
+        if (at > 0)
+            ranges.push({ start: m.index + schemeEnd, end: m.index + schemeEnd + at });
+    }
+    const valueAfter = (from) => {
+        let end = from;
+        while (end < text.length && end - from < 200 && !/[\s"'`,;]/.test(text[end]))
+            end++;
+        return { start: from, end };
+    };
+    for (const m of text.matchAll(/authorization\s*["']?\s*[:=]\s*["']?\s*(?:bearer|basic|token)\s+/gi)) {
+        ranges.push(valueAfter(m.index + m[0].length));
+    }
+    for (const m of text.matchAll(/--(?:token|auth|api[-_]?key|password|secret)(?:\s*=\s*|\s+)["']?/gi)) {
+        ranges.push(valueAfter(m.index + m[0].length));
+    }
+    return ranges;
+}
+/** Variables assigned (transitively) from a credential value expression. */
+function taintedVars(text, atoms, dataRanges) {
+    const tainted = new Set();
+    const assignRe = /(?:^|[;\n,])\s*(?:export\s+|const\s+|let\s+|var\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\s*=(?![=<>])\s*/g;
+    const assigns = [];
+    let m;
+    while ((m = assignRe.exec(text)) !== null) {
+        const rhsStart = m.index + m[0].length;
+        let rhsEnd = rhsStart;
+        while (rhsEnd < text.length && text[rhsEnd] !== ";" && text[rhsEnd] !== "\n")
+            rhsEnd++;
+        assigns.push({ name: m[1], rhsStart, rhsEnd });
+    }
+    const live = atoms.filter((a) => !a.inData);
+    for (let pass = 0; pass < 4; pass++) {
+        for (const a of assigns) {
+            if (tainted.has(a.name))
+                continue;
+            if (live.some((x) => x.start >= a.rhsStart && x.start < a.rhsEnd)) {
+                tainted.add(a.name);
+                continue;
+            }
+            const rhs = text.slice(a.rhsStart, a.rhsEnd);
+            for (const v of tainted) {
+                if (refOutsideData(rhs, v, a.rhsStart, dataRanges)) {
+                    tainted.add(a.name);
+                    break;
+                }
+            }
+        }
+    }
+    return tainted;
+}
+/** Balanced paren span starting at the "(" index, quote aware. */
+function callSpan(text, openIdx) {
+    let depth = 0;
+    let quote = "";
+    for (let j = openIdx; j < text.length; j++) {
+        const c = text[j];
+        if (quote) {
+            if (c === "\\") {
+                j++;
+                continue;
+            }
+            if (c === quote)
+                quote = "";
+            continue;
+        }
+        if (c === "'" || c === '"' || c === "`") {
+            quote = c;
+            continue;
+        }
+        if (c === "(")
+            depth++;
+        else if (c === ")") {
+            depth--;
+            if (depth === 0)
+                return { start: openIdx, end: j + 1 };
+        }
+    }
+    return { start: openIdx, end: text.length };
+}
+function spanHasTaint(text, span, atoms, tainted, dataRanges) {
+    if (atoms.some((a) => !a.inData && a.start >= span.start && a.start < span.end))
+        return true;
+    if (tainted.size === 0)
+        return false;
+    const seg = text.slice(span.start, span.end);
+    for (const v of tainted) {
+        if (refOutsideData(seg, v, span.start, dataRanges))
+            return true;
+    }
+    return false;
+}
+/**
+ * Exfil value flow (Round 2, P-018). ENV-EXFIL used to fire on mere
+ * co-occurrence: a credential shaped name and any URL inside one finding.
+ * Since block scalars made a finding a whole 30 to 100 line step, and one
+ * hop following classifies whole referenced files, co-occurrence is the
+ * default state of any authenticated release step. Round 2 hand-read all
+ * 15 verdict drivers across langfuse, PostHog/posthog-js, attune-ai,
+ * cas, and flowspec: genuinely exfil shaped, zero. Every one was the
+ * repo's own automation using its token as authentication.
+ *
+ * ENV-EXFIL now requires the credential VALUE to flow into a send:
+ *   - an atom or a tainted variable inside a fetch, axios, requests,
+ *     http.get, urlopen, XHR send, or sendBeacon call span;
+ *   - an atom or tainted variable anywhere in a curl or wget statement
+ *     (payload, query string, or a non Authorization header), after
+ *     authentication positions have been removed;
+ *   - a pipeline whose earlier segments produce a credential value or a
+ *     bulk dump and whose later segment is netcat, or curl or wget
+ *     reading its body from stdin;
+ *   - a credential value printed or logged while a send construct is
+ *     present in the same text (CI logs are a real leak channel).
+ */
+function analyzeExfil(text, views, lang) {
+    const dataRanges = views.dataRanges;
+    const auth = authRanges(text);
+    const atoms = findAtoms(text, dataRanges).filter((a) => !inRanges(a.start, auth));
+    const tainted = taintedVars(text, atoms, dataRanges);
+    const has = (span) => spanHasTaint(text, span, atoms, tainted, dataRanges);
+    const callRes = [
+        /\bfetch\s*\(/g,
+        /\baxios(?:\s*\.\s*(?:post|put|patch|get|request|delete))?\s*\(/g,
+        /\brequests\s*\.\s*(?:get|post|put|patch|request)\s*\(/g,
+        /\bhttps?\s*\.\s*(?:request|get)\s*\(/g,
+        /\burlopen\s*\(/g,
+        /\.\s*send\s*\(/g,
+        /\bsendBeacon\s*\(/g,
+    ];
+    for (const re of callRes) {
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            if (has(callSpan(text, m.index + m[0].length - 1)))
+                return true;
+        }
+    }
+    const statements = splitShell(text, ["\n", ";", "&&", "||"]);
+    for (const stmt of statements) {
+        if (!/\b(?:curl|wget)\b/.test(text.slice(stmt.start, stmt.end)))
+            continue;
+        if (has(stmt))
+            return true;
+    }
+    for (const stmt of statements) {
+        const stmtText = text.slice(stmt.start, stmt.end);
+        const segments = splitShell(stmtText, ["|"]);
+        if (segments.length < 2)
+            continue;
+        for (let k = 1; k < segments.length; k++) {
+            const segText = stmtText.slice(segments[k].start, segments[k].end);
+            const word = firstShellWord(segText);
+            const isNc = word === "nc" || word === "netcat";
+            const isStdinSend = (word === "curl" || word === "wget") && /(?:-d\s+@-|--data(?:-raw|-binary)?\s+@-|-T\s+-)/.test(segText);
+            if (!isNc && !isStdinSend)
+                continue;
+            for (let e = 0; e < k; e++) {
+                const early = { start: stmt.start + segments[e].start, end: stmt.start + segments[e].end };
+                if (has(early))
+                    return true;
+            }
+        }
+    }
+    // Print disclosure alongside a send construct in the same text. The
+    // send gate runs on the code view with data blanked: a send WORD in
+    // prose (a docstring saying "we fetch release metadata") is not a send
+    // construct. In script files a printed atom or variable only counts at
+    // a code position (an f-string or template interpolation hole is code;
+    // prose inside a plain string is not). In shell text, echo and printf
+    // arguments ARE the printed values, so references inside them count.
+    const gateText = blankRanges(views.codeText, dataRanges);
+    const hasSendConstruct = /\b(?:fetch|axios|requests\s*\.|urlopen|https?\s*\.\s*(?:request|get)|curl|wget|nc|netcat)\b/.test(gateText);
+    if (hasSendConstruct) {
+        for (const m of text.matchAll(/(?:^|[;\n|&]\s*)(?:echo|printf)\s+([^\n;|]*)/g)) {
+            const span = { start: m.index, end: m.index + m[0].length };
+            if (atoms.some((a) => a.start >= span.start && a.start < span.end))
+                return true;
+            const argText = m[1] ?? "";
+            const argStart = m.index + m[0].length - argText.length;
+            for (const v of tainted) {
+                if (lang === "shell" || refOutsideData(argText, v, argStart, dataRanges))
+                    return true;
+            }
+        }
+        for (const m of text.matchAll(/\b(?:console\.(?:log|info|debug)|print)\s*\(([^)]*)\)/g)) {
+            const span = { start: m.index, end: m.index + m[0].length };
+            if (atoms.some((a) => a.start >= span.start && a.start < span.end && (lang === "shell" || !a.inData)))
+                return true;
+            const argText = m[1] ?? "";
+            const argStart = m.index + m[0].indexOf(argText);
+            for (const v of tainted) {
+                if (lang === "shell" || refOutsideData(argText, v, argStart, dataRanges))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
 function isLoopbackHost(host) {
     const h = host.toLowerCase();
     return h === "localhost" || h === "127.0.0.1" || h === "0.0.0.0" || h === "::1" || h === "[::1]";
@@ -129,15 +866,28 @@ const SAFE_PATTERNS = [
     /^patch-package$/i,
     /^simple-git-hooks$/i,
 ];
-export function classifyCommand(command) {
+export function classifyCommand(command, lang = "shell") {
     // Strip comments first (a docs URL in a comment is not a fetch), then
     // normalize shell line continuations and stray carriage returns, so a
     // payload split as `curl ... \` + newline + `| sh` classifies the same as
-    // the one line form.
-    const cmd = stripComments(command).replace(/\\\r?\n/g, " ").replace(/\r/g, " ").replace(/\n/g, " ").trim();
+    // the one line form. GitHub ${{ }} expressions are whitespace collapsed
+    // so URLs containing them parse as one token. Newlines are kept: the
+    // exfil value flow analysis works statement by statement.
+    const cmd = stripComments(command)
+        .replace(/\\\r?\n/g, " ")
+        .replace(/\r/g, " ")
+        .replace(/\$\{\{([\s\S]*?)\}\}/g, (_m, inner) => "${{" + inner.replace(/\s+/g, "") + "}}")
+        .trim();
+    // Behavior rules match the code view (P-019): quoted pattern text in a
+    // script file is data, not behavior. REMOTE-URL is the exception: a URL
+    // is a reference wherever it appears, so it matches the full text.
+    const views = buildViews(cmd, lang);
+    const joined = cmd.replace(/\n/g, " ");
+    const codeJoined = views.codeText.replace(/\n/g, " ");
     const fired = [];
     for (const rule of RISKY_RULES) {
-        if (rule.pattern.test(cmd))
+        const hay = rule.id === "REMOTE-URL" ? joined : codeJoined;
+        if (rule.pattern.test(hay))
             fired.push({ id: rule.id, evidence: rule.evidence });
     }
     // Loopback downgrade (P-004): a fetch whose every URL is loopback is a
@@ -150,20 +900,31 @@ export function classifyCommand(command) {
                 fired.splice(i, 1);
         }
     }
-    // Credential store access, content and path based (P-004).
-    if (detectCredAccess(cmd)) {
+    // Credential store access, content and path based (P-004), matched on
+    // the credential view so paths quoted as data in a script file (a
+    // guard's blocklist) do not count, while paths handed to file access
+    // calls do.
+    const credAccess = detectCredAccess(views.credText);
+    if (credAccess) {
         fired.push({ id: "CRED-ACCESS", evidence: "touches a credential store path or credential file" });
     }
-    // Env access, credential shaped names or bulk only (P-005).
-    const env = detectEnvAccess(cmd);
+    // Env access, credential shaped names or bulk only (P-005, P-020).
+    const env = detectEnvAccess(cmd, views.dataRanges);
     if (env.cred) {
         fired.push({ id: "ENV-ACCESS", evidence: "reads an environment variable whose name is credential shaped (token, secret, password, api key)" });
     }
     if (env.bulk) {
         fired.push({ id: "ENV-BULK", evidence: "accesses the whole environment at once (serialization, printenv, or env dump)" });
     }
-    if ((env.cred || env.bulk) && (fired.some((f) => f.id === "NET-FETCH" || f.id === "REMOTE-URL") || /\b(nc|netcat)\b/.test(cmd))) {
-        fired.push({ id: "ENV-EXFIL", evidence: "combines credential shaped or bulk environment access with an outbound send pattern" });
+    // Exfil is a value flow, not a co-occurrence (P-018): the credential
+    // value must reach a send. Token as authentication does not count.
+    if (analyzeExfil(cmd, views, lang)) {
+        fired.push({ id: "ENV-EXFIL", evidence: "a credential shaped or bulk environment value flows into an outbound send (payload, query string, printed output next to a send, or a pipe into a network tool); a token used as authentication does not count" });
+    }
+    if (credAccess && (/\|\s*(?:nc|netcat)\b/.test(joined) ||
+        /\|\s*(?:curl|wget)\b[^|\n]*?(?:-d\s+@-|--data(?:-raw|-binary)?\s+@-)/.test(joined) ||
+        /(?:-d|--data(?:-raw|-binary)?)\s+@[^\s"']*(?:\.ssh|\.aws|\.gnupg|id_rsa|credentials)/.test(joined))) {
+        fired.push({ id: "CRED-EXFIL", evidence: "credential store contents are piped or posted straight into an outbound network send" });
     }
     if (fired.length > 0) {
         return {
@@ -221,7 +982,7 @@ function escalateWithLocalFile(root, finding) {
         catch {
             continue;
         }
-        const inner = classifyCommand(content);
+        const inner = classifyCommand(content, langForFile(token));
         if (inner.classification === "RISKY") {
             const rules = Array.from(new Set([...out.rules, ...inner.rules]));
             out = {
@@ -272,13 +1033,22 @@ function escalateWithScriptChain(root, scripts, currentName, finding) {
     return out;
 }
 /**
- * Verdict calibration (Round 1, P-003 and P-004). COMPROMISED-PATTERN
- * requires strong evidence inside a single finding:
+ * Verdict calibration (Round 1, P-003 and P-004; Round 2, P-018).
+ * COMPROMISED-PATTERN requires strong evidence inside a single finding:
  *   (a) a severe rule: fetched or decoded content executed directly as
  *       code (curl piped to an interpreter, base64 decode piped to an
- *       interpreter, eval of fetched content), or
- *   (b) credential evidence (credential store access, a credential shaped
- *       env name, or bulk env access) combined with network behavior.
+ *       interpreter, eval of fetched content), or a verified exfil flow
+ *       (ENV-EXFIL, CRED-EXFIL), or
+ *   (b) credential STORE access (CRED-ACCESS: actual credential files
+ *       and stores) combined with network behavior.
+ * Round 2 narrowed path (b): in v0.1.2 and v0.1.3 any credential evidence
+ * counted, including a credential shaped env NAME next to a URL. On real
+ * estates that is the normal shape of a repo's own authenticated
+ * automation (a release step reading its token and pushing to its own
+ * repo), and it drove every one of the 15 false COMPROMISED drivers
+ * hand-read in Round 2. Env references plus network behavior are RISKY
+ * and verdict REVIEW; the verdict now needs the value to actually move
+ * (path a) or an actual credential store to be touched (path b).
  * Weak signals alone (a remote URL, a localhost fetch, an ordinary env
  * read, a download by itself) classify RISKY at most, and a RISKY-only
  * estate verdicts REVIEW, never COMPROMISED-PATTERN.
@@ -289,9 +1059,9 @@ export function computeVerdict(findings) {
         if (f.classification === "RISKY") {
             const metas = f.rules.map(ruleMeta);
             const hasSevere = metas.some((x) => x.severe);
-            const hasCred = metas.some((x) => x.credential);
+            const hasCredStore = f.rules.includes("CRED-ACCESS");
             const hasNet = metas.some((x) => x.remote);
-            if (hasSevere || (hasCred && hasNet))
+            if (hasSevere || (hasCredStore && hasNet))
                 return "COMPROMISED-PATTERN";
             review = true;
         }
@@ -723,6 +1493,13 @@ function scanWorkflows(root, findings) {
 function scanGitHooks(root, findings) {
     scanDirFiles(root, ".githooks", "githooks", findings);
 }
+/**
+ * Empty estate note (P-014, hookcheck half). A scan that inventories
+ * nothing must say so next to the verdict, in JSON as well as in the
+ * human output: CLEAN with total 0 is vacuously true and otherwise reads
+ * as an all-clear.
+ */
+export const EMPTY_ESTATE_NOTE = "Nothing was found to audit: no auto-exec hooks were inventoried under this path, so the verdict covers an empty estate. This can mean a hook-free repo, an empty directory, or a path that is not a repo root.";
 export function scanHooks(root) {
     const findings = [];
     const warnings = [];
@@ -739,6 +1516,7 @@ export function scanHooks(root) {
             path: root, verdict: "REVIEW", findings, warnings,
             counts: { total: 0, safe: 0, risky: 0, unknown: 0 },
             scannedAt: new Date().toISOString(),
+            note: EMPTY_ESTATE_NOTE,
         };
     }
     if (!rootStat.isDirectory()) {
@@ -747,6 +1525,7 @@ export function scanHooks(root) {
             path: root, verdict: "REVIEW", findings, warnings,
             counts: { total: 0, safe: 0, risky: 0, unknown: 0 },
             scannedAt: new Date().toISOString(),
+            note: EMPTY_ESTATE_NOTE,
         };
     }
     scanPackageJson(root, findings, warnings);
@@ -782,6 +1561,7 @@ export function scanHooks(root) {
         counts,
         warnings,
         scannedAt: new Date().toISOString(),
+        ...(counts.total === 0 ? { note: EMPTY_ESTATE_NOTE } : {}),
     };
 }
 export function explainHook(root, idOrFile) {
@@ -807,6 +1587,8 @@ export function renderReport(report) {
     const lines = [];
     lines.push(`hookcheck ${report.path}: ${report.verdict}`);
     lines.push(`  ${report.counts.total} hook(s): ${report.counts.safe} SAFE, ${report.counts.risky} RISKY, ${report.counts.unknown} UNKNOWN`);
+    if (report.note)
+        lines.push(`  note: ${report.note}`);
     for (const f of report.findings) {
         lines.push(`  [${f.classification}] ${f.id} (${f.source}${f.line !== undefined ? `, line ${f.line}` : ""})`);
         lines.push(`      command: ${f.command.slice(0, 200)}`);
@@ -821,7 +1603,7 @@ export function renderReport(report) {
     else if (report.verdict === "REVIEW")
         lines.push("REVIEW: at least one hook needs manual review.");
     else
-        lines.push("COMPROMISED-PATTERN: at least one risky hook shows strong evidence: fetched or decoded content executed as code, or credential access combined with network behavior. Treat as a Shai-Hulud style persistence pattern until proven otherwise.");
+        lines.push("COMPROMISED-PATTERN: at least one risky hook shows strong evidence: fetched or decoded content executed as code, credential values flowing into an outbound send, or credential store access combined with network behavior. Treat as a Shai-Hulud style persistence pattern until proven otherwise.");
     return lines.join("\n");
 }
 export { relative };