v1.0.0

[jkowalleck]

First release.

Responsibilities

• Provide a yarn plugin that generates CycloneDX SBOM for current workspace
• Provide a CLI wrapper got said plugin

Capabilities

• Supports yarn3 and yarn4
• Can output in XML and JSON format, CycloneDX v1.2 - v1.6 spec
• Can omit dev dependencies

---

🏗️ GOALS

• have the license situation clarified -- [LEGAL] sort out license sotuation #104
• have all implementation done
  see https://github.com/CycloneDX/cyclonedx-node-yarn/milestone/1
• have integration tests with real yarn setups
• have have CI/CT ready
• have dependabot working
• have release action in place
  see [CHORE] release process #103
  have a pre-release published to github, that
  • has the resulting package as an asset
  • has the resulting plugin-script as an asset
  • has the 3rd party notice as an asset
• have license headers in all files
• have docs finalized
• have scripts for build, lint, cs-fix, etc ...
• squash/fixup all commits in this PR to one commit with a proper commit message that explains capabilities and responsibilities.
  This will be done on merge - quash merge
• ❗ after merge: docs: fix branch names #27

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
Report missing for 11426ea1	∅ (target: 80.00%)

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (11426ea)	Report Missing	Report Missing	Report Missing
Head commit (57b8d43)	2538	2169	85.46%

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#6)	0	0	∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

---

_{🚀 Don’t miss a bit, follow what’s new on Codacy.}

_{Codacy stopped sending the deprecated coverage status on June 5th, 2024. Learn more}

Footnotes

1. Codacy didn't receive coverage data for the commit, or there was an error processing the received data. Check your integration for errors and validate that your coverage setup is correct. ↩

[AugustusKling]

@jkowalleck I haven't had the chance to test in depth nor go through the code changes yet but can at least share some feedback in the meantime.

• In general the plugin works fine and produces similar output to when I had donated the initial code. The differences are mostly expected given your changes.
• Using the plugin using the YARN_PLUGINS environment variable should be mentioned in the readme because this allows to use the plugin without interfering with the project for which the SBOM is generated. It's an alternative to yarn dlx which works also in isolated environments.
• The default of emitting the JSON SBOM to the standard output is not really useful in combination with yarn dlx as it also writes logs to the standard output. The readme should mention the invocation using yarn dlx --quiet.
• This repository no longer contains a yarn.lock file which makes your builds non-reproducible. It should always be committed to the source code repository.
• When attempting to generate the SBOM and a package.json contains for example "version": "1.0-dev" it now crashes in a function called Object.fixVersionField. This concerns me as I would not expect the SBOM generation to adjust version numbers and instead just take them verbatim.
• The SBOM files do no longer identify package instances by their locator hash but use pretty printed identifiers of package names and version numbers instead (value in the bom-ref fields). This is okay as long as the hash is appended for virtual packages. Since I'm pretty sure the hash is clipped to the first 5 characters you may see duplicated identifiers with really low probability.

Output in case a version number is "1.0-dev" or similar:

yarn cyclonedx --output-file by-cyclonedx.json
LOG   | gathering BOM data ...
Internal Error: Invalid version: "1.0-dev"
    at Object.fixVersionField (/code/yarn-plugin-cyclonedx.cjs:48:3853)
    at /code/yarn-plugin-cyclonedx.cjs:48:10076
    at Array.forEach (<anonymous>)
    at Jx (/code/yarn-plugin-cyclonedx.cjs:48:10041)
    at Xf.makeComponent (/code/yarn-plugin-cyclonedx.cjs:48:13143)
    at Xf.makeComponentFromWorkspace (/code/yarn-plugin-cyclonedx.cjs:48:12462)
    at Xf.buildFromWorkspace (/code/yarn-plugin-cyclonedx.cjs:48:11711)
    at async Is.execute (/code/yarn-plugin-cyclonedx.cjs:55:989)
    at async Is.validateAndExecute (/root/.cache/node/corepack/yarn/4.1.0/yarn.js:94:787)
    at async as.run (/root/.cache/node/corepack/yarn/4.1.0/yarn.js:98:3250)

Regarding this see also fixVersionField in https://www.npmjs.com/package/normalize-package-data?activeTab=code and https://www.npmjs.com/package/semver?activeTab=code

I guess it would be preferable to fail the execution instead of risking stripping parts of the version number.

[jkowalleck]

re: #6 (comment)

Using the plugin using the YARN_PLUGINS environment variable should be mentioned in the readme because this allows to use the plugin without interfering with the project for which the SBOM is generated. It's an alternative to yarn dlx which works also in isolated environments.

