@vola-trebla/croak 0.0.0-stage → 0.1.1

package/dist/detectors/ide-autorun.js

@@ -0,0 +1,127 @@
+import { posix } from "node:path";
+import { JsoncError, parseJsonc } from "../signals/jsonc.js";
+import { stripBom } from "../signals/text.js";
+import { assessor } from "./lifecycle-script.js";
+import { isInNodeModules } from "./node-modules-present.js";
+const RULE = "repo/ide-autorun";
+const TASKS_FILE = ".vscode/tasks.json";
+const MAX_SHOWN = 80;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const asString = (value) => typeof value === "string" ? value : undefined;
+const truncate = (text) => text.length > MAX_SHOWN ? `${text.slice(0, MAX_SHOWN)}…` : text;
+function folderOpenLines(text) {
+    return text
+        .split("\n")
+        .flatMap((line, index) => (line.includes("folderOpen") ? [index + 1] : []));
+}
+function manifestFor(repo, tasksPath) {
+    const folder = posix.dirname(posix.dirname(tasksPath));
+    const dir = folder === "." ? "" : folder;
+    const text = repo.read(dir === "" ? "package.json" : `${dir}/package.json`);
+    if (text === undefined)
+        return { dir, scripts: {} };
+    try {
+        const manifest = JSON.parse(stripBom(text));
+        return {
+            dir,
+            scripts: isRecord(manifest) && isRecord(manifest.scripts)
+                ? manifest.scripts
+                : {},
+        };
+    }
+    catch {
+        return { dir, scripts: {} };
+    }
+}
+function taskFinding(repo, path, task, line, trigger) {
+    const label = asString(task.label) ?? "(unnamed task)";
+    const presentation = isRecord(task.presentation) ? task.presentation : {};
+    const hidden = presentation.reveal === "never" ? ", with its terminal hidden" : "";
+    const at = line === undefined ? { file: path } : { file: path, line };
+    if (task.type === "npm") {
+        const script = asString(task.script) ?? "";
+        const { dir, scripts } = manifestFor(repo, path);
+        const command = asString(scripts[script]);
+        const assessment = command === undefined ? undefined : assessor(repo, dir, scripts)(command);
+        const shown = command === undefined
+            ? "not found in package.json"
+            : `\`${truncate(command)}\``;
+        const reasons = assessment !== undefined && assessment.reasons.length > 0
+            ? `: ${assessment.reasons.join("; ")}`
+            : "";
+        return {
+            ruleId: RULE,
+            severity: assessment?.block === true ? "block" : "warn",
+            ...at,
+            message: `task "${label}" runs npm script "${script}" (${shown}) ${trigger}${hidden}${reasons}`,
+        };
+    }
+    const args = Array.isArray(task.args)
+        ? task.args.filter((a) => typeof a === "string")
+        : [];
+    const command = [asString(task.command) ?? "(command)", ...args].join(" ");
+    return {
+        ruleId: RULE,
+        severity: "block",
+        ...at,
+        message: `task "${label}" runs \`${truncate(command)}\` automatically ${trigger}${hidden}`,
+    };
+}
+const dependsOnLabels = (task) => {
+    const deps = task.dependsOn;
+    if (typeof deps === "string")
+        return [deps];
+    return Array.isArray(deps)
+        ? deps.filter((d) => typeof d === "string")
+        : [];
+};
+function tasksFindings(repo, path) {
+    const text = repo.read(path);
+    if (text === undefined)
+        return [];
+    let config;
+    try {
+        config = parseJsonc(stripBom(text));
+    }
+    catch (error) {
+        if (!(error instanceof JsoncError))
+            throw error;
+        return [
+            {
+                ruleId: RULE,
+                severity: "warn",
+                file: path,
+                message: `tasks.json could not be parsed (${error.message}); VS Code may still run its tasks`,
+            },
+        ];
+    }
+    const tasks = isRecord(config) && Array.isArray(config.tasks)
+        ? config.tasks.filter(isRecord)
+        : [];
+    const byLabel = new Map(tasks.flatMap((task) => typeof task.label === "string" ? [[task.label, task]] : []));
+    const autorun = tasks.filter((task) => isRecord(task.runOptions) && task.runOptions.runOn === "folderOpen");
+    const lines = folderOpenLines(text);
+    const findings = autorun.map((task, index) => taskFinding(repo, path, task, lines[index], "when the folder is opened"));
+    const seen = new Set(autorun);
+    const queue = autorun.flatMap((task) => dependsOnLabels(task).map((dep) => ({
+        dep,
+        parent: asString(task.label) ?? "",
+    })));
+    while (queue.length > 0) {
+        const next = queue.shift();
+        const task = next === undefined ? undefined : byLabel.get(next.dep);
+        if (next === undefined || task === undefined || seen.has(task))
+            continue;
+        seen.add(task);
+        findings.push(taskFinding(repo, path, task, undefined, `when the folder is opened (folder-open task "${next.parent}" depends on it)`));
+        queue.push(...dependsOnLabels(task).map((dep) => ({ dep, parent: next.dep })));
+    }
+    return findings;
+}
+export const ideAutorun = (repo) => repo.entries
+    .filter((e) => e.kind === "file" &&
+    (e.path === TASKS_FILE || e.path.endsWith(`/${TASKS_FILE}`)) &&
+    !isInNodeModules(e.path))
+    .flatMap((e) => tasksFindings(repo, e.path));

