@xagents_in/unmask 0.1.3 → 0.1.4

package/README.md

@@ -49,12 +49,61 @@ type an exact release such as `chalk@6.0.1`, and press **check it**.
 **From a terminal:**
 
 ```bash
-npx @xagents_in/unmask check chalk@6.0.1 --out ./unmask-report
+npx @xagents_in/unmask check chalk@6.0.1
 ```
 
-You get `report.json` and an escaped `report.html` in `./unmask-report`. Only the
+The terminal shows the result, coverage, findings, known advisories, the AI
+explanation status and next steps. Add `--out ./unmask-report` to also save
+`report.json` and an escaped `report.html`; nothing is written without it. Only the
 package name and version leave your machine; the hosted service does the rest.
 
+### What the terminal shows
+
+The examples below are real CLI output from a local test server with synthetic
+fixtures and recorded OSV advisory data. They are not live-service results.
+
+A completed check prints the result and exit code, coverage, findings, the OSV
+advisories for that exact version, the AI status and next steps. The AI summary
+appears only when the model actually returned one; otherwise the line names the
+status, such as `unavailable (quota)`, and nothing stands in for it.
+
+```text
+UNMASK fixture@1.0.0
+Result    Deterministic findings need review (exit 3)
+Coverage  complete: 1 file, 81 B
+          0 byte-identical, 1 changed, 0 artifact-only, 0 not-compared
+Source    selected via user-full-SHA at dddddddddddd
+Findings  1
+  - lifecycle-source-absent (script install)
+Advisory  none reported by OSV for this exact version
+AI        complete, 0 hypotheses (separate from deterministic evidence)
+  Summary: The artifact declares an install script that the selected source does not.
+  Scope: 1 evidence items supplied, 0 omitted; not checked: runtime-behavior
+  Uncertainty: The script was not executed, so its runtime effect is unknown.
+Next
+  - Review each finding and its cited evidence before installing.
+  - AI suggests: Compare the install script with the upstream repository before installing.
+  - Add --out DIR to save the full JSON and HTML evidence.
+```
+
+When the registry artifact cannot be analyzed, for example a removed release or
+a timed-out run, the check still shows the advisories for that exact version. It
+says that nothing was inspected and exits `2`:
+
+```text
+UNMASK ua-parser-js@0.7.29
+Result    Advisory-only: artifact not inspected; no verdict is claimed (exit 2)
+Artifact  not inspected (execution-timeout); source comparison not performed
+Advisory  1 known for this exact version (OSV)
+  - GHSA-pjwm-rvh2-c87w Embedded malware in ua-parser-js
+AI        not run; no artifact evidence to explain
+```
+
+Progress and errors go to stderr, so stdout stays clean for pipes. Color appears
+only on an interactive terminal; set `NO_COLOR=1` to turn it off. Exit `0` means
+no review rule fired in the inspected scope. It does not mean safe, and a
+missing advisory is not evidence of safety.
+
 ## What a check returns
 
 A real report for **`zod@4.6.7`**, from the live service:
