selfguard 0.0.1 → 0.2.0

package/dist/report.js

@@ -0,0 +1,126 @@
+import { homedir } from "node:os";
+import { severityRank } from "./match.js";
+import { compare, isValid } from "./semver.js";
+import { clean } from "./sanitize.js";
+function useColor(stream) {
+    return Boolean(stream.isTTY) && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+}
+export function paint(stream) {
+    const on = useColor(stream);
+    const wrap = (open, close) => (s) => (on ? `\x1b[${open}m${s}\x1b[${close}m` : s);
+    return {
+        bold: wrap(1, 22),
+        dim: wrap(2, 22),
+        red: wrap(31, 39),
+        yellow: wrap(33, 39),
+        green: wrap(32, 39),
+        magenta: wrap(35, 39),
+        cyan: wrap(36, 39),
+        inverseRed: wrap(41, 49),
+    };
+}
+export function severityLabel(s, c) {
+    switch (s) {
+        case "malicious":
+            return c.inverseRed(c.bold(" MALICIOUS "));
+        case "critical":
+            return c.red(c.bold("CRITICAL"));
+        case "high":
+            return c.red("HIGH");
+        case "moderate":
+            return c.yellow("MODERATE");
+        case "low":
+            return c.dim("LOW");
+        default:
+            return c.dim("UNKNOWN");
+    }
+}
+export function tildify(p) {
+    const home = homedir();
+    return p === home || p.startsWith(`${home}/`) ? `~${p.slice(home.length)}` : p;
+}
+export function countBySeverity(findings) {
+    const counts = {};
+    for (const f of findings)
+        counts[f.severity] = (counts[f.severity] ?? 0) + 1;
+    return counts;
+}
+export function summarizeCounts(findings) {
+    const counts = countBySeverity(findings);
+    const order = ["malicious", "critical", "high", "moderate", "low", "unknown"];
+    return order
+        .filter((s) => counts[s])
+        .map((s) => `${counts[s]} ${s}`)
+        .join(", ");
+}
+export function renderFindings(rec, stream, verbose = false) {
+    const c = paint(stream);
+    const lines = [];
+    const title = `${c.bold(tildify(rec.path))}  ${c.dim(`${rec.deps.length} packages`)}`;
+    lines.push(title);
+    if (rec.error)
+        lines.push(`  ${c.yellow("!")} ${clean(rec.error)}`);
+    if (rec.skipped > 0)
+        lines.push(c.dim(`  ${rec.skipped} entries skipped (git/file/link deps)`));
+    if (rec.findings.length === 0) {
+        if (!rec.error)
+            lines.push(`  ${c.green("✓")} no known vulnerabilities`);
+        return lines.join("\n");
+    }
+    const groups = groupByPackage(rec.findings);
+    lines.push(`  ${groups.length} vulnerable package(s), ${rec.findings.length} advisories: ${summarizeCounts(rec.findings)}`);
+    for (const g of groups) {
+        const pkg = `${clean(g.name, 120)}@${clean(g.version, 60)}`;
+        const tags = [g.direct ? "direct" : "transitive", g.dev ? "dev" : ""].filter(Boolean).join(", ");
+        lines.push("");
+        lines.push(`  ${severityLabel(g.worst, c)} ${c.bold(pkg)} ${c.dim(`(${tags})`)}`);
+        if (g.worst === "malicious") {
+            lines.push(`    ${c.red("→ remove it now and rotate any credentials available on this machine/CI")}`);
+        }
+        else if (g.upgradeTo) {
+            const partial = g.unfixed > 0 ? c.yellow(` (${g.unfixed} advisory(ies) have no fix yet)`) : "";
+            lines.push(`    ${c.green(`→ upgrade to ${clean(g.upgradeTo, 60)} or later`)}${partial}`);
+        }
+        else {
+            lines.push(`    ${c.yellow("→ no fixed version published; consider replacing it")}`);
+        }
+        const shown = verbose ? g.findings : g.findings.slice(0, 3);
+        for (const f of shown) {
+            lines.push(`    ${c.dim("•")} ${clean(f.id, 64)} ${c.dim(f.severity)}${f.summary ? ` ${clean(f.summary, 90)}` : ""}`);
+        }
+        if (shown.length < g.findings.length)
+            lines.push(c.dim(`    • …and ${g.findings.length - shown.length} more (--verbose)`));
+    }
+    lines.push("");
+    lines.push(c.dim("  Details: https://osv.dev/vulnerability/<ID>"));
+    return lines.join("\n");
+}
+export function worstSeverity(findings) {
+    const order = ["malicious", "critical", "high", "moderate", "low", "unknown"];
+    for (const s of order)
+        if (findings.some((f) => f.severity === s))
+            return s;
+    return null;
+}
+export function groupByPackage(findings) {
+    const map = new Map();
+    for (const f of findings) {
+        const key = `${f.name}@${f.version}`;
+        let g = map.get(key);
+        if (!g) {
+            g = { name: f.name, version: f.version, direct: f.direct, dev: f.dev, worst: f.severity, findings: [], unfixed: 0 };
+            map.set(key, g);
+        }
+        g.findings.push(f);
+        if (severityRank(f.severity) < severityRank(g.worst))
+            g.worst = f.severity;
+        if (f.fixedIn && isValid(f.fixedIn)) {
+            if (!g.upgradeTo || compare(f.fixedIn, g.upgradeTo) > 0)
+                g.upgradeTo = f.fixedIn;
+        }
+        else {
+            g.unfixed++;
+        }
+    }
+    return [...map.values()].sort((a, b) => severityRank(a.worst) - severityRank(b.worst) || Number(b.direct) - Number(a.direct) || a.name.localeCompare(b.name));
+}