package/dist/detectors/index.js

@@ -0,0 +1,19 @@
+import { gitConfig } from "./git-config.js";
+import { hiddenCodeDetector } from "./hidden-code.js";
+import { ideAutorun } from "./ide-autorun.js";
+import { lifecycleScript } from "./lifecycle-script.js";
+import { nodeModulesPresent } from "./node-modules-present.js";
+import { obfuscation } from "./obfuscation.js";
+import { unscanned } from "./unscanned.js";
+export const repoDetectors = [
+    unscanned,
+    nodeModulesPresent,
+    lifecycleScript,
+    ideAutorun,
+    hiddenCodeDetector,
+    obfuscation,
+    gitConfig,
+];
+export function scanRepo(repo, detectors = repoDetectors) {
+    return detectors.flatMap((detect) => detect(repo));
+}

package/dist/detectors/lifecycle-script.js

@@ -0,0 +1,298 @@
+import { posix } from "node:path";
+import { codeSignals, describeSignals, isSuspicious, } from "../signals/code.js";
+import { analyzeShell } from "../signals/shell.js";
+import { stripBom } from "../signals/text.js";
+import { isInNodeModules } from "./node-modules-present.js";
+const RULE = "repo/lifecycle-script";
+export const INSTALL_SCRIPTS = [
+    "preinstall",
+    "install",
+    "postinstall",
+    "prepublish",
+    "preprepare",
+    "prepare",
+    "postprepare",
+    "dependencies",
+];
+export const DEPENDENCY_INSTALL_SCRIPTS = [
+    "preinstall",
+    "install",
+    "postinstall",
+];
+const BUNDLED_MANIFEST = /(?:^|\/)node_modules\/(?:@[^/]+\/)?[^/@][^/]*\/package\.json$/;
+const INERT_TOOLS = new Set([
+    "husky",
+    "simple-git-hooks",
+    "lefthook",
+    "only-allow",
+    "opencollective-postinstall",
+    "playwright",
+    "tsc",
+    "esbuild",
+    "swc",
+    "echo",
+    "true",
+    "exit",
+    "printf",
+]);
+const EXECUTING_TOOLS = new Set([
+    "prisma",
+    "vite",
+    "webpack",
+    "rollup",
+    "tsup",
+    "unbuild",
+    "babel",
+    "nuxt",
+    "nuxi",
+    "svelte-kit",
+    "astro",
+    "ngcc",
+    "turbo",
+    "nx",
+    "lerna",
+    "patch-package",
+    "rimraf",
+]);
+const KNOWN_TOOLS = new Set([...INERT_TOOLS, ...EXECUTING_TOOLS]);
+const PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn", "bun"]);
+const MAX_SCRIPT_DEPTH = 5;
+const SHELL_DECODE = /\bbase64\s+(?:-d|-D|--decode)\b|\bopenssl\s+(?:enc|base64)\b[^|;&]*\s-d\b/;
+const MAX_SHOWN = 80;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const truncate = (text) => text.length > MAX_SHOWN ? `${text.slice(0, MAX_SHOWN)}…` : text;
+function scriptLine(manifest, name) {
+    const lines = manifest.split("\n");
+    const scripts = lines.findIndex((line) => /"scripts"\s*:/.test(line));
+    const key = `"${name}"`;
+    const index = lines.findIndex((line, i) => i >= Math.max(scripts, 0) &&
+        line.includes(key) &&
+        /"\s*:/.test(line.slice(line.indexOf(key))));
+    return index === -1 ? undefined : index + 1;
+}
+function routineChecker(scripts) {
+    const memo = new Map();
+    const scriptIsRoutine = (name, depth) => {
+        const known = memo.get(name);
+        if (known !== undefined)
+            return known;
+        memo.set(name, false);
+        const body = scripts[name];
+        const result = typeof body === "string" &&
+            commandIsRoutine(body, depth + 1) &&
+            [`pre${name}`, `post${name}`].every((hook) => !(hook in scripts) || scriptIsRoutine(hook, depth + 1));
+        memo.set(name, result);
+        return result;
+    };
+    const commandIsRoutine = (command, depth) => {
+        if (depth > MAX_SCRIPT_DEPTH)
+            return false;
+        const facts = analyzeShell(command);
+        if (facts.unparsable ||
+            facts.downloadExecute ||
+            facts.network ||
+            facts.localFiles.length > 0 ||
+            facts.inlineCode.length > 0 ||
+            facts.modifiers.length > 0 ||
+            codeSignals(command).length > 0 ||
+            facts.commands.length === 0) {
+            return false;
+        }
+        const pmCalls = facts.commands.filter((name) => PACKAGE_MANAGERS.has(name)).length;
+        if (pmCalls !== facts.runScripts.length)
+            return false;
+        if (!facts.commands.every((name) => INERT_TOOLS.has(name) || PACKAGE_MANAGERS.has(name)))
+            return false;
+        return facts.runScripts.every((name) => scriptIsRoutine(name, depth));
+    };
+    return (command) => commandIsRoutine(command, 0);
+}
+export function assessor(repo, dir, scripts, suspicious = isSuspicious) {
+    const memo = new Map();
+    const empty = {
+        block: false,
+        reasons: [],
+        knownTools: [],
+        signals: new Set(),
+    };
+    const assessScript = (name, depth) => {
+        const known = memo.get(name);
+        if (known !== undefined)
+            return known;
+        memo.set(name, empty);
+        const body = scripts[name];
+        const result = typeof body !== "string"
+            ? {
+                ...empty,
+                reasons: [`calls script "${name}", which is not in package.json`],
+            }
+            : assessCommand(body, depth + 1);
+        memo.set(name, result);
+        return result;
+    };
+    const assessCommand = (command, depth) => {
+        if (depth > MAX_SCRIPT_DEPTH)
+            return { ...empty, reasons: ["scripts are nested too deeply to follow"] };
+        const facts = analyzeShell(command);
+        if (facts.unparsable) {
+            return facts.mentionsDownloader
+                ? {
+                    ...empty,
+                    block: true,
+                    reasons: [
+                        "could not be parsed and mentions a download tool (failing closed)",
+                    ],
+                }
+                : {
+                    ...empty,
+                    reasons: [
+                        "the command could not be parsed, so croak cannot tell what it runs",
+                    ],
+                };
+        }
+        const reasons = [];
+        const signals = new Set();
+        const knownTools = new Set(facts.commands.filter((name) => KNOWN_TOOLS.has(name)));
+        let nestedBlock = false;
+        const absorb = (hits, where) => {
+            if (hits.length === 0)
+                return;
+            for (const hit of hits)
+                signals.add(hit.signal);
+            reasons.push(describeSignals(hits, where));
+        };
+        if (facts.downloadExecute)
+            reasons.push("downloads and executes code");
+        if (facts.network) {
+            signals.add("network");
+            reasons.push("uses the network");
+        }
+        if (SHELL_DECODE.test(command))
+            signals.add("decode");
+        absorb(codeSignals(command), "the command");
+        for (const code of facts.inlineCode)
+            absorb(codeSignals(code), "inline code");
+        for (const file of facts.localFiles) {
+            const path = posix.normalize(posix.join(dir, file));
+            if (path === ".." || path.startsWith("../")) {
+                reasons.push(`runs ${file}, a path outside the repo`);
+                continue;
+            }
+            const entry = repo.entries.find((e) => e.path === path);
+            if (entry === undefined)
+                reasons.push(`runs ${path}, which is not in the repo`);
+            else if (entry.kind === "oversized")
+                reasons.push(`runs ${path}, too large to scan`);
+            else if (entry.kind === "symlink")
+                reasons.push(`runs ${path}, a symlink croak does not follow`);
+            else
+                absorb(codeSignals(repo.read(path) ?? ""), path);
+        }
+        for (const name of facts.runScripts) {
+            for (const script of [`pre${name}`, name, `post${name}`]) {
+                if (script !== name && !(script in scripts))
+                    continue;
+                const sub = assessScript(script, depth);
+                nestedBlock ||= sub.block;
+                for (const signal of sub.signals)
+                    signals.add(signal);
+                for (const tool of sub.knownTools)
+                    knownTools.add(tool);
+                if (sub.reasons.length > 0)
+                    reasons.push(`via script "${script}": ${sub.reasons.join("; ")}`);
+            }
+        }
+        return {
+            block: facts.downloadExecute || nestedBlock || suspicious(signals),
+            reasons,
+            knownTools: [...knownTools],
+            signals,
+        };
+    };
+    return (command) => assessCommand(command, 0);
+}
+function manifestFindings(repo, path, { suspicious, scripts: installScripts }) {
+    const dir = posix.dirname(path) === "." ? "" : posix.dirname(path);
+    const text = repo.read(path);
+    if (text === undefined)
+        return [];
+    let manifest;
+    try {
+        manifest = JSON.parse(stripBom(text));
+    }
+    catch {
+        return [
+            {
+                ruleId: RULE,
+                severity: "warn",
+                file: path,
+                message: "package.json is not valid JSON; croak cannot see its install scripts",
+            },
+        ];
+    }
+    const scripts = isRecord(manifest) && isRecord(manifest.scripts) ? manifest.scripts : {};
+    const findings = [];
+    const isRoutine = routineChecker(scripts);
+    const assess = assessor(repo, dir, scripts, suspicious);
+    for (const name of installScripts) {
+        const command = scripts[name];
+        if (typeof command !== "string")
+            continue;
+        const { block, reasons, knownTools } = assess(command);
+        const line = scriptLine(text, name);
+        const at = line === undefined ? { file: path } : { file: path, line };
+        if (!block && isRoutine(command)) {
+            findings.push({
+                ruleId: RULE,
+                severity: "info",
+                ...at,
+                message: `${name} runs \`${truncate(command)}\` on install: known tools only, nothing suspicious`,
+            });
+            continue;
+        }
+        findings.push({
+            ruleId: RULE,
+            severity: block ? "block" : "warn",
+            ...at,
+            message: `${name} runs \`${truncate(command)}\` on install${reasons.length > 0 ? `: ${reasons.join("; ")}` : ""}`,
+        });
+        for (const tool of knownTools) {
+            findings.push({
+                ruleId: RULE,
+                severity: "info",
+                ...at,
+                message: `${name} uses ${tool}, a known install-time tool`,
+            });
+        }
+    }
+    const gyp = posix.join(dir, "binding.gyp");
+    if (!("install" in scripts) &&
+        !("preinstall" in scripts) &&
+        repo.entries.some((e) => e.path === gyp)) {
+        findings.push({
+            ruleId: RULE,
+            severity: "warn",
+            file: gyp,
+            message: "binding.gyp makes npm run `node-gyp rebuild` on install; gyp files can run arbitrary build actions",
+        });
+    }
+    return findings;
+}
+export function lifecycleScriptWith(policy) {
+    return (repo) => repo.entries
+        .filter((e) => e.kind === "file" &&
+        (policy.manifests === "root"
+            ? e.path === "package.json"
+            : policy.manifests === "package"
+                ? e.path === "package.json" || BUNDLED_MANIFEST.test(e.path)
+                : posix.basename(e.path) === "package.json" &&
+                    !isInNodeModules(e.path)))
+        .flatMap((e) => manifestFindings(repo, e.path, policy));
+}
+export const lifecycleScript = lifecycleScriptWith({
+    suspicious: isSuspicious,
+    scripts: INSTALL_SCRIPTS,
+    manifests: "repo",
+});

package/dist/detectors/node-modules-present.js

@@ -0,0 +1,25 @@
+const SEGMENT = "node_modules";
+function nodeModulesRoot(path) {
+    const segments = path.split("/");
+    const index = segments.indexOf(SEGMENT);
+    return index === -1 ? undefined : segments.slice(0, index + 1).join("/");
+}
+export function isInNodeModules(path) {
+    return nodeModulesRoot(path) !== undefined;
+}
+export const nodeModulesPresent = (repo) => {
+    const counts = new Map();
+    for (const { path } of repo.entries) {
+        const root = nodeModulesRoot(path);
+        if (root !== undefined)
+            counts.set(root, (counts.get(root) ?? 0) + 1);
+    }
+    return [...counts]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([root, count]) => ({
+        ruleId: "repo/node-modules-present",
+        severity: "warn",
+        file: root,
+        message: `node_modules present (${count} ${count === 1 ? "file" : "files"}): croak repo checks repos before install, so a fresh clone should not contain installed dependencies`,
+    }));
+};