The yarn dlx creates an isolated environment on the fly. That's why I've put it on the top of the lists — it is probably the least inversive method of running this plugin.
Advanced users of yarn know about the YARN_PLUGINS env var and how to use it; I'd rather not document it, so the new users are not confused, and so the usage is clear and simple.

The default of emitting the JSON SBOM to the standard output is not really useful in combination with yarn dlx as it also writes logs to the standard output. The readme should mention the invocation using yarn dlx --quiet.

Thank you so much for bringing this up. 👍
Added this to the docs!

When attempting to generate the SBOM and a package.json contains for example "version": "1.0-dev" it now crashes in a function called Object.fixVersionField. This concerns me as I would not expect the SBOM generation to adjust version numbers and instead just take them verbatim.

Thanks for testing this. 👍
Converted this remark to #133.

The SBOM files do no longer identify package instances by their locator hash but use pretty printed identifiers of package names and version numbers instead (value in the bom-ref fields). This is okay as long as the hash is appended for virtual packages. Since I'm pretty sure the hash is clipped to the first 5 characters you may see duplicated identifiers with really low probability.

Internally, the components are not identified per @, but by yarn's own descriptorHash.
The CycloneDX library asserts that bom-refs are unique per document, and makes them unique if needed.
So there is no need to add/append any hashes, or is there? If there was, i'd probably register and use a CyclieDX property to store yarn's locatorHash in the SBOM.
@AugustusKling, please advice.

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
Report missing for 11426ea1	∅ (target: 80.00%)

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (11426ea)	Report Missing	Report Missing	Report Missing
Head commit (0ad76ae)	2538	2169	85.46%

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#6)	0	0	∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

---

_{🚀 Don’t miss a bit, follow what’s new on Codacy.}

_{Codacy stopped sending the deprecated coverage status on June 5th, 2024. Learn more}

Footnotes

1. Codacy didn't receive coverage data for the commit, or there was an error processing the received data. Check your integration for errors and validate that your coverage setup is correct. ↩

[AugustusKling]

re: #6 (comment)
[...]

The SBOM files do no longer identify package instances by their locator hash but use pretty printed identifiers of package names and version numbers instead (value in the bom-ref fields). This is okay as long as the hash is appended for virtual packages. Since I'm pretty sure the hash is clipped to the first 5 characters you may see duplicated identifiers with really low probability.

Internally, the components are not identified per @, but by yarn's own descriptorHash. The CycloneDX library asserts that bom-refs are unique per document, and makes them unique if needed. So there is no need to add/append any hashes, or is there? If there was, i'd probably register and use a CyclieDX property to store yarn's locatorHash in the SBOM. @AugustusKling, please advice.

Usually the "descriptor" is the package plus version range as found in a package.json. The "locator" is the package plus a fixed version as in after Yarn decided which version to pick given a version range.

I think the value in Package.locatorHash, not descriptorHash, is even unique when virtual packages are required (see https://yarnpkg.com/advanced/lexicon#virtual-package). Such package instances need to be created in certain cases when a package occurs multiple times in the dependency tree but would resolve its own dependencies to different versions for different instantiations. For example different peer dependencies are provided in the different branches of the transitive dependency tree.

If the Cyclone DX library ensures bom-ref properties are unique across all components we could be sure that all produced SBOM files are okay.

My original code created the CDX.Models.Component instances first and thereafter added the dependencies for each component. In case the current code still follows the same approach, then I don't understand how the Cyclone DX library could make the bom-ref unique while still retriving the correct dependencies by a descriptorHash. Doing the same with locatorHash should be correct, though.

Sadly, I don't have the time these days to read your code in detail but it might be enough to simply get the dependencies by locatorHash instead of descriptorHash. There is no need to include the locatorHash in the SBOM file as it's just in implementation detail of Yarn. What you should guarantee is that each locatorHash value maps to exactly 1 bom-ref value but it does not matter which value is used for the bom-ref in the generated SBOM.

[jkowalleck]

Such package instances need to be created in certain cases when a package occurs multiple times in the dependency tree but would resolve its own dependencies to different versions for different instantiations. For example different peer dependencies are provided in the different branches of the transitive dependency tree.

would you be able to craft a test bed for testing this?
I will try and might come back in a separate pull request.

Regarding locatorHash versus descriptorHash -- in all test beds I tried, I was able to reproducibly craft resulted based on descriptorHash, but not based on locatorHash. this is why ...
(maybe i just did not hate the right test beds, will investigate). thank you for the hint.

If all this only about a unique bom-ref, rest assured that the library takes care of it.
It uses a reversible discriminator mechanism right before normalizing/serializing the data models.