@@ -183,8 +232,8 @@ npm run check:package
 node dist/cli/main.mjs check chalk@6.0.1 --out /tmp/unmask-chalk-report
 ```
 
-Choose a fresh output folder for each check; existing report files are never
-replaced. `UNMASK_SERVER_URL` selects another service: an HTTPS origin, or a
+`--out` is optional. When given, choose a fresh output folder for each check;
+existing report files are never replaced. `UNMASK_SERVER_URL` selects another service: an HTTPS origin, or a
 loopback HTTP origin for local testing. A hosted failure never falls back to local
 acquisition. See [CLI configuration and data flow](docs/cli.md).
 
@@ -199,6 +248,39 @@ folder instead. Leave out all source options for an artifact-only report.
 `--claim name@version` checks an identity claim against the package manifest.
 Excerpts leave the machine only if you add `--allow-model` and configure a provider.
 
+**Commands in this build.** `node dist/cli/main.mjs --help` (or `unmask --help`
+once installed) prints the same list, and `unmask help COMMAND` shows its usage.
+
+| Command       | What it does                                                                   |
+| ------------- | ------------------------------------------------------------------------------ |
+| `check`       | Check one exact version through the hosted service, or a local tarball offline |
+| `install`     | Refuse mutable npm install and explain the lockfile-first ci path              |
+| `ci`          | Screen the exact lockfile plan before invoking npm ci                          |
+| `enable`      | Print explicit reversible shell integration                                    |
+| `disable`     | Print how to remove the shell integration                                      |
+| `audit`       | Check exact versions locked in a package-lock.json, with bounded coverage      |
+| `why`         | Explain dependency paths recorded in the lockfile                              |
+| `info`        | Show hosted package metadata, scripts, dependencies and recorded assessment    |
+| `files`       | List a bounded hosted package file inventory                                   |
+| `file`        | Inspect recorded file evidence using a report-bound file selector              |
+| `compare`     | Compare scripts, dependencies and files between two exact versions             |
+| `history`     | Show a bounded registry release timeline with exact-version guidance           |
+| `config`      | Manage project-local guard policy settings                                     |
+| `exceptions`  | Manage explicit expiring exact-version guard exceptions                        |
+| `init`        | Create project guard configuration explicitly                                  |
+| `doctor`      | Diagnose Node, service reachability and project guard configuration            |
+| `cache`       | Import, inspect and explicitly prune local report snapshots                    |
+| `sarif`       | Export recorded findings as SARIF from an existing report                      |
+| `annotations` | Produce escaped CI annotations and a summary from an existing report           |
+| `watch`       | Opt in to watch a lockfile and check changes                                   |
+| `preflight`   | Check changed lockfile entries against a baseline for CI                       |
+| `scan`        | Resolve a dist-tag to an exact version, then check it                          |
+| `batch`       | Check several explicit exact versions serially with duplicate coalescing       |
+
+The explicit install guard can block before npm when policy or incomplete evidence
+requires it. Inspection commands report recorded evidence and coverage; exit `0`
+never means a package is safe.
+
 **Run the website locally:**
 
 ```bash

package/dist/cli/annotations.mjs