package/dist/detectors/obfuscation.js

@@ -0,0 +1,98 @@
+import { CODE_PATTERNS } from "../signals/code.js";
+import { OBFUSCATION_PATTERNS, obfuscationSignals, } from "../signals/obfuscation.js";
+import { isInNodeModules } from "./node-modules-present.js";
+const RULE = "repo/obfuscation";
+const LEAD = {
+    info: "unusual encoding, common in generated or vendored code",
+    warn: "looks obfuscated",
+    block: "obfuscated code",
+};
+const SCANNED = /\.[cm]?[jt]sx?$/;
+const DECLARATIONS = /\.d\.[cm]?ts$/;
+const WEAK = new Set(["escapes", "encoded-blob"]);
+const FILE_WIDE = new Set(["obfuscator-names"]);
+const NEARBY_LINES = 3;
+const LONG_LINE = 1000;
+const NEARBY_CHARS = 200;
+const patternsOf = (...signals) => CODE_PATTERNS.filter((p) => signals.includes(p.signal)).map((p) => p.pattern);
+const EXECUTES = patternsOf("eval");
+const EXECUTES_OR_DECODES = patternsOf("eval", "decode");
+function spans(lines, patterns, onLines) {
+    const found = [];
+    let offset = 0;
+    lines.forEach((text, index) => {
+        const line = index + 1;
+        if (onLines === undefined || onLines.has(line)) {
+            for (const pattern of patterns) {
+                for (const m of text.matchAll(new RegExp(pattern.source, "g"))) {
+                    const start = offset + (m.index ?? 0);
+                    found.push({ line, start, end: start + m[0].length });
+                }
+            }
+        }
+        offset += text.length + 1;
+    });
+    return found;
+}
+const gap = (a, b) => Math.max(0, Math.max(a.start, b.start) - Math.min(a.end, b.end));
+function nearCall(lines, hit, calls) {
+    const patterns = OBFUSCATION_PATTERNS.filter((p) => p.kind === hit.kind);
+    const threshold = Math.min(...patterns.map((p) => p.threshold));
+    const short = (line) => (lines[line - 1]?.length ?? 0) <= LONG_LINE;
+    const marks = spans(lines, patterns.map((p) => p.pattern), new Set(hit.lines));
+    return calls.some((call) => {
+        if (short(call.line) &&
+            hit.lines.some((at) => short(at) && Math.abs(at - call.line) <= NEARBY_LINES))
+            return true;
+        return (marks.filter((m) => gap(m, call) <= NEARBY_CHARS).length >= threshold);
+    });
+}
+function assess(lines, hits) {
+    const kinds = new Set(hits.map((hit) => hit.kind));
+    const strong = [...kinds].filter((kind) => !WEAK.has(kind)).length;
+    const markedBy = (hit) => spans(lines, OBFUSCATION_PATTERNS.filter((p) => p.kind === hit.kind).map((p) => p.pattern), new Set(hit.lines));
+    const together = hits.some((hit) => FILE_WIDE.has(hit.kind)) ||
+        hits.some((hit) => !WEAK.has(hit.kind) &&
+            hits.some((other) => other.kind !== hit.kind && nearCall(lines, hit, markedBy(other))));
+    if (strong >= 1 && kinds.size >= 2 && together)
+        return { raw: "block", why: "" };
+    const executes = spans(lines, EXECUTES);
+    const decodes = spans(lines, EXECUTES_OR_DECODES);
+    const near = hits.some((hit) => FILE_WIDE.has(hit.kind)
+        ? decodes.length > 0
+        : nearCall(lines, hit, WEAK.has(hit.kind) ? executes : decodes));
+    if (near)
+        return { raw: "block", why: ", next to eval or decoding" };
+    return { raw: strong >= 1 ? "warn" : "info", why: "" };
+}
+function fileFinding(path, text, downgradeInstalled) {
+    const hits = obfuscationSignals(text);
+    const first = hits[0];
+    if (first === undefined)
+        return undefined;
+    const { raw, why } = assess(text.split("\n"), hits);
+    const severity = downgradeInstalled && isInNodeModules(path) && raw === "block"
+        ? "warn"
+        : raw;
+    const seen = hits.map((hit) => `${hit.kind} (line ${hit.line})`).join(", ");
+    return {
+        ruleId: RULE,
+        severity,
+        file: path,
+        line: first.line,
+        message: `${LEAD[severity]}: ${seen}${raw === "block" ? why : ""}`,
+    };
+}
+export function obfuscationWith({ downgradeInstalled, }) {
+    return (repo) => repo.entries
+        .filter((e) => e.kind === "file" &&
+        SCANNED.test(e.path) &&
+        !DECLARATIONS.test(e.path))
+        .flatMap((e) => {
+        const finding = fileFinding(e.path, repo.read(e.path) ?? "", downgradeInstalled);
+        return finding === undefined ? [] : [finding];
+    });
+}
+export const obfuscation = obfuscationWith({
+    downgradeInstalled: true,
+});

