[WIP] CycloneDX v2.0 Specification by stevespringett · Pull Request #652 · CycloneDX/specification

stevespringett · 2025-06-15T01:20:54Z

Important

WORK IN PROGRESS
see Milestone for progress: https://github.com/CycloneDX/specification/milestone/2

BREAKING Changes

Drop schema for XML.
To be explained further.
Drop schema for Protocol Buffers
Reasoning: Downstream spec users may build ontop of JSON schema.
To be explained further.

... TBC ...

Added

... TBD ...

Chaned

... TBD ...

Removed

... TBD ...

Misc

... TBD ...

fixes CycloneDX 2.0 #631

+    // Pattern for markdown links at the end
+    const markdownLinkPattern = /\]\([^)]+\)$/;
+
+    return urlPattern.test(text) || markdownLinkPattern.test(text);


+    // Pattern for markdown links at the end
+    const markdownLinkPattern = /\]\([^)]+\)$/;
+
+    return urlPattern.test(text) || markdownLinkPattern.test(text);


+        const absoluteRootPath = path.resolve(rootSchemaPath);
+
+        // Verify paths exist
+        await fs.access(absoluteModelsDir);


To fix this safely without changing intended bundling behavior, validate both CLI paths against a strict policy before any filesystem access. For this script, the least disruptive policy is: only allow paths that resolve under the current working directory (process.cwd()), after normalization.

Best implementation in tools/src/main/js/bundler/bundle-schemas.js:

Add a helper that:

resolves the user path with path.resolve,

computes path.relative(baseDir, resolvedPath),

rejects if the result is absolute or starts with .. (meaning outside base).

Use this helper inside bundleSchemas for both modelsDirectory and rootSchemaPath instead of direct path.resolve(...).

Keep all existing behavior otherwise (same flow, same fs.access, same outputs), only adding early validation error on unsafe paths.

No external dependencies are needed; Node’s built-in path is sufficient.

+
+        // Verify paths exist
+        await fs.access(absoluteModelsDir);
+        await fs.access(absoluteRootPath);


To fix this without changing intended functionality, validate that the user-provided rootSchemaPath resolves to a file within the provided modelsDirectory tree before using it in filesystem operations. The safest approach here is:

Resolve both inputs to absolute paths.

Compute path.relative(absoluteModelsDir, absoluteRootPath).

Reject if the relative path is empty? (empty is fine if same path), absolute, or starts with .. (meaning outside base directory).

Optionally keep existence checks after boundary validation.

In tools/src/main/js/bundler/bundle-schemas.js, update bundleSchemas right after lines 182–183 to enforce this containment rule and throw a clear error when violated. No new dependencies are required; use built-in path.

+        console.log(`Output (minified): ${minifiedPath}\n`);
+
+        // Read all schema files in the models directory
+        const files = await fs.readdir(absoluteModelsDir);


To fix this safely without changing intended behavior, validate both CLI-supplied paths (modelsDirectory and rootSchemaPath) against a trusted base directory before using them in filesystem operations. The best approach here is:

Define a trusted base directory for this script execution (for example, process.cwd()).

Resolve user inputs relative to that base.

Enforce containment: ensure each resolved path is either exactly the base directory or starts with base + path.sep.

Reject invalid/outside paths before any fs.access, fs.readdir, or file reads.

In tools/src/main/js/bundler/bundle-schemas.js, add a helper like resolvePathWithinBase(baseDir, userPath, label) near existing utility functions, and replace direct path.resolve(...) usage in bundleSchemas with this checked resolver. No new package dependency is needed; Node’s built-in path is sufficient.

+            const schemaPath = path.join(absoluteModelsDir, file);
+            console.log(`  Reading ${file}...`);
+
+            const content = await fs.readFile(schemaPath, 'utf8');


The best fix is to canonicalize and constrain both user-provided paths to an approved root directory before any file operations.
For this script, the least disruptive approach is:

Define a trusted root (for example, process.cwd() for CLI usage).

Resolve user inputs relative to that root.

Canonicalize with fs.realpath (after existence checks).

Enforce containment with path.relative checks (!rel.startsWith('..') && !path.isAbsolute(rel)).

Use only the validated canonical paths afterward.

This preserves existing behavior for normal relative invocations (like ./schema/...) while preventing directory traversal or arbitrary absolute path targeting outside the project working tree.

Edit region: tools/src/main/js/bundler/bundle-schemas.js, inside bundleSchemas where absoluteModelsDir / absoluteRootPath are computed and checked (lines ~182–187 in the snippet). No new dependency is needed.

+
+        // Read the root schema
+        console.log(`\nReading root schema...`);
+        const rootContent = await fs.readFile(absoluteRootPath, 'utf8');


General fix: validate user-controlled paths against an explicit trusted root before using them in filesystem operations. Normalization alone is insufficient; enforce containment (candidate must stay under safeRoot) after resolving absolute paths.

