@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/src/platform/deps.ts

@@ -0,0 +1,374 @@
+/**
+ * THE DEPENDENCY CHECK: DO THE LIBRARIES THIS PROJECT PINS HAVE KNOWN ADVISORIES?
+ * ==============================================================================
+ *
+ * Every other check reads the code a project wrote. Most of what a project
+ * runs, it did not write: it is in the lockfile. This reads the versions a
+ * lockfile pins and asks OSV (osv.dev, the open advisory database behind
+ * OSV-Scanner) which of them have published advisories.
+ *
+ * WHY IT IS A SEPARATE COMMAND. It is the one check that talks to the network.
+ * `defuse scan` promises nothing leaves the machine, and keeps that promise;
+ * `defuse deps` sends package names and versions - never code - to api.osv.dev,
+ * and says so before it does.
+ *
+ * WHAT IT CAN AND CANNOT CLAIM. A pinned version that matches an advisory says
+ * the vulnerable code is installed. It says nothing about whether this project
+ * ever calls it. Signature-grade by nature, and every result says so.
+ *
+ * Lockfiles it recognises but cannot read yet are listed by name, and lines it
+ * could not read are counted with the reason - never silently skipped.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { signatureFinding, type Severity, type SignatureFinding } from '../core/finding.js';
+import { DEPENDENCY_RULE, type DependencyReport } from './dependency-rule.js';
+import { globToRegExp } from '../engine/walk.js';
+
+export { DEPENDENCY_RULE, type DependencyReport };
+
+
+
+export type Ecosystem = 'npm' | 'PyPI' | 'Packagist' | 'Go';
+
+export interface Pinned {
+  readonly name: string;
+  readonly version: string;
+  readonly ecosystem: Ecosystem;
+  /** The lockfile it was read from, as found. */
+  readonly file: string;
+}
+
+export interface LockfileRead {
+  readonly file: string;
+  readonly packages: readonly Pinned[];
+  /** What was in the file but not checked, each with the reason. */
+  readonly skipped: readonly string[];
+}
+
+export interface Advisory {
+  readonly id: string;
+  readonly summary: string;
+  readonly aliases: readonly string[];
+  /** OSV's own rating where the source gives one (critical/high/medium/low), else "unrated". */
+  readonly severity: string;
+  /** Versions the advisory says fix it, for this package. Empty when none is published. */
+  readonly fixed: readonly string[];
+}
+
+export interface DependencyHit {
+  readonly pkg: Pinned;
+  readonly advisories: readonly Advisory[];
+}
+
+type Reader = (text: string, file: string) => { packages: Pinned[]; skipped: string[] };
+
+/** A version that is a release, not a path, URL or branch. */
+const RELEASE = /^v?\d/;
+
+const READERS: Record<string, Reader> = {
+  'package-lock.json': (text, file) => {
+    const lock = JSON.parse(text) as {
+      packages?: Record<string, { name?: string; version?: string; link?: boolean }>;
+      dependencies?: Record<string, NpmV1Dep>;
+    };
+    const found: Array<[string, string]> = [];
+    if (lock.packages) {
+      for (const [key, p] of Object.entries(lock.packages)) {
+        if (key === '' || p.link || !p.version) continue; // the project itself, or a workspace link
+        found.push([p.name ?? key.slice(key.lastIndexOf('node_modules/') + 'node_modules/'.length), p.version]);
+      }
+    } else {
+      const walk = (deps: Record<string, NpmV1Dep> | undefined): void => {
+        for (const [name, d] of Object.entries(deps ?? {})) {
+          if (d.version) found.push([name, d.version]);
+          walk(d.dependencies);
+        }
+      };
+      walk(lock.dependencies);
+    }
+    return split(found, 'npm', file);
+  },
+
+  'composer.lock': (text, file) => {
+    const lock = JSON.parse(text) as Record<string, Array<{ name: string; version: string }> | undefined>;
+    const all = [...(lock['packages'] ?? []), ...(lock['packages-dev'] ?? [])];
+    return split(all.map((p) => [p.name, p.version]), 'Packagist', file);
+  },
+
+  'requirements.txt': (text, file) => {
+    const packages: Pinned[] = [];
+    const skipped: string[] = [];
+    for (const raw of text.split(/\r?\n/)) {
+      const line = raw.replace(/\s+#.*$/, '').trim();
+      if (!line || line.startsWith('#')) continue;
+      if (line.startsWith('-')) {
+        skipped.push(`${line} - an option line (-r, -e, --index-url...), not followed`);
+        continue;
+      }
+      const m = /^([A-Za-z0-9._-]+)(?:\[[^\]]*\])?\s*==\s*([^\s;,]+)$/.exec(line.split(';')[0]!.trim());
+      if (m) packages.push({ name: m[1]!, version: m[2]!, ecosystem: 'PyPI', file });
+      else skipped.push(`${line} - not pinned with ==, so the installed version is unknown`);
+    }
+    return { packages, skipped };
+  },
+
+  'go.mod': (text, file) => {
+    const found: Array<[string, string]> = [];
+    let inRequire = false;
+    for (const raw of text.split(/\r?\n/)) {
+      const line = raw.replace(/\/\/.*$/, '').trim();
+      if (/^require\s*\($/.test(line)) inRequire = true;
+      else if (inRequire && line === ')') inRequire = false;
+      else {
+        const m = (inRequire ? /^(\S+)\s+(\S+)$/ : /^require\s+(\S+)\s+(\S+)$/).exec(line);
+        if (m) found.push([m[1]!, m[2]!]);
+      }
+    }
+    const result = split(found, 'Go', file);
+    if (/^replace\b/m.test(text)) {
+      result.skipped.push('replace directives - not applied, so a replaced module is checked at its required version');
+    }
+    return result;
+  },
+};
+
+interface NpmV1Dep {
+  version?: string;
+  dependencies?: Record<string, NpmV1Dep>;
+}
+
+function split(found: ReadonlyArray<readonly [string, string]>, ecosystem: Ecosystem, file: string) {
+  const packages: Pinned[] = [];
+  const skipped: string[] = [];
+  for (const [name, version] of found) {
+    if (RELEASE.test(version)) packages.push({ name, version, ecosystem, file });
+    else skipped.push(`${name} ${version} - not a release version (a path, URL or branch)`);
+  }
+  return { packages, skipped };
+}
+
+/** Recognised by name, not read yet. Listed in the output, never ignored in silence. */
+export const UNREAD_LOCKFILES: ReadonlySet<string> = new Set([
+  'yarn.lock', 'pnpm-lock.yaml', 'npm-shrinkwrap.json', 'Pipfile.lock', 'poetry.lock', 'uv.lock',
+  'Cargo.lock', 'Gemfile.lock', 'pom.xml', 'build.gradle', 'build.gradle.kts', 'gradle.lockfile',
+  'packages.lock.json',
+]);
+
+const SKIP_DIRS = new Set(['node_modules', 'vendor', '.git', '.venv', 'venv', '__pycache__']);
+
+/** Parse one lockfile by its file name. Null when the name is not one this reads. */
+export function readLockfile(file: string, text: string): LockfileRead | null {
+  const reader = READERS[path.basename(file)];
+  if (!reader) return null;
+  try {
+    return { file, ...reader(text, file) };
+  } catch (error) {
+    return { file, packages: [], skipped: [`the whole file - it did not parse: ${(error as Error).message}`] };
+  }
+}
+
+/** Every lockfile under `target`, read; plus the recognised ones that are not. `exclude` means what scan --exclude means. */
+export function findLockfiles(target: string, exclude: readonly string[] = []): { read: LockfileRead[]; unread: string[] } {
+  const read: LockfileRead[] = [];
+  const unread: string[] = [];
+  const patterns = exclude.map(globToRegExp);
+  const visit = (p: string): void => {
+    const relative = path.relative(target, p).split(path.sep).join('/');
+    if (relative && patterns.some((re) => re.test(relative))) return;
+    if (statSync(p).isDirectory()) {
+      for (const entry of readdirSync(p)) if (!SKIP_DIRS.has(entry)) visit(path.join(p, entry));
+      return;
+    }
+    const name = path.basename(p);
+    if (UNREAD_LOCKFILES.has(name)) unread.push(p);
+    else if (READERS[name]) read.push(readLockfile(p, readFileSync(p, 'utf8'))!);
+  };
+  visit(target);
+  return { read, unread };
+}
+
+const OSV = 'https://api.osv.dev/v1';
+const BATCH = 1000; // OSV's own limit per querybatch call
+
+/**
+ * Ask OSV about every pinned package. Sends name, ecosystem and version only.
+ * `fetchImpl` is injectable so the tests can run without a network.
+ */
+export async function queryOsv(
+  pinned: readonly Pinned[],
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ hits: DependencyHit[]; checked: number; incomplete: string[] }> {
+  const unique = [...new Map(pinned.map((p) => [`${p.ecosystem}|${p.name}|${p.version}`, p])).values()];
+  const call = async (url: string, body?: unknown): Promise<unknown> => {
+    const signal = AbortSignal.timeout(30_000);
+    const response = await fetchImpl(
+      url,
+      body
+        ? { method: 'POST', body: JSON.stringify(body), headers: { 'content-type': 'application/json' }, signal }
+        : { signal },
+    );
+    if (!response.ok) throw new Error(`OSV answered ${response.status} for ${url}`);
+    return response.json();
+  };
+
+  const idsPer: string[][] = [];
+  const incomplete: string[] = [];
+  for (let i = 0; i < unique.length; i += BATCH) {
+    const chunk = unique.slice(i, i + BATCH);
+    const answer = (await call(`${OSV}/querybatch`, {
+      queries: chunk.map((p) => ({ package: { name: p.name, ecosystem: p.ecosystem }, version: p.version })),
+    })) as { results?: Array<{ vulns?: Array<{ id: string }>; next_page_token?: string }> };
+    if (!Array.isArray(answer.results) || answer.results.length !== chunk.length) {
+      throw new Error('OSV returned a batch answer of the wrong shape - nothing was checked');
+    }
+    answer.results.forEach((r, j) => {
+      idsPer.push((r.vulns ?? []).map((v) => v.id));
+      if (r.next_page_token) incomplete.push(`${chunk[j]!.name} ${chunk[j]!.version} - more advisories exist than one page`);
+    });
+  }
+
+  // ponytail: one GET per distinct advisory, all at once; add a concurrency cap if OSV starts refusing.
+  const details = new Map<string, OsvVuln>();
+  await Promise.all(
+    [...new Set(idsPer.flat())].map(async (id) => details.set(id, (await call(`${OSV}/vulns/${encodeURIComponent(id)}`)) as OsvVuln)),
+  );
+
+  const hits = unique.flatMap((pkg, i): DependencyHit[] => {
+    const ids = idsPer[i]!;
+    return ids.length ? [{ pkg, advisories: mergeSame(ids.map((id) => toAdvisory(details.get(id)!, pkg))) }] : [];
+  });
+  return { hits, checked: unique.length, incomplete };
+}
+
+
+const RANK: Record<string, number> = { critical: 4, high: 3, medium: 2, low: 1 };
+
+/**
+ * The whole check for `scan --deps`: find lockfiles, ask OSV, and return one
+ * signature-based finding per affected package, located on its lockfile line.
+ * `display` turns an absolute path into the one the report shows.
+ */
+export async function checkDependencies(
+  target: string,
+  display: (file: string) => string,
+  exclude: readonly string[] = [],
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ findings: SignatureFinding[]; report: DependencyReport }> {
+  const { read, unread } = findLockfiles(target, exclude);
+  const pinned = read.flatMap((r) => r.packages);
+  const answer = pinned.length ? await queryOsv(pinned, fetchImpl) : { hits: [], checked: 0, incomplete: [] };
+  const texts = new Map<string, string[]>();
+  const linesOf = (file: string): string[] => {
+    if (!texts.has(file)) texts.set(file, readFileSync(file, 'utf8').split(/\r?\n/));
+    return texts.get(file)!;
+  };
+  return {
+    findings: answer.hits.map((h) => dependencyFinding(h, linesOf(h.pkg.file), display(h.pkg.file))),
+    report: {
+      source: 'api.osv.dev',
+      checkedAt: new Date().toISOString(),
+      read: read.map((r) => ({ file: display(r.file), packages: r.packages.length, skipped: r.skipped })),
+      notRead: unread.map(display),
+      checked: answer.checked,
+      incomplete: answer.incomplete,
+    },
+  };
+}
+
+export function dependencyFinding(hit: DependencyHit, lines: readonly string[], file: string): SignatureFinding {
+  const { pkg, advisories } = hit;
+  // ponytail: first line naming the package (with its version, if one does); a lockfile has no AST to point at.
+  const named = (needle: string) => lines.findIndex((l) => l.includes(needle));
+  const at = [`node_modules/${pkg.name}"`, `"${pkg.name}"`, pkg.name]
+    .map((n) => {
+      const withVersion = lines.findIndex((l) => l.includes(n) && l.includes(pkg.version));
+      return withVersion >= 0 ? withVersion : named(n);
+    })
+    .find((i) => i >= 0) ?? 0;
+  const text = (lines[at] ?? '').trim();
+  const rated = advisories.filter((a) => a.severity !== 'unrated');
+  const top = rated.reduce((best, a) => (RANK[a.severity]! > RANK[best]! ? a.severity : best), 'low');
+  const severity = (rated.length ? top : 'medium') as Severity;
+  const ids = advisories.map((a) => [a.id, ...a.aliases.filter((x) => x.startsWith('CVE-'))].join('/'));
+  const fixed = [...new Set(advisories.flatMap((a) => a.fixed))];
+  return signatureFinding({
+    ruleId: DEPENDENCY_RULE.id,
+    ruleName: DEPENDENCY_RULE.name,
+    cwe: 'CWE-1395',
+    owasp: DEPENDENCY_RULE.owasp,
+    severity,
+    message:
+      `${pkg.name} ${pkg.version} has ${advisories.length} published advisor${advisories.length === 1 ? 'y' : 'ies'}` +
+      (fixed.length ? ` - fixed versions: ${fixed.join(', ')}` : ' - no fixed version published'),
+    location: {
+      file,
+      startLine: at + 1,
+      startColumn: 1,
+      endLine: at + 1,
+      endColumn: (lines[at]?.length ?? 0) + 1,
+      astNodeType: 'lockfile-entry',
+      astNodePath: `${pkg.ecosystem} lockfile`,
+      snippet: text.length > 160 ? `${text.slice(0, 159)}…` : text,
+    },
+    reasoning:
+      `osv.dev lists ${ids.join(', ')} for ${pkg.ecosystem} ${pkg.name} ${pkg.version}: ` +
+      advisories.map((a) => `${a.summary} (${a.severity})`).join('; ') +
+      '.' +
+      (rated.length
+        ? ''
+        : ' None of these advisories carries a severity rating, so medium is a placeholder, not an assessment.'),
+    limitations: DEPENDENCY_RULE.limitations,
+  });
+}
+
+interface OsvVuln {
+  id: string;
+  summary?: string;
+  details?: string;
+  aliases?: string[];
+  database_specific?: { severity?: string };
+  affected?: Array<{
+    package?: { name?: string; ecosystem?: string };
+    ranges?: Array<{ type?: string; events?: Array<{ fixed?: string }> }>;
+  }>;
+}
+
+/**
+ * One flaw, one entry. OSV holds the same CVE once per database (GHSA-, GO-,
+ * PYSEC-...), so a project would otherwise see one bug listed two or three
+ * times. Entries naming each other, or sharing an alias, are folded into one;
+ * a rated entry wins over an unrated one, and every id is kept in `aliases`.
+ */
+export function mergeSame(advisories: readonly Advisory[]): Advisory[] {
+  const groups: Advisory[][] = [];
+  for (const a of advisories) {
+    const names = new Set([a.id, ...a.aliases]);
+    const group = groups.find((g) => g.some((b) => b.id === a.id || names.has(b.id) || b.aliases.some((x) => names.has(x))));
+    if (group) group.push(a);
+    else groups.push([a]);
+  }
+  return groups.map((g) => {
+    const lead = g.find((a) => a.severity !== 'unrated') ?? g[0]!;
+    const ids = new Set(g.flatMap((a) => [a.id, ...a.aliases]));
+    ids.delete(lead.id);
+    return { ...lead, aliases: [...ids], fixed: [...new Set(g.flatMap((a) => a.fixed))] };
+  });
+}
+
+function toAdvisory(v: OsvVuln, pkg: Pinned): Advisory {
+  const fixed = (v.affected ?? [])
+    .filter((a) => a.package?.name === pkg.name && a.package?.ecosystem === pkg.ecosystem)
+    // GIT ranges name commits, not versions anyone can install.
+    .flatMap((a) => (a.ranges ?? []).filter((r) => r.type !== 'GIT'))
+    .flatMap((r) => (r.events ?? []).flatMap((e) => (e.fixed ? [e.fixed] : [])));
+  const rated = v.database_specific?.severity?.toLowerCase().replace('moderate', 'medium');
+  return {
+    id: v.id,
+    summary: v.summary ?? v.details?.split('\n')[0]?.slice(0, 160) ?? '(no summary published)',
+    aliases: v.aliases ?? [],
+    severity: rated && ['critical', 'high', 'medium', 'low'].includes(rated) ? rated : 'unrated',
+    fixed: [...new Set(fixed)],
+  };
+}

package/src/platform/php-facts.ts

@@ -0,0 +1,85 @@
+/**
+ * WHAT DEFUSE KNOWS ABOUT PHP RELEASES - AND WHEN IT LAST CHECKED.
+ * ================================================================
+ *
+ * Every other check in Defuse reads the code it is given and needs nothing
+ * else. This one compares a version number with facts about the world, and
+ * facts about the world go stale: a release that is current today is missing a
+ * fix next month. So the table carries the date it was checked, and every
+ * finding and report built on it prints that date. A stale table is then a
+ * visible fact rather than a quiet wrong answer.
+ *
+ * Every entry was read from php.net on the date below, not from news reports:
+ *   https://www.php.net/supported-versions.php   support dates, 8.2 - 8.5
+ *   https://www.php.net/eol.php                  end-of-life dates
+ *   https://www.php.net/archive/2026             the 21 Oct 2026 security releases
+ *
+ * TO UPDATE: change the facts, change CHECKED, run `npm test`. The tests pin
+ * the table's shape, not today's numbers, so an update is a data change only.
+ */
+
+/** The day these facts were read from php.net. ISO date. */
+export const PHP_FACTS_CHECKED = '2026-10-28';
+
+/**
+ * Branches still receiving security fixes, and until when. A branch past its
+ * date on the day of the scan is treated as end of life - the scan date
+ * decides that, not the table date, so 8.2 turns out of support on 1 Jan 2027
+ * without anyone editing this file.
+ */
+export const PHP_SECURITY_UNTIL: Readonly<Record<string, string>> = {
+  '8.2': '2026-12-31',
+  '8.3': '2027-12-31',
+  '8.4': '2028-12-31',
+  '8.5': '2029-12-31',
+};
+
+/** Branches php.net lists as end of life, with the date support ended. */
+export const PHP_END_OF_LIFE: Readonly<Record<string, string>> = {
+  '8.1': '2025-12-31',
+  '8.0': '2023-11-26',
+  '7.4': '2022-11-28',
+  '7.3': '2021-12-06',
+  '7.2': '2020-11-30',
+  '7.1': '2019-12-01',
+  '7.0': '2019-01-10',
+  '5.6': '2018-12-31',
+  '5.5': '2016-07-21',
+  '5.4': '2015-09-03',
+  '5.3': '2014-08-14',
+  '5.2': '2011-01-06',
+  '5.1': '2006-08-24',
+  '5.0': '2005-09-05',
+};
+
+export interface PhpAdvisory {
+  /** The name it is known by, for a reader who has seen the news. */
+  readonly name: string;
+  readonly cves: readonly string[];
+  /** ISO date of the fixing releases. */
+  readonly published: string;
+  /** One plain sentence: what an attacker gets. */
+  readonly impact: string;
+  /** Per supported branch, the first release with the fix. */
+  readonly fixedIn: Readonly<Record<string, string>>;
+  /** The oldest branch reported affected. Older branches are end of life anyway. */
+  readonly oldestAffected: string;
+}
+
+/**
+ * Only advisories severe enough to change what a reader should do today. This
+ * is not a vulnerability database and does not pretend to be one - see the
+ * limitations text in runtime-version.ts. One entry is a deliberate start.
+ */
+export const PHP_ADVISORIES: readonly PhpAdvisory[] = [
+  {
+    name: 'PHP2Shell',
+    cves: ['CVE-2026-109618', 'CVE-2026-109619'],
+    published: '2026-10-21',
+    impact:
+      'two critical flaws in PHP itself that can let an attacker run code on the server ' +
+      'without logging in, reported exploited in the wild',
+    fixedIn: { '8.2': '8.2.35', '8.3': '8.3.36', '8.4': '8.4.27', '8.5': '8.5.12' },
+    oldestAffected: '5.4',
+  },
+];