package/dist/sanitize.js

@@ -0,0 +1,12 @@
+/**
+ * Everything we print comes from untrusted sources (lockfiles, advisory text).
+ * Strip control characters so nobody can inject terminal escape sequences
+ * (cursor movement, OSC 8 links, title changes, clipboard writes...) and
+ * bidirectional overrides ("Trojan Source" style spoofing).
+ */
+const CONTROL = new RegExp("[\\u0000-\\u0008\\u000B-\\u001F\\u007F-\\u009F\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u2069]", "g");
+export function clean(input, maxLen = 300, opts = {}) {
+    const stripped = String(input ?? "").replace(CONTROL, "");
+    const s = (opts.multiline ? stripped.replace(/\n{3,}/g, "\n\n") : stripped.replace(/\s*\n\s*/g, " ")).trim();
+    return s.length > maxLen ? `${s.slice(0, maxLen - 1)}…` : s;
+}

package/dist/scan.js

@@ -0,0 +1,197 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { sha256 } from "./fsutil.js";
+import { isSupported, parseLockfile } from "./lockfile/index.js";
+import { evaluate, severityOf, severityRank } from "./match.js";
+import { getVulns, queryBatch } from "./osv.js";
+import { repoIdentity } from "./repoid.js";
+import { clean } from "./sanitize.js";
+import { findingKey, loadRepo } from "./store.js";
+const MAX_LOCKFILE_BYTES = 100 * 1024 * 1024;
+export function lockState(lockfile) {
+    try {
+        const st = statSync(lockfile);
+        if (!st.isFile() || st.size > MAX_LOCKFILE_BYTES)
+            return null;
+        return { hash: sha256(readFileSync(lockfile)), mtimeMs: st.mtimeMs, size: st.size };
+    }
+    catch {
+        return null;
+    }
+}
+/** Cheap check first (mtime+size), hash only if those changed. */
+export function lockChanged(rec, project) {
+    if (rec.lockfile !== project.lockfile)
+        return true;
+    if (!project.lockfile)
+        return false;
+    try {
+        const st = statSync(project.lockfile);
+        if (st.mtimeMs === rec.lockMtimeMs && st.size === rec.lockSize)
+            return false;
+    }
+    catch {
+        return true;
+    }
+    return lockState(project.lockfile)?.hash !== rec.lockHash;
+}
+/** Parse a project's lockfile into a fresh (findings-less) record. Never executes project code. */
+function inventory(project) {
+    const previous = loadRepo(project.root);
+    const now = new Date().toISOString();
+    const record = {
+        schema: 1,
+        path: project.root,
+        lockfile: project.lockfile,
+        lockType: project.lockType,
+        lockHash: null,
+        lockMtimeMs: null,
+        lockSize: null,
+        registeredAt: previous?.registeredAt ?? now,
+        scannedAt: null,
+        deps: [],
+        skipped: 0,
+        findings: [],
+        branch: repoIdentity(project.root)?.branch ?? null,
+    };
+    if (!project.lockfile || !project.lockType) {
+        record.error = "no lockfile found (run your package manager's install to create one)";
+        record.scannedAt = now;
+        return { record, previous };
+    }
+    const st = lockState(project.lockfile);
+    if (!st) {
+        record.error = "lockfile unreadable or too large";
+        record.scannedAt = now;
+        return { record, previous };
+    }
+    Object.assign(record, { lockHash: st.hash, lockMtimeMs: st.mtimeMs, lockSize: st.size });
+    if (!isSupported(project.lockType, project.lockfile)) {
+        record.error = "bun.lockb (binary) is not supported; run `bun install --save-text-lockfile` to create bun.lock";
+        record.scannedAt = now;
+        return { record, previous };
+    }
+    try {
+        let manifest;
+        try {
+            manifest = JSON.parse(readFileSync(join(project.root, "package.json"), "utf8"));
+        }
+        catch {
+            manifest = undefined;
+        }
+        const parsed = parseLockfile(project.lockType, readFileSync(project.lockfile, "utf8"), manifest);
+        record.deps = parsed.deps;
+        record.skipped = parsed.skipped;
+    }
+    catch (err) {
+        record.error = `could not parse lockfile: ${clean(err.message, 200)}`;
+        record.scannedAt = now;
+    }
+    return { record, previous };
+}
+function buildFindings(deps, refsPerDep, vulns, previous, now) {
+    const prevSeen = new Map((previous?.findings ?? []).map((f) => [findingKey(f), f.firstSeen]));
+    const findings = [];
+    for (const dep of deps) {
+        const ids = refsPerDep.get(`${dep.name}@${dep.version}`) ?? [];
+        const reported = new Set();
+        for (const id of ids) {
+            const vuln = vulns.get(id);
+            if (vuln?.withdrawn)
+                continue;
+            // Collapse duplicates published under several ids (e.g. GHSA + CVE alias).
+            if (vuln?.aliases?.some((a) => reported.has(a)) || reported.has(id))
+                continue;
+            reported.add(id);
+            const ev = vuln ? evaluate(vuln, dep.name, dep.version) : { affected: true };
+            const f = {
+                id,
+                aliases: (vuln?.aliases ?? []).map((a) => clean(a, 64)).slice(0, 10),
+                severity: vuln ? severityOf(vuln) : id.startsWith("MAL-") ? "malicious" : "unknown",
+                summary: clean(vuln?.summary ?? vuln?.details ?? "", 200),
+                name: dep.name,
+                version: dep.version,
+                direct: dep.direct,
+                dev: dep.dev,
+                firstSeen: "",
+            };
+            if (ev.fixedIn)
+                f.fixedIn = ev.fixedIn;
+            f.firstSeen = prevSeen.get(findingKey(f)) ?? now;
+            findings.push(f);
+        }
+    }
+    return findings.sort((a, b) => severityRank(a.severity) - severityRank(b.severity) || Number(b.direct) - Number(a.direct) || a.name.localeCompare(b.name));
+}
+const SEEN_TTL_MS = 180 * 24 * 60 * 60 * 1000;
+const SEEN_MAX = 5000;
+/** Remember every finding this checkout has had recently, on any branch. */
+function updateSeen(previous, findings, now) {
+    const seen = Object.create(null);
+    const cutoff = Date.parse(now) - SEEN_TTL_MS;
+    for (const [k, at] of Object.entries(previous?.seen ?? {})) {
+        if (typeof at === "string" && Date.parse(at) >= cutoff)
+            seen[k] = at;
+    }
+    for (const f of previous?.findings ?? [])
+        seen[findingKey(f)] ??= previous?.scannedAt ?? now;
+    for (const f of findings)
+        seen[findingKey(f)] = now;
+    const entries = Object.entries(seen);
+    if (entries.length <= SEEN_MAX)
+        return seen;
+    entries.sort((a, b) => b[1].localeCompare(a[1]));
+    return Object.fromEntries(entries.slice(0, SEEN_MAX));
+}
+/**
+ * Scan one or many projects with a single deduplicated OSV query.
+ * Records are returned, not saved: the caller decides.
+ */
+export async function scanProjects(projects) {
+    const inventories = projects.map(inventory);
+    const unique = new Map();
+    for (const { record } of inventories) {
+        if (record.error)
+            continue;
+        for (const d of record.deps)
+            unique.set(`${d.name}@${d.version}`, { name: d.name, version: d.version });
+    }
+    const queries = [...unique.values()];
+    let refsPerDep = new Map();
+    let vulns = new Map();
+    let networkError;
+    if (queries.length > 0) {
+        try {
+            const refs = await queryBatch(queries);
+            refsPerDep = new Map(queries.map((q, i) => [`${q.name}@${q.version}`, refs[i].map((r) => r.id)]));
+            vulns = await getVulns(refs.flat());
+        }
+        catch (err) {
+            networkError = `could not reach OSV: ${clean(err.message, 200)}`;
+        }
+    }
+    const now = new Date().toISOString();
+    return inventories.map(({ record, previous }) => {
+        if (networkError && !record.error) {
+            // Keep the last known findings rather than pretending everything is fine.
+            record.error = networkError;
+            record.findings = previous?.findings ?? [];
+            record.scannedAt = previous?.scannedAt ?? null;
+            record.seen = previous?.seen ?? {};
+            return { record, newFindings: [], resolvedFindings: [], firstScan: previous === null };
+        }
+        if (!record.error) {
+            record.findings = buildFindings(record.deps, refsPerDep, vulns, previous, now);
+            record.scannedAt = now;
+        }
+        const before = new Set((previous?.findings ?? []).map(findingKey));
+        const history = previous?.seen ?? {};
+        const newFindings = record.findings.filter((f) => !before.has(findingKey(f)) && !Object.hasOwn(history, findingKey(f)));
+        const after = new Set(record.findings.map(findingKey));
+        // Only a successful scan on the same branch can say something was fixed.
+        const sameBranch = previous?.branch === undefined || previous.branch === record.branch;
+        const resolvedFindings = previous && !record.error && sameBranch ? previous.findings.filter((f) => !after.has(findingKey(f))) : [];
+        record.seen = updateSeen(previous, record.findings, now);
+        return { record, newFindings, resolvedFindings, firstScan: previous === null };
+    });
+}