package/dist/detectors/unscanned.js

@@ -0,0 +1,33 @@
+import { isInNodeModules } from "./node-modules-present.js";
+const CODE = /\.(?:[cm]?[jt]sx?|json|sh|bash|zsh|py|rb|pl|ps1|gyp)$/;
+const LOCKFILES = new Set(["package-lock.json", "npm-shrinkwrap.json"]);
+const DECLARATIONS = /\.d\.[cm]?ts$/;
+export function unscannedWith({ jsonIsData, downgradeInstalled, }) {
+    return (repo) => repo.entries
+        .filter((entry) => entry.kind === "oversized")
+        .filter((entry) => {
+        const name = entry.path.slice(entry.path.lastIndexOf("/") + 1);
+        return (entry.path.startsWith(".git/") ||
+            /(?:^|\/)\.husky\//.test(entry.path) ||
+            (CODE.test(name) && !LOCKFILES.has(name) && !DECLARATIONS.test(name)));
+    })
+        .map((entry) => {
+        const name = entry.path.slice(entry.path.lastIndexOf("/") + 1);
+        const data = jsonIsData && name.endsWith(".json") && name !== "package.json";
+        const installed = downgradeInstalled && isInNodeModules(entry.path);
+        return {
+            ruleId: "repo/unscanned",
+            severity: installed || data ? "info" : "warn",
+            file: entry.path,
+            message: data
+                ? `${entry.size} bytes exceeds the read limit; not scanned (JSON data, not executed)`
+                : installed
+                    ? `${entry.size} bytes exceeds the read limit; not scanned (installed dependency)`
+                    : `${entry.size} bytes exceeds the read limit; not scanned`,
+        };
+    });
+}
+export const unscanned = unscannedWith({
+    jsonIsData: false,
+    downgradeInstalled: true,
+});