@cdxgen/cdxgen 13.4.0 → 13.6.0

package/lib/managers/docker.js

@@ -10,6 +10,7 @@ import {
   basename,
   isAbsolute,
   join,
+  posix,
   relative,
   resolve,
   win32,
@@ -18,10 +19,11 @@ import process from "node:process";
 import stream from "node:stream/promises";
 import { URL } from "node:url";
 
-import { x } from "tar";
+import { t as listTar, x } from "tar";
 
 import {
   DEBUG_MODE,
+  isAllowedHttpHost,
   isDryRun,
   readEnvironmentVariable,
   recordActivity,
@@ -1081,6 +1083,36 @@ const isSafeImageReference = (fullImageName) =>
   fullImageName === fullImageName.trim() &&
   isImageReference(fullImageName);
 
+/**
+ * Whether an image named in a scanned manifest, such as a docker-compose file
+ * or a Kubernetes spec, may be pulled and inventoried. The name comes from the
+ * scanned project, so a local archive path would read files outside the
+ * allowed paths and a registry outside CDXGEN_ALLOWED_HOSTS would bypass the
+ * host allowlist.
+ *
+ * @param {string} fullImageName Image name from the manifest
+ * @param {Object} [imageObj] Result of parseImageName for the same name
+ * @returns {boolean} true when the image may be followed
+ */
+export const isFollowableManifestImage = (fullImageName, imageObj) => {
+  if (!isSafeImageReference(fullImageName)) {
+    return false;
+  }
+  const allowedHostsEnv = readEnvironmentVariable("CDXGEN_ALLOWED_HOSTS");
+  if (!allowedHostsEnv) {
+    return true;
+  }
+  const registry =
+    (imageObj || parseImageName(fullImageName)).registry || "docker.io";
+  let registryHost;
+  try {
+    registryHost = new URL(`https://${registry}`).hostname;
+  } catch (_err) {
+    return false;
+  }
+  return isAllowedHttpHost(registryHost, allowedHostsEnv);
+};
+
 /**
  * Parse image name
  *
@@ -1586,19 +1618,20 @@ function handleTarWarning(code, message) {
   }
 }
 
-// These paths are known to cause extract errors
+// These paths are known to cause extract errors. CA-store directories
+// (etc/ssl/certs, etc/pki/ca-trust, ssl/certs, cacerts,
+// var/lib/ca-certificates) are deliberately NOT excluded any more: their
+// original extract failures came from the hash-named symlink farms, and
+// symlinks/hardlinks are excluded by type below, while the regular
+// certificate files are exactly what a CBOM must inventory.
 const EXTRACT_EXCLUDE_PATHS = [
   "etc/machine-id",
   "etc/gshadow",
   "etc/shadow",
   "etc/passwd",
-  "etc/ssl/certs",
-  "etc/pki/ca-trust",
   "usr/lib/systemd/",
   "usr/lib64/libdevmapper.so",
   "usr/sbin/",
-  "cacerts",
-  "ssl/certs",
   "logs/",
   "dev/",
   "proc/",
@@ -1608,7 +1641,6 @@ const EXTRACT_EXCLUDE_PATHS = [
   "usr/share/man/",
   "usr/share/icons/",
   "usr/share/i18n/",
-  "var/lib/ca-certificates",
   "root/.gnupg",
   "root/.dotnet",
   "usr/share/licenses/device-mapper-libs",
@@ -1634,16 +1666,18 @@ const MEDIA_EXTENSIONS = new Set([
   ".eot",
 ]);
 
-// These device types are known to cause extract errors
+// These entry types are known to cause extract errors. The names are the
+// ones node-tar's header parser assigns (types.js in the tar package):
+// symlinks and hardlinks ("SymbolicLink", "Link") are how CA-store
+// hash-named entries appear, which is why the CA paths could be un-excluded
+// above once these were dropped by type.
 const EXTRACT_EXCLUDE_TYPES = new Set([
   "BlockDevice",
   "CharacterDevice",
   "FIFO",
-  "MultiVolume",
-  "TapeVolume",
+  "ContinuationFile",
+  "TapeVolumeHeader",
   "SymbolicLink",
-  "RenamedOrSymlinked",
-  "HardLink",
   "Link",
 ]);
 
@@ -1994,6 +2028,126 @@ const resolveContainedArchivePath = (tempDir, archiveRef, kind) => {
   return join(tempDir, archiveRef);
 };
 
+const WHITEOUT_PREFIX = ".wh.";
+const WHITEOUT_OPAQUE = ".wh..wh..opq";
+
+/**
+ * Split an untrusted tar entry path into safe segments. Returns undefined when
+ * the path contains a parent-directory segment.
+ *
+ * @param {string} entryPath Raw entry path from a layer
+ * @returns {string[]|undefined} Path segments, or undefined when unsafe
+ */
+const safeEntrySegments = (entryPath) => {
+  const stripped = stripAbsolutePath(String(entryPath).replaceAll("\\", "/"));
+  const parts = stripped.split("/").filter((p) => p && p !== ".");
+  return parts.includes("..") ? undefined : parts;
+};
+
+/**
+ * Walk down from rootDir through real directories only. A symlink or a
+ * missing component stops the walk, so removals never leave rootDir.
+ *
+ * @param {string} rootDir Extraction root
+ * @param {string[]} parts Directory segments below the root
+ * @returns {string|undefined} The directory path, or undefined
+ */
+const resolveRealDir = (rootDir, parts) => {
+  let current = rootDir;
+  for (const part of parts) {
+    current = join(current, part);
+    let st;
+    try {
+      st = lstatSync(current);
+    } catch (_err) {
+      return undefined;
+    }
+    if (!st.isDirectory()) {
+      return undefined;
+    }
+  }
+  return current;
+};
+
+/**
+ * Apply the OCI/Docker whiteouts of one layer to the merged extraction
+ * directory. `.wh.<name>` removes <name>, and `.wh..wh..opq` empties the
+ * directory it sits in, both only for content from earlier layers, so call
+ * this before extracting the layer itself. Matches
+ * ci/reconstruct-staged-rootfs.py.
+ * https://github.com/opencontainers/image-spec/blob/v1.1.0/layer.md#whiteouts
+ *
+ * @param {string} layerPath Layer tar (optionally compressed)
+ * @param {string} rootDir Merged extraction directory
+ */
+// Applies one whiteout entry of a layer to the merged root.
+const applyWhiteout = (entryPath, rootDir) => {
+  const parts = safeEntrySegments(entryPath);
+  if (!parts?.length) {
+    return;
+  }
+  const name = parts[parts.length - 1];
+  const parentParts = parts.slice(0, -1);
+  if (name === WHITEOUT_OPAQUE) {
+    const dir = resolveRealDir(rootDir, parentParts);
+    if (!dir) {
+      return;
+    }
+    for (const child of readdirSync(dir)) {
+      safeRmSync(join(dir, child), { recursive: true, force: true });
+    }
+    return;
+  }
+  // Other .wh..wh.* names are AUFS metadata, not deletions.
+  if (name.startsWith(".wh..wh.")) {
+    return;
+  }
+  const target = name.slice(WHITEOUT_PREFIX.length);
+  if (!target || target === "." || target === "..") {
+    return;
+  }
+  const dir = resolveRealDir(rootDir, parentParts);
+  if (dir) {
+    safeRmSync(join(dir, target), { recursive: true, force: true });
+  }
+};
+
+const applyLayerWhiteouts = async (layerPath, rootDir) => {
+  const whiteouts = [];
+  try {
+    await listTar({
+      file: layerPath,
+      strict: false,
+      onwarn: () => {
+        // extractTar reports damaged layers
+      },
+      onReadEntry: (entry) => {
+        if (
+          basename(String(entry.path).replaceAll("\\", "/")).startsWith(
+            WHITEOUT_PREFIX,
+          )
+        ) {
+          whiteouts.push(entry.path);
+        }
+        entry.resume();
+      },
+    });
+  } catch (_err) {
+    // extractTar reports unreadable layers
+  }
+  for (const entryPath of whiteouts) {
+    // One whiteout that cannot be applied (name too long, EACCES) must not
+    // abort the layer's extraction, which would hide everything it adds.
+    try {
+      applyWhiteout(entryPath, rootDir);
+    } catch (err) {
+      if (DEBUG_MODE) {
+        console.log(`Skipping whiteout ${entryPath}: ${err.message}`);
+      }
+    }
+  }
+};
+
 /**
  * Parse a Docker/containerd manifest file and extract all image layers into a
  * single merged directory. Resolves the last layer's config to determine the
@@ -2074,6 +2228,7 @@ export const extractFromManifest = async (
         console.log(`Extracting layer ${layer} to ${allLayersExplodedDir}`);
       }
       try {
+        await applyLayerWhiteouts(containedLayerPath, allLayersExplodedDir);
         await extractTar(containedLayerPath, allLayersExplodedDir, options);
       } catch (err) {
         if (err.code === "TAR_BAD_ARCHIVE") {
@@ -2333,6 +2488,77 @@ export const exportImage = async (fullImageName, options) => {
   return undefined;
 };
 
+// Directories that hold far more than gems. An image that names one as its gem
+// directory would turn the gem scan into a scan of the whole tree.
+const BROAD_IMAGE_DIRS = new Set([
+  "/bin",
+  "/boot",
+  "/dev",
+  "/etc",
+  "/home",
+  "/lib",
+  "/lib64",
+  "/opt",
+  "/proc",
+  "/root",
+  "/run",
+  "/sbin",
+  "/srv",
+  "/sys",
+  "/tmp",
+  "/usr",
+  "/usr/bin",
+  "/usr/lib",
+  "/usr/lib64",
+  "/usr/local",
+  "/usr/local/lib",
+  "/usr/share",
+  "/var",
+  "/var/lib",
+]);
+const MAX_IMAGE_GEM_DIRS = 16;
+
+/**
+ * The gem directories an image's environment names in GEM_HOME, GEM_PATH and
+ * BUNDLE_PATH. Only absolute paths without `..` segments are kept, so an image
+ * cannot steer the scan outside its own root, and each is normalized; the root
+ * and broad system directories such as /usr or /var are refused, so an image
+ * cannot turn the gem scan into a scan of the whole tree.
+ *
+ * @param {string[]|undefined} env image config Env entries, `NAME=value`
+ * @returns {string[]} absolute in-image directories, deduplicated, at most
+ *   MAX_IMAGE_GEM_DIRS
+ */
+export function imageGemDirs(env) {
+  const dirs = new Set();
+  if (!Array.isArray(env)) {
+    return [];
+  }
+  for (const entry of env) {
+    if (typeof entry !== "string") {
+      continue;
+    }
+    const separator = entry.indexOf("=");
+    if (separator <= 0) {
+      continue;
+    }
+    const name = entry.slice(0, separator);
+    if (!["GEM_HOME", "GEM_PATH", "BUNDLE_PATH"].includes(name)) {
+      continue;
+    }
+    for (const value of entry.slice(separator + 1).split(":")) {
+      if (!value.startsWith("/") || value.split("/").includes("..")) {
+        continue;
+      }
+      const dir = posix.normalize(value).replace(/\/+$/, "");
+      if (dir && !BROAD_IMAGE_DIRS.has(dir)) {
+        dirs.add(dir);
+      }
+    }
+  }
+  return Array.from(dirs).sort().slice(0, MAX_IMAGE_GEM_DIRS);
+}
+
 /**
  * Method to retrieve path list for system-level packages
  */
@@ -2376,6 +2602,7 @@ export const getPkgPathList = (exportData, lastWorkingDir) => {
   if (allLayersExplodedDir && allLayersExplodedDir !== "") {
     knownSysPaths = knownSysPaths.concat([
       join(allLayersExplodedDir, "/usr/local/go"),
+      join(allLayersExplodedDir, "/usr/local/bundle"),
       join(allLayersExplodedDir, "/usr/local/lib"),
       join(allLayersExplodedDir, "/usr/local/lib64"),
       join(allLayersExplodedDir, "/opt"),
@@ -2390,6 +2617,7 @@ export const getPkgPathList = (exportData, lastWorkingDir) => {
   } else if (allLayersExplodedDir === "") {
     knownSysPaths = knownSysPaths.concat([
       join(allLayersExplodedDir, "/usr/local/go"),
+      join(allLayersExplodedDir, "/usr/local/bundle"),
       join(allLayersExplodedDir, "/usr/local/lib"),
       join(allLayersExplodedDir, "/usr/local/lib64"),
       join(allLayersExplodedDir, "/opt"),
@@ -2400,6 +2628,11 @@ export const getPkgPathList = (exportData, lastWorkingDir) => {
       join(allLayersExplodedDir, "/var/lib"),
     ]);
   }
+  // The official Ruby images install gems into GEM_HOME=/usr/local/bundle, and
+  // an image can point GEM_HOME, GEM_PATH or BUNDLE_PATH anywhere else.
+  for (const gemDir of imageGemDirs(exportData?.inspectData?.Config?.Env)) {
+    knownSysPaths.push(join(allLayersExplodedDir || "", gemDir));
+  }
   if (safeExistsSync(join(allLayersDir, "Files"))) {
     knownSysPaths.push(join(allLayersDir, "Files"));
   }

package/lib/parsers/email.js

@@ -0,0 +1,277 @@
+import { isIPv4, isIPv6 } from "node:net";
+import { domainToASCII, domainToUnicode } from "node:url";
+
+/**
+ * Validation of RFC 6531 internationalized email addresses: the JSON Schema
+ * `idn-email` format the CycloneDX schemas assert on contact addresses.
+ *
+ * It follows what `cdxrs validate` (jsonschema-rs) accepts, so the JS and Rust
+ * validators agree on the addresses BOMs actually carry, internationalized
+ * ones included. Two deliberate differences keep this small:
+ * - a `Display Name <address>` string is not an address here, as RFC 6531
+ *   says; jsonschema-rs tolerates it, but cdxgen never emits one and the
+ *   source parsers must not mistake one for an email;
+ * - the RFC 5892 contextual rules and the RFC 5893 bidi rule are not applied,
+ *   so a few exotic internationalized domains are accepted that cdxrs
+ *   rejects. No valid domain is rejected for that.
+ *
+ * Every check is a bounded pass over the input with no backtracking regular
+ * expression.
+ */
+
+const LOCAL_PART_MAX_LENGTH = 64;
+const HOSTNAME_MAX_LENGTH = 253;
+const LABEL_MAX_LENGTH = 63;
+const ATEXT_SPECIALS = "!#$%&'*+-/=?^_`{|}~";
+// Appended before IDNA conversion so a numeric last label is not read as an
+// IPv4 address by the WHATWG host parser behind `domainToASCII`.
+const CONVERSION_SUFFIX = ".invalid";
+// What an internationalized label may hold: letters, combining marks and
+// decimal digits (RFC 5892 PVALID, by general category), plus the characters
+// RFC 5892 makes PVALID by exception, such as the Catalan middle dot.
+const IDNA_LABEL_CHAR = /^[\p{L}\p{Mn}\p{Mc}\p{Nd}]$/u;
+const IDNA_EXCEPTIONS = new Set([
+  "·",
+  "͵",
+  "׳",
+  "״",
+  "۽",
+  "۾",
+  "་",
+  "‌",
+  "‍",
+  "〇",
+  "・",
+]);
+const COMBINING_MARK = /^\p{M}$/u;
+
+/**
+ * @param {string} text Text to inspect
+ * @returns {boolean} Whether the text holds only ASCII
+ */
+const isAscii = (text) => {
+  for (let index = 0; index < text.length; index++) {
+    if (text.charCodeAt(index) > 0x7f) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * @param {number} code Code point
+ * @returns {boolean} Whether the code point is an ASCII letter or digit
+ */
+const isAsciiAlphanumeric = (code) =>
+  (code >= 0x30 && code <= 0x39) ||
+  (code >= 0x41 && code <= 0x5a) ||
+  (code >= 0x61 && code <= 0x7a);
+
+/**
+ * RFC 5322 `atext`, widened by RFC 6531 to every non-ASCII code point.
+ *
+ * @param {string} char One code point
+ * @returns {boolean} Whether it may appear in an unquoted local part atom
+ */
+const isAtext = (char) => {
+  const code = char.codePointAt(0);
+  return (
+    code > 0x7f || isAsciiAlphanumeric(code) || ATEXT_SPECIALS.includes(char)
+  );
+};
+
+/**
+ * The content of a quoted local part: printable ASCII other than `"` and `\`,
+ * non-ASCII, spaces and tabs, and backslash-escaped printable characters.
+ *
+ * @param {string} text Quoted local part without its surrounding quotes
+ * @returns {boolean} Whether the quoted content is valid
+ */
+const isQuotedContent = (text) => {
+  const chars = [...text];
+  for (let index = 0; index < chars.length; index++) {
+    const code = chars[index].codePointAt(0);
+    if (code === 0x5c) {
+      index++;
+      const escaped = chars[index]?.codePointAt(0);
+      if (escaped === undefined || escaped < 0x21 || escaped === 0x7f) {
+        return false;
+      }
+    } else if (code < 0x20 || code === 0x22 || code === 0x7f) {
+      if (code !== 0x09) {
+        return false;
+      }
+    }
+  }
+  return true;
+};
+
+/**
+ * A dot-atom (`atext` atoms joined by single dots) or a quoted string, at
+ * most 64 characters.
+ *
+ * @param {string} localPart Text before the last `@`
+ * @returns {boolean} Whether it is a valid local part
+ */
+const isValidLocalPart = (localPart) => {
+  if (!localPart || [...localPart].length > LOCAL_PART_MAX_LENGTH) {
+    return false;
+  }
+  if (
+    localPart.length >= 2 &&
+    localPart.startsWith('"') &&
+    localPart.endsWith('"')
+  ) {
+    // An empty quoted local part (`""@example.com`) is valid per RFC 5321.
+    return isQuotedContent(localPart.slice(1, -1));
+  }
+  return localPart
+    .split(".")
+    .every((atom) => atom.length > 0 && [...atom].every(isAtext));
+};
+
+/**
+ * An RFC 1123 label in ASCII (A-label) form.
+ *
+ * @param {string} label ASCII label
+ * @returns {boolean} Whether the label is valid
+ */
+const isValidAsciiLabel = (label) => {
+  if (
+    !label ||
+    label.length > LABEL_MAX_LENGTH ||
+    label.startsWith("-") ||
+    label.endsWith("-")
+  ) {
+    return false;
+  }
+  for (let index = 0; index < label.length; index++) {
+    const code = label.charCodeAt(index);
+    if (!isAsciiAlphanumeric(code) && code !== 0x2d) {
+      return false;
+    }
+  }
+  // Hyphens in the third and fourth positions are reserved for A-labels.
+  return label.slice(2, 4) !== "--" || label.toLowerCase().startsWith("xn--");
+};
+
+/**
+ * The Unicode form of a label, as `domainToUnicode` returns it.
+ *
+ * @param {string} label Unicode label
+ * @returns {boolean} Whether the label is valid
+ */
+const isValidUnicodeLabel = (label) => {
+  // `domainToUnicode` leaves an undecodable A-label as it was.
+  if (label.toLowerCase().startsWith("xn--")) {
+    return false;
+  }
+  if (isAscii(label)) {
+    return true;
+  }
+  if (
+    label.startsWith("-") ||
+    label.endsWith("-") ||
+    label.slice(2, 4) === "--"
+  ) {
+    return false;
+  }
+  const chars = [...label];
+  return (
+    !COMBINING_MARK.test(chars[0]) &&
+    chars.every(
+      (char) =>
+        char.charCodeAt(0) <= 0x7f ||
+        IDNA_EXCEPTIONS.has(char) ||
+        IDNA_LABEL_CHAR.test(char),
+    )
+  );
+};
+
+/**
+ * An internationalized hostname: mapped to its A-label form with UTS #46
+ * processing, held to the ASCII hostname rules, and every A-label decoded
+ * back and checked for the characters IDNA allows.
+ *
+ * @param {string} hostname Hostname, possibly holding non-ASCII labels
+ * @returns {boolean} Whether it is a valid IDN hostname
+ */
+export const isValidIdnHostname = (hostname) => {
+  if (typeof hostname !== "string" || !hostname) {
+    return false;
+  }
+  for (let index = 0; index < hostname.length; index++) {
+    // Controls and spaces never belong in a hostname; the WHATWG parser
+    // behind `domainToASCII` would silently strip tabs and newlines.
+    const code = hostname.charCodeAt(index);
+    if (code <= 0x20 || code === 0x7f) {
+      return false;
+    }
+  }
+  let ascii = hostname;
+  if (!isAscii(hostname)) {
+    const converted = domainToASCII(`${hostname}${CONVERSION_SUFFIX}`);
+    if (!converted.endsWith(CONVERSION_SUFFIX)) {
+      return false;
+    }
+    ascii = converted.slice(0, -CONVERSION_SUFFIX.length);
+  }
+  if (
+    !ascii ||
+    ascii.length > HOSTNAME_MAX_LENGTH ||
+    ascii.endsWith(".") ||
+    !ascii.split(".").every(isValidAsciiLabel)
+  ) {
+    return false;
+  }
+  if (!/(^|\.)xn--/i.test(ascii)) {
+    return true;
+  }
+  const unicode = domainToUnicode(`${ascii}${CONVERSION_SUFFIX}`);
+  return (
+    unicode.endsWith(CONVERSION_SUFFIX) &&
+    unicode
+      .slice(0, -CONVERSION_SUFFIX.length)
+      .split(".")
+      .every(isValidUnicodeLabel)
+  );
+};
+
+/**
+ * @param {string} domain Text after the last `@`
+ * @returns {boolean} Whether it is a valid hostname or address literal
+ */
+const isValidEmailDomain = (domain) => {
+  if (domain.startsWith("[") && domain.endsWith("]")) {
+    const literal = domain.slice(1, -1);
+    // RFC 5321 address-literal tags are case-insensitive.
+    if (literal.slice(0, 5).toLowerCase() === "ipv6:") {
+      return isIPv6(literal.slice(5));
+    }
+    return isIPv4(literal);
+  }
+  return isValidIdnHostname(domain);
+};
+
+/**
+ * Whether a value is a valid RFC 6531 email address (`idn-email`): a dot-atom
+ * or quoted local part, where non-ASCII characters are allowed, then `@` and
+ * an internationalized hostname or a bracketed IPv4/IPv6 literal.
+ *
+ * @param {string} value Candidate email address
+ * @returns {boolean} true when the value is a valid address
+ */
+export const isValidIdnEmail = (value) => {
+  if (typeof value !== "string") {
+    return false;
+  }
+  // A domain never holds `@`; a quoted local part may.
+  const separator = value.lastIndexOf("@");
+  if (separator <= 0 || separator === value.length - 1) {
+    return false;
+  }
+  return (
+    isValidLocalPart(value.slice(0, separator)) &&
+    isValidEmailDomain(value.slice(separator + 1))
+  );
+};