@@ -0,0 +1,145 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { LocalInputError } from "../core/pipeline.mjs";
+import { collectFindings } from "../core/sarif.mjs";
+import { parseExportOptions, readExportInputs } from "./sarif.mjs";
+
+const MAX_SUMMARY_ITEMS = 50;
+const commands = { error: "error", warning: "warning", note: "notice" };
+const visible = (value) =>
+  String(value).replace(
+    /[\u0000-\u0009\u000b\u000c\u000e-\u001f\u007f-\u009f\u2028\u2029]/g,
+    (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+
+export function escapeData(value) {
+  return visible(value)
+    .replace(/%/g, "%25")
+    .replace(/\r/g, "%0D")
+    .replace(/\n/g, "%0A");
+}
+
+export function escapeProperty(value) {
+  return escapeData(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+
+export function escapeMarkdown(value) {
+  return visible(value)
+    .replace(/[\r\n]+/g, " ")
+    .replace(/[\\`*_{}[\]()<>#+!|~&"'=-]/g, (char) => `\\${char}`);
+}
+
+function where(result) {
+  const spans = result.locations.map(
+    (item) =>
+      `${item.side} ${item.path} bytes ${item.byteOffset}-${item.byteOffset + item.byteLength}`,
+  );
+  return spans.length ? ` [${spans.join("; ")}]` : "";
+}
+
+export function annotationOutcome(collected) {
+  const { report, advisories, results } = collected;
+  let exitCode = report.policy.exitCode;
+  const knownAdvisory = results.some((item) =>
+    ["advisory/known-malware", "advisory/known-vulnerability"].includes(
+      item.ruleId,
+    ),
+  );
+  if (exitCode === 0 && knownAdvisory) exitCode = 3;
+  if (exitCode === 0 && advisories && !advisories.complete) exitCode = 2;
+  return exitCode;
+}
+
+export function renderAnnotations(collected) {
+  const lines = [];
+  for (const result of collected.results)
+    lines.push(
+      `::${commands[result.level]} title=${escapeProperty(`unmask ${result.ruleId}`)}::${escapeData(result.message + where(result))}`,
+    );
+  for (const item of collected.limitations)
+    lines.push(
+      `::${commands[item.level]} title=${escapeProperty(`unmask ${item.id}`)}::${escapeData(item.message)}`,
+    );
+  return lines.join("\n") + "\n";
+}
+
+export function renderSummary(collected, exitCode) {
+  const { report, identity, advisories, results, limitations } = collected;
+  const conflict = identity?.identityStatus === "claim-conflicts-with-manifest";
+  const name = identity
+    ? conflict
+      ? `${identity.name}@${identity.version} (claimed; artifact declares ${identity.declared.name}@${identity.declared.version})`
+      : `${identity.name}@${identity.version}`
+    : "unidentified artifact";
+  const count = (level) =>
+    results.filter((item) => item.level === level).length;
+  const lines = [
+    `## UNMASK check: ${escapeMarkdown(name)}`,
+    "",
+    "| Item | Value |",
+    "| --- | --- |",
+    `| Exit code | ${exitCode} |`,
+    `| Policy findings | ${report.policy.findings.length} |`,
+    `| Coverage complete | ${report.coverage.complete ? "yes" : "no"} |`,
+    `| Identity | ${escapeMarkdown(identity?.identityStatus ?? "unknown")} |`,
+    `| Advisory check | ${escapeMarkdown(advisories ? `${advisories.status}${advisories.boundTo === "claim" && identity.identityStatus !== "claim-matches-manifest" ? " (for requested identity)" : ""}` : "not supplied")} |`,
+    `| Results | ${count("error")} error, ${count("warning")} warning, ${count("note")} note |`,
+    `| Artifact sha256 | \`${report.inputs.artifact.sha256}\` |`,
+    "",
+  ];
+  if (results.length) {
+    lines.push("### Results", "");
+    for (const item of results.slice(0, MAX_SUMMARY_ITEMS))
+      lines.push(
+        `- **${item.level}** \`${item.ruleId}\`: ${escapeMarkdown(item.message + where(item))}`,
+      );
+    if (results.length > MAX_SUMMARY_ITEMS)
+      lines.push(
+        `- ${results.length - MAX_SUMMARY_ITEMS} more results omitted`,
+      );
+    lines.push("");
+  }
+  lines.push("### Limitations", "");
+  for (const item of limitations)
+    lines.push(`- ${item.level}: ${escapeMarkdown(item.message)}`);
+  return lines.join("\n") + "\n\n";
+}
+
+async function appendSummary(filename, markdown) {
+  let handle;
+  try {
+    handle = await open(
+      filename,
+      constants.O_WRONLY |
+        constants.O_APPEND |
+        constants.O_CREAT |
+        constants.O_NONBLOCK |
+        (constants.O_NOFOLLOW ?? 0),
+      0o600,
+    );
+    if (!(await handle.stat()).isFile()) throw new Error("not regular");
+    await handle.writeFile(markdown);
+  } catch {
+    throw new LocalInputError(
+      "output-write-failed",
+      "Summary requires a regular, writable file path",
+    );
+  } finally {
+    await handle?.close();
+  }
+}
+
+export async function annotationsCommand(argv, stdout = process.stdout) {
+  const options = parseExportOptions(argv, {
+    "--report": "report",
+    "--details": "details",
+    "--summary": "summary",
+  });
+  const { report, details } = await readExportInputs(options);
+  const collected = collectFindings(report, details);
+  const exitCode = annotationOutcome(collected);
+  if (options.summary !== undefined)
+    await appendSummary(options.summary, renderSummary(collected, exitCode));
+  stdout.write(renderAnnotations(collected));
+  return exitCode;
+}

package/dist/cli/audit.mjs

@@ -0,0 +1,223 @@
+import { LocalInputError } from "../core/pipeline.mjs";
+import { AcquisitionError } from "../core/acquire.mjs";
+import { checkHosted } from "./hosted.mjs";
+import { exactTargets, readLockfile } from "./lockfile.mjs";
+
+export const AUDIT_LIMITS = Object.freeze({
+  defaultMax: 6,
+  maxPackages: 50,
+  maxConcurrency: 2,
+});
+const STATUS_BY_EXIT = { 0: "no-findings", 2: "incomplete", 3: "findings" };
+
+export function bindingStatus(target, report) {
+  if (!target.bound) return "unbound";
+  const actual = report?.inputs?.artifact?.sha512;
+  if (typeof actual !== "string" || !/^[a-f0-9]{128}$/.test(actual))
+    return "unavailable";
+  const locked = target.integrity
+    .flatMap((value) => value.split(/\s+/))
+    .filter((value) => value.startsWith("sha512-"))
+    .map((value) => Buffer.from(value.slice(7), "base64").toString("hex"));
+  return locked.length > 0 && locked.every((value) => value === actual)
+    ? "verified"
+    : "mismatch";
+}
+
+function positive(value, max, label) {
+  if (!/^[1-9]\d*$/.test(value ?? "") || Number(value) > max)
+    throw new LocalInputError(
+      "invalid-option",
+      `${label} must be an integer from 1 to ${max}.`,
+    );
+  return Number(value);
+}
+
+export function parseAuditArgs(argv) {
+  const options = {
+    lockfile: "package-lock.json",
+    max: AUDIT_LIMITS.defaultMax,
+    concurrency: 1,
+    omitDev: false,
+    json: false,
+  };
+  const seen = new Set();
+  for (let index = 0; index < argv.length; index++) {
+    const key = argv[index];
+    if (seen.has(key))
+      throw new LocalInputError(
+        "duplicate-option",
+        "Each option may be supplied only once",
+      );
+    seen.add(key);
+    if (key === "--json") options.json = true;
+    else if (key === "--omit-dev") options.omitDev = true;
+    else if (key === "--lockfile") {
+      const value = argv[++index];
+      if (!value || value.startsWith("--"))
+        throw new LocalInputError(
+          "missing-value",
+          "An option is missing its value",
+        );
+      options.lockfile = value;
+    } else if (key === "--max")
+      options.max = positive(argv[++index], AUDIT_LIMITS.maxPackages, "--max");
+    else if (key === "--concurrency")
+      options.concurrency = positive(
+        argv[++index],
+        AUDIT_LIMITS.maxConcurrency,
+        "--concurrency",
+      );
+    else
+      throw new LocalInputError(
+        "unknown-option",
+        "Use audit [--lockfile PATH] [--max N] [--concurrency N] [--omit-dev] [--json]",
+      );
+  }
+  return options;
+}
+
+async function checkOne(target, check) {
+  try {
+    const report = await check(target.spec);
+    const exitCode = report?.policy?.exitCode;
+    return {
+      ...target,
+      status: STATUS_BY_EXIT[exitCode] ?? "incomplete",
+      binding: bindingStatus(target, report),
+      exitCode,
+      findings: (report.policy.findings ?? []).map((item) => item.ruleId),
+      model: report.model?.status ?? "not-reported",
+    };
+  } catch (error) {
+    return {
+      ...target,
+      status: "failed",
+      error:
+        error instanceof LocalInputError
+          ? { code: error.code, message: error.message }
+          : error instanceof AcquisitionError
+            ? { code: error.code, message: "Invalid exact package identity." }
+            : { code: "internal", message: "Check failed unexpectedly." },
+    };
+  }
+}
+
+export async function auditLock(
+  lock,
+  { check, max = AUDIT_LIMITS.defaultMax, concurrency = 1, omitDev = false },
+) {
+  const { considered, targets, skipped, omitted } = exactTargets(lock, {
+    omitDev,
+  });
+  const selected = targets.slice(0, max);
+  const results = new Array(selected.length);
+  let next = 0;
+  // Bounded worker pool keeps hosted load within the shared rate limit.
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, selected.length) }, async () => {
+      while (next < selected.length) {
+        const index = next++;
+        results[index] = await checkOne(selected[index], check);
+      }
+    }),
+  );
+  const notChecked = targets
+    .slice(max)
+    .map((target) => ({ ...target, status: "not-checked" }));
+  const counts = {};
+  for (const item of [...results, ...notChecked])
+    counts[item.status] = (counts[item.status] ?? 0) + 1;
+  const skippedTotal = Object.values(skipped).reduce((a, b) => a + b, 0);
+  const binding = {};
+  for (const item of results)
+    if (item.binding) binding[item.binding] = (binding[item.binding] ?? 0) + 1;
+  const complete =
+    skippedTotal === 0 &&
+    notChecked.length === 0 &&
+    results.every(
+      (item) =>
+        ["no-findings", "findings"].includes(item.status) &&
+        item.binding === "verified",
+    );
+  return {
+    schemaVersion: "1",
+    lockfileVersion: lock.lockfileVersion,
+    scope: omitDev ? "production-and-optional" : "all-locked",
+    coverage: {
+      complete,
+      lockedEntries: considered,
+      uniqueExact: targets.length,
+      checked: results.length,
+      counts,
+      binding,
+      skipped,
+      omitted,
+    },
+    exitCode: counts.findings ? 3 : complete ? 0 : 2,
+    results: [...results, ...notChecked],
+    limitations: [
+      "No findings means no deterministic policy finding in the checked scope, not that a package is safe.",
+      "Removed or unpublished registry versions fail acquisition and are reported as failed, not clean.",
+      "Git, URL, file, workspace and invalid entries are not audited by exact registry identity.",
+      "Coverage requires each locked sha512 integrity to equal the hosted artifact sha512; unbound (no registry.npmjs.org resolved or sha512 integrity), mismatched or unreported hashes stay incomplete.",
+      "Unlocked optionalDependencies and optional peers are counted under coverage.omitted and not audited; npm does not require them, so they do not make coverage incomplete.",
+      "At most --max (default 6, matching the hosted limit of six new checks per ten minutes) unique versions are checked, in name order; the rest are not-checked.",
+    ],
+  };
+}
+
+function formatText(result) {
+  const lines = [];
+  const { coverage } = result;
+  lines.push(
+    `Audited ${coverage.checked} of ${coverage.uniqueExact} unique exact versions (${coverage.lockedEntries} locked entries, lockfile v${result.lockfileVersion}).`,
+  );
+  for (const item of result.results) {
+    const detail =
+      item.status === "failed"
+        ? ` ${item.error.code}`
+        : (item.findings?.length ? ` ${item.findings.join(",")}` : "") +
+          (item.binding && item.binding !== "verified"
+            ? ` [binding ${item.binding}]`
+            : "");
+    const alias = item.aliases?.length
+      ? ` (as ${item.aliases.join(", ")})`
+      : "";
+    lines.push(`  ${item.status.padEnd(12)} ${item.spec}${alias}${detail}`);
+  }
+  for (const [reason, count] of Object.entries(coverage.skipped))
+    lines.push(`  skipped      ${count} entries: ${reason}`);
+  const { optional, peerOptional, devEntries, devEdges } = coverage.omitted;
+  if (optional + peerOptional + devEntries + devEdges > 0)
+    lines.push(
+      `  omitted      ${optional} unlocked optional, ${peerOptional} unlocked optional peer edges; ${devEntries} dev entries, ${devEdges} dev edges (--omit-dev)`,
+    );
+  lines.push(
+    coverage.complete
+      ? "Coverage: complete for the checked scope."
+      : "Coverage: INCOMPLETE; unchecked, failed or skipped entries are not verified.",
+  );
+  lines.push(result.limitations[0]);
+  return lines.join("\n") + "\n";
+}
+
+export async function runAudit(argv, runtime = {}) {
+  const options = parseAuditArgs(argv);
+  const lock = await readLockfile(options.lockfile);
+  const env = runtime.env ?? process.env;
+  const check =
+    runtime.auditCheck ??
+    ((spec) =>
+      checkHosted(spec, {
+        serverUrl: env.UNMASK_SERVER_URL,
+        fetchImpl: runtime.fetchImpl,
+        signal: runtime.signal,
+        limits: runtime.hostedLimits,
+      }));
+  const result = await auditLock(lock, { ...options, check });
+  process.stdout.write(
+    options.json ? JSON.stringify(result, null, 2) + "\n" : formatText(result),
+  );
+  return result.exitCode;
+}