Best fix here (without changing intended functionality too much): in bundleSchemas, derive a safeRootDir from process.cwd() (or options.safeRootDir if provided), resolve both modelsDirectory and rootSchemaPath, and reject execution if either resolved path is outside the safe root. This keeps current CLI behavior for normal in-repo usage while preventing arbitrary absolute/parent traversal paths.

Changes needed in tools/src/main/js/bundler/bundle-schemas.js:

Add a small helper function to check whether a target path is inside a base directory.

In bundleSchemas (around lines 180–184), compute safeRootDir.

After computing absoluteModelsDir and absoluteRootPath, validate both with the helper and throw an error on violation.

No new dependencies required.

+        // Write bundled (pretty) version
+        console.log('\nWriting bundled schema...');
+        const prettyJson = JSON.stringify(finalSchema, null, 2);
+        await fs.writeFile(bundledPath, prettyJson);


To fix this without changing intended functionality, validate that the computed output paths stay within a safe, expected root directory before writing files. Since outputs are derived from rootSchemaPath, the natural safe root is absoluteModelsDir (the provided models directory). After resolving/normalizing paths, ensure:

absoluteRootPath is inside absoluteModelsDir

bundledPath and minifiedPath are inside absoluteModelsDir

Use path.relative(root, candidate) and reject when result is absolute or starts with .. (or equals ..). This is a robust containment check and avoids prefix tricks. Implement a small helper in tools/src/main/js/bundler/bundle-schemas.js and call it in bundleSchemas immediately after path resolution and before writes.

+        console.log('\nWriting bundled schema...');
+        const prettyJson = JSON.stringify(finalSchema, null, 2);
+        await fs.writeFile(bundledPath, prettyJson);
+        const bundledStats = await fs.stat(bundledPath);


To fix this, validate and constrain user-provided paths before they are used to derive output file locations. In general, normalize untrusted paths (path.resolve) and enforce containment within a trusted root directory. This preserves current functionality for valid inputs while preventing arbitrary filesystem access.

Best single fix here: in bundleSchemas (around lines 182–183), resolve both modelsDirectory and rootSchemaPath, then verify both are inside a trusted base (use process.cwd() for CLI-compatible behavior). Add a helper that checks targetPath is equal to the base or starts with base + path.sep after normalization. Throw an error if validation fails. This prevents rootSchemaDir (and thus bundledPath/minifiedPath) from pointing outside the allowed workspace.

Changes needed in tools/src/main/js/bundler/bundle-schemas.js:

Add a small helper function (no new dependency) for containment check.

In bundleSchemas, define allowedBaseDir = path.resolve(process.cwd()).

Validate absoluteModelsDir and absoluteRootPath against allowedBaseDir before file access/writes.

+        const lineCount = minifiedJson.split('\n').length;
+        console.log(`  Minified JSON is on ${lineCount} line(s)`);
+
+        await fs.writeFile(minifiedPath, minifiedJson);


To fix this without changing intended behavior, validate that all filesystem operations remain within a trusted base directory. The best fit here is to derive a safe base from the provided models directory (already a required input), normalize/resolve all relevant paths, and reject any path that escapes that base.

In tools/src/main/js/bundler/bundle-schemas.js, inside bundleSchemas right after computing absoluteModelsDir/absoluteRootPath, add a helper that verifies targetPath is inside baseDir using path.relative (robust across platforms). Then:

Validate absoluteRootPath is within absoluteModelsDir.

Validate generated outputs bundledPath and minifiedPath are within absoluteModelsDir.
If validation fails, throw an error before any write. This preserves current functionality for normal valid inputs while preventing arbitrary path writes.

No new imports or dependencies are required.

+        console.log(`  Minified JSON is on ${lineCount} line(s)`);
+
+        await fs.writeFile(minifiedPath, minifiedJson);
+        const minifiedStats = await fs.stat(minifiedPath);


General fix: enforce that all filesystem operations using user-influenced paths are confined to an approved root directory. Normalize with path.resolve, then verify resulting paths stay inside that root.

Best fix here (without changing core functionality): in bundleSchemas, define a trusted base directory (current working directory), then reject modelsDirectory and rootSchemaPath if they resolve outside it. Additionally, verify computed output paths (bundledPath, minifiedPath) are still inside the same trusted base. This preserves existing behavior for normal in-repo usage while preventing arbitrary filesystem targets.

Changes needed in tools/src/main/js/bundler/bundle-schemas.js:

Add helper isPathInside(parentDir, targetPath).

In bundleSchemas, after resolving inputs, validate:

absoluteModelsDir inside trusted root

absoluteRootPath inside trusted root

After generating output paths, validate:

bundledPath inside trusted root

minifiedPath inside trusted root

No new dependencies required.