package/dist/schedule.js

@@ -0,0 +1,142 @@
+/**
+ * Background work via per-user launchd agents (macOS):
+ * - dev.selfguard.sync: `selfguard sync` every N hours (discovery, new advisories, reminders);
+ * - dev.selfguard.watch: `selfguard check` as soon as a lockfile of an active checkout changes
+ *   (git pull, installs, merges), so fixes and new risks show up in seconds.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { atomicWrite } from "./fsutil.js";
+import { cliEntry } from "./hook.js";
+import { logFile } from "./paths.js";
+const SYNC_LABEL = "dev.selfguard.sync";
+const WATCH_LABEL = "dev.selfguard.watch";
+/** launchd watches each path with a kqueue descriptor; keep the set bounded. */
+export const MAX_WATCH_PATHS = 200;
+const plistPath = (label) => join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+const domain = () => `gui/${userInfo().uid}`;
+function xml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+export function parseInterval(input) {
+    const m = /^(\d+)\s*(m|h|d)$/.exec(input.trim());
+    if (!m)
+        throw new Error(`invalid interval "${input}" (use e.g. 30m, 6h, 1d)`);
+    const n = Number(m[1]) * { m: 60, h: 3600, d: 86400 }[m[2]];
+    if (n < 15 * 60)
+        throw new Error("minimum interval is 15m");
+    return n;
+}
+function assertMac() {
+    if (process.platform !== "darwin")
+        throw new Error("scheduling is only implemented for macOS (launchd) for now");
+}
+/** Plist for one of our agents. Pure: tested directly. */
+export function agentPlist(label, args, trigger, log) {
+    const triggerXml = "interval" in trigger
+        ? `  <key>StartInterval</key><integer>${trigger.interval}</integer>\n  <key>RunAtLoad</key><true/>`
+        : `  <key>WatchPaths</key>\n  <array>\n${trigger.watch.map((p) => `    <string>${xml(p)}</string>`).join("\n")}\n  </array>\n  <key>ThrottleInterval</key><integer>15</integer>`;
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${xml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args.map((a) => `    <string>${xml(a)}</string>`).join("\n")}
+  </array>
+${triggerXml}
+  <key>ProcessType</key><string>Background</string>
+  <key>LowPriorityIO</key><true/>
+  <key>StandardOutPath</key><string>${xml(log)}</string>
+  <key>StandardErrorPath</key><string>${xml(log)}</string>
+</dict>
+</plist>
+`;
+}
+function unload(label) {
+    try {
+        execFileSync("/bin/launchctl", ["bootout", `${domain()}/${label}`], { stdio: "ignore" });
+    }
+    catch {
+        /* not loaded */
+    }
+}
+function install(label, plist) {
+    unload(label);
+    atomicWrite(plistPath(label), plist);
+    execFileSync("/bin/launchctl", ["bootstrap", domain(), plistPath(label)], { stdio: "ignore" });
+}
+function isLoaded(label) {
+    try {
+        execFileSync("/bin/launchctl", ["print", `${domain()}/${label}`], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function scheduleOn(seconds, watchPaths) {
+    assertMac();
+    install(SYNC_LABEL, agentPlist(SYNC_LABEL, [process.execPath, cliEntry(), "sync", "--background"], { interval: seconds }, logFile()));
+    updateWatcher(watchPaths, { force: true });
+    return plistPath(SYNC_LABEL);
+}
+/**
+ * (Re)install the lockfile watcher with these paths, only when the schedule is on and the
+ * path set changed. Never call it from the watcher's own run: unloading would kill it.
+ */
+export function updateWatcher(paths, opts = {}) {
+    if (process.platform !== "darwin" || process.env.SELFGUARD_NO_LAUNCHD === "1")
+        return { watching: 0, changed: false };
+    if (!opts.force && !existsSync(plistPath(SYNC_LABEL)))
+        return { watching: 0, changed: false };
+    const list = [...new Set(paths)].slice(0, MAX_WATCH_PATHS);
+    if (list.length === 0) {
+        const had = existsSync(plistPath(WATCH_LABEL));
+        unload(WATCH_LABEL);
+        rmSync(plistPath(WATCH_LABEL), { force: true });
+        return { watching: 0, changed: had };
+    }
+    const plist = agentPlist(WATCH_LABEL, [process.execPath, cliEntry(), "check", "--background"], { watch: list }, logFile());
+    let current = "";
+    try {
+        current = readFileSync(plistPath(WATCH_LABEL), "utf8");
+    }
+    catch {
+        /* not installed */
+    }
+    if (current === plist && isLoaded(WATCH_LABEL))
+        return { watching: list.length, changed: false };
+    install(WATCH_LABEL, plist);
+    return { watching: list.length, changed: true };
+}
+export function scheduleOff() {
+    assertMac();
+    let existed = false;
+    for (const label of [SYNC_LABEL, WATCH_LABEL]) {
+        unload(label);
+        existed = existsSync(plistPath(label)) || existed;
+        rmSync(plistPath(label), { force: true });
+    }
+    return existed;
+}
+export function scheduleStatus() {
+    assertMac();
+    let paths = 0;
+    try {
+        const section = /<key>WatchPaths<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(readFileSync(plistPath(WATCH_LABEL), "utf8"));
+        paths = section?.[1]?.match(/<string>/g)?.length ?? 0;
+    }
+    catch {
+        paths = 0;
+    }
+    return {
+        installed: existsSync(plistPath(SYNC_LABEL)),
+        loaded: isLoaded(SYNC_LABEL),
+        plist: plistPath(SYNC_LABEL),
+        watcher: { installed: existsSync(plistPath(WATCH_LABEL)), loaded: isLoaded(WATCH_LABEL), paths },
+    };
+}

package/dist/semver.js

@@ -0,0 +1,65 @@
+/**
+ * Minimal SemVer 2.0.0 parser/comparator (no dependencies on purpose).
+ * Only what we need to evaluate OSV ranges for the npm ecosystem.
+ */
+const SEMVER_RE = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export function parse(input) {
+    if (typeof input !== "string" || input.length > 256)
+        return null;
+    const m = SEMVER_RE.exec(input.trim());
+    if (!m)
+        return null;
+    const major = Number(m[1]);
+    const minor = Number(m[2]);
+    const patch = Number(m[3]);
+    if (![major, minor, patch].every(Number.isSafeInteger))
+        return null;
+    const pre = m[4]
+        ? m[4].split(".").map((id) => (/^\d+$/.test(id) && Number.isSafeInteger(Number(id)) ? Number(id) : id))
+        : [];
+    return { major, minor, patch, pre };
+}
+export function isValid(input) {
+    return parse(input) !== null;
+}
+function cmpNum(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function cmpIdent(a, b) {
+    const an = typeof a === "number";
+    const bn = typeof b === "number";
+    if (an && bn)
+        return cmpNum(a, b);
+    if (an)
+        return -1; // numeric identifiers have lower precedence
+    if (bn)
+        return 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export function compareParsed(a, b) {
+    const core = cmpNum(a.major, b.major) || cmpNum(a.minor, b.minor) || cmpNum(a.patch, b.patch);
+    if (core !== 0)
+        return core;
+    // A version without pre-release has higher precedence than one with.
+    if (a.pre.length === 0 && b.pre.length === 0)
+        return 0;
+    if (a.pre.length === 0)
+        return 1;
+    if (b.pre.length === 0)
+        return -1;
+    const len = Math.min(a.pre.length, b.pre.length);
+    for (let i = 0; i < len; i++) {
+        const c = cmpIdent(a.pre[i], b.pre[i]);
+        if (c !== 0)
+            return c;
+    }
+    return cmpNum(a.pre.length, b.pre.length);
+}
+/** Compare two version strings. Throws if either is not valid SemVer. */
+export function compare(a, b) {
+    const pa = parse(a);
+    const pb = parse(b);
+    if (!pa || !pb)
+        throw new Error(`invalid semver: ${!pa ? a : b}`);
+    return compareParsed(pa, pb);
+}