{"id":20617806,"url":"https://github.com/cyclonedx/cyclonedx-javascript-library","last_synced_at":"2025-04-05T03:11:44.525Z","repository":{"id":36960973,"uuid":"455652613","full_name":"CycloneDX/cyclonedx-javascript-library","owner":"CycloneDX","description":"Core functionality of OWASP CycloneDX for JavaScript (Node.js or WebBrowser) written in TypeScript.","archived":false,"fork":false,"pushed_at":"2024-10-30T03:19:20.000Z","size":3187,"stargazers_count":15,"open_issues_count":19,"forks_count":10,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-10-30T06:12:43.875Z","etag":null,"topics":["bill-of-materials","bom","cyclonedx","hacktoberfest","json","library","mbom","node","obom","owasp","saasbom","sbom","software-bill-of-materials","software-library","spdx","vdr","vex","web","xml"],"latest_commit_sha":null,"homepage":"https://cyclonedx.org/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CycloneDX.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://owasp.org/donate/?reponame=www-project-cyclonedx\u0026title=OWASP+CycloneDX"]}},"created_at":"2022-02-04T18:20:43.000Z","updated_at":"2024-10-25T13:24:11.000Z","dependencies_parsed_at":"2024-01-20T15:25:24.778Z","dependency_job_id":"48a837a6-5431-46f4-9c71-4c4c28654c78","html_url":"https://github.com/CycloneDX/cyclonedx-javascript-library","commit_stats":{"total_commits":951,"total_committers":7,"mean_commits":"135.85714285714286","dds":"0.43953732912723453","last_synced_commit":"7fcc595145031d90aa8b2d74cd0db1b9f999732e"},"previous_names":[],"tags_count":82,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CycloneDX%2Fcyclonedx-javascript-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CycloneDX%2Fcyclonedx-javascript-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CycloneDX%2Fcyclonedx-javascript-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CycloneDX%2Fcyclonedx-javascript-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CycloneDX","download_url":"https://codeload.github.com/CycloneDX/cyclonedx-javascript-library/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280272,"owners_count":20912967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bill-of-materials","bom","cyclonedx","hacktoberfest","json","library","mbom","node","obom","owasp","saasbom","sbom","software-bill-of-materials","software-library","spdx","vdr","vex","web","xml"],"created_at":"2024-11-16T12:06:01.467Z","updated_at":"2025-04-05T03:11:44.519Z","avatar_url":"https://github.com/CycloneDX.png","language":"TypeScript","readme":"# CycloneDX JavaScript Library\n\n[![shield_npm-version]][link_npm]\n[![shield_rtfd]][link_rtfd]\n[![shield_gh-workflow-test]][link_gh-workflow-test]\n[![shield_coverage]][link_codacy]\n[![shield_ossf-best-practices]][link_ossf-best-practices]\n[![shield_license]][license_file]  \n[![shield_website]][link_website]\n[![shield_slack]][link_slack]\n[![shield_groups]][link_discussion]\n[![shield_twitter-follow]][link_twitter]\n\n----\n\nCore functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or _WebBrowsers_),\nwritten in _TypeScript_ and compiled for the target.\n\n\u003e [!NOTE]  \n\u003e This package is a software library not intended for standalone use.  \n\u003e For a list of tools and plugins for generating Software Bill of Materials (SBOM), check out the [meta-package](https://github.com/CycloneDX/cyclonedx-node-module?tab=readme-ov-file#readme).\n\n## Responsibilities\n\n* Provide a general purpose _JavaScript_-implementation of [_CycloneDX_][link_website] for _Node.js_ and _WebBrowsers_.\n* Provide typing for said implementation, so developers and dev-tools can rely on it.\n* Provide data models to work with _CycloneDX_.\n* Provide JSON- and XML-normalizers, that...\n  * supports all shipped data models.\n  * respects any injected [_CycloneDX_ Specification][CycloneDX-spec] and generates valid output according to it.\n  * can be configured to generate reproducible/deterministic output.\n  * can prepare data structures for JSON- and XML-serialization.\n* Serialization:\n  * Provide a universal JSON-serializer for all target environments.\n  * Provide an XML-serializer for all target environments.\n  * Support the downstream implementation of custom XML-serializers tailored to specific environments  \n    by providing an abstract base class that takes care of normalization and BomRef-discrimination.  \n    This is done, because there is no universal XML support in _JavaScript_.\n* Provide formal JSON- and XML-validators according to [_CycloneDX_ Specification][CycloneDX-spec]. (currently for _Node.js_ only)\n\n## Capabilities\n\n* Enums for the following use cases:\n  * `AttachmentEncoding`\n  * `ComponentScope`\n  * `ComponentType`\n  * `ExternalReferenceType`\n  * `HashAlgorithm`\n  * `Vulnerability` related:  \n    * `AffectStatus`\n    * `AnalysisJustification`\n    * `AnalysisResponse`\n    * `AnalysisState`\n    * `RatingMethod`\n    * `Severity`\n* Data models for the following use cases:\n  * `Attachment`\n  * `Bom`\n  * `BomLink`, `BomLinkDocument`, `BomLinkElement`\n  * `BomRef`, `BomRefRepository`\n  * `Component`, `ComponentRepository`, `ComponentEvidence`\n  * `ExternalReference`, `ExternalReferenceRepository`\n  * `Hash`, `HashContent`,  `HashDictionary`\n  * `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository`\n  * `Metadata`\n  * `OrganizationalContact`, `OrganizationalContactRepository`\n  * `OrganizationalEntity`, `OrganizationalEntityRepository`\n  * `Property`, `PropertyRepository`\n  * `SWID`\n  * `Tool`, `ToolRepository`, `Tools`\n  * `Vulnerability` related:\n    * `Advisory`, `AdvisoryRepository`\n    * `Affect`, `AffectRepository`, `AffectedSingleVersion`, `AffectedVersionRange`, `AffectedVersionRepository`\n    * `Analysis`\n    * `Credits`\n    * `Rating`, `RatingRepository`\n    * `Reference`, `ReferenceRepository`\n    * `Source`\n    * `Vulnerability`, `VulnerabilityRepository`\n* Utilities for the following use cases:\n  * Generate valid random SerialNumbers for `Bom.serialNumber`\n* Factories for the following use cases:\n  * Create data models from any license descriptor string\n  * Create `PackageURL` from `Component` data models\n  * Specific to _Node.js_: create data models from PackageJson-like data structures and derived data\n* Builders for the following use cases:\n  * Specific to _Node.js_: create deep data models `Tool` or `Component` from PackageJson-like data structures\n* Implementation of the [_CycloneDX_ Specification][CycloneDX-spec] for the following versions:\n  * `1.6`\n  * `1.5`\n  * `1.4`\n  * `1.3`\n  * `1.2`\n* Normalizers that convert data models to JSON structures\n* Normalizers that convert data models to XML structures\n* Universal serializer that converts `Bom` data models to JSON string\n* Specific  Serializer that converts `Bom` data models to XML string:\n  * Specific to _WebBrowsers_: implementation utilizes browser-specific document generators and printers.\n  * Specific to _Node.js_: implementation utilizes [optional dependencies](#optional-dependencies) as described below\n* Formal validators for JSON string and XML string (currently for _Node.js_ only)  \n  Requires [optional dependencies](#optional-dependencies) as described below\n\n## Installation\n\nThis package and the build results are available for _npm_, _pnpm_ and _yarn_:\n\n```shell\nnpm i -S @cyclonedx/cyclonedx-library\npnpm add @cyclonedx/cyclonedx-library\nyarn add @cyclonedx/cyclonedx-library\n```\n\nYou can install the package from source,\nwhich will build automatically on installation:\n\n```shell\nnpm i -S github:CycloneDX/cyclonedx-javascript-library\npnpm add github:CycloneDX/cyclonedx-javascript-library\nyarn add @cyclonedx/cyclonedx-library@github:CycloneDX/cyclonedx-javascript-library # only with yarn-2\n```\n\n## Optional Dependencies\n\nSome dependencies are optional.\nSee the shipped `package.json` for version constraints.\n\n* Serialization to XML on _Node.js_ requires any of:\n  * [`xmlbuilder2`](https://www.npmjs.com/package/xmlbuilder2)\n* Validation of JSON on _Node.js_ requires all of:\n  * [`ajv`](https://www.npmjs.com/package/ajv)\n  * [`ajv-formats`](https://www.npmjs.com/package/ajv-formats)\n  * [`ajv-formats-draft2019`](https://www.npmjs.com/package/ajv-formats-draft2019)\n* Validation of XML on _Node.js_ requires all of:\n  * [`libxmljs2`](https://www.npmjs.com/package/libxmljs2)  \n  * the system might need to meet the requirements for [`node-gyp`](https://github.com/TooTallNate/node-gyp#installation), in certain cases.\n\n## Usage\n\nSee extended [examples].\n\n### As _Node.js_ package\n\n```javascript\nconst CDX = require('@cyclonedx/cyclonedx-library')\n\nconst bom = new CDX.Models.Bom()\nbom.metadata.component = new CDX.Models.Component(\n  CDX.Enums.ComponentType.Application,\n  'MyProject'\n)\nconst componentA = new CDX.Models.Component(\n  CDX.Enums.ComponentType.Library,\n  'myComponentA',\n)\nbom.components.add(componentA)\nbom.metadata.component.dependencies.add(componentA.bomRef)\n```\n\n### In _WebBrowsers_\n\n```html\n\u003cscript src=\"path-to-this-package/dist.web/lib.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"application/javascript\"\u003e\n    const CDX = CycloneDX_library\n\n    let bom = new CDX.Models.Bom()\n    bom.metadata.component = new CDX.Models.Component(\n        CDX.Enums.ComponentType.Application,\n        'MyProject'\n    )\n    const componentA = new CDX.Models.Component(\n        CDX.Enums.ComponentType.Library,\n        'myComponentA',\n    )\n    bom.components.add(componentA)\n    bom.metadata.component.dependencies.add(componentA.bomRef)\n\u003c/script\u003e\n```\n\n## API documentation\n\nWe ship annotated type definitions, so that your IDE and tools may pick up the documentation when you use this library downstream.\n\nThere are also pre-rendered documentations hosted on [readthedocs][link_rtfd].\n\n## Development \u0026 Contributing\n\nFeel free to open issues, bug reports or pull requests.  \nSee the [CONTRIBUTING][contributing_file] file for details.\n\n## License\n\nPermission to modify and redistribute is granted under the terms of the Apache 2.0 license.  \nSee the [LICENSE][license_file] file for the full license.\n\n[CycloneDX-spec]: https://github.com/CycloneDX/specification/#readme\n\n[license_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/LICENSE\n[contributing_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/CONTRIBUTING.md\n[examples]: https://github.com/CycloneDX/cyclonedx-javascript-library/tree/main/examples/README.md\n[link_rtfd]: https://cyclonedx-javascript-library.readthedocs.io\n\n[shield_npm-version]: https://img.shields.io/npm/v/%40cyclonedx%2fcyclonedx-library/latest?label=npm\u0026logo=npm\u0026logoColor=white \"npm\"\n[shield_rtfd]: https://img.shields.io/readthedocs/cyclonedx-javascript-library?logo=readthedocs\u0026logoColor=white \"Read the Docs\"\n[shield_gh-workflow-test]: https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-javascript-library/nodejs.yml?branch=main\u0026logo=GitHub\u0026logoColor=white \"tests\"\n[shield_coverage]: https://img.shields.io/codacy/coverage/ae6c086b53d54653ad5077b12ec22264?logo=Codacy\u0026logoColor=white \"test coverage\"\n[shield_ossf-best-practices]: https://img.shields.io/cii/percentage/7883?label=OpenSSF%20best%20practices \"OpenSSF best practices\"\n[shield_license]: https://img.shields.io/github/license/CycloneDX/cyclonedx-javascript-library?logo=open%20source%20initiative\u0026logoColor=white \"license\"\n[shield_website]: https://img.shields.io/badge/https://-cyclonedx.org-blue.svg \"homepage\"\n[shield_slack]: https://img.shields.io/badge/slack-join-blue?logo=Slack\u0026logoColor=white \"slack join\"\n[shield_groups]: https://img.shields.io/badge/discussion-groups.io-blue.svg \"groups discussion\"\n[shield_twitter-follow]: https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter\u0026logoColor=white \"twitter follow\"\n\n[link_website]: https://cyclonedx.org/\n[link_npm]: https://www.npmjs.com/package/%40cyclonedx/cyclonedx-library\n\n[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-javascript-library/actions/workflows/nodejs.yml?query=branch%3Amain\n[link_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-javascript-library/dashboard\n[link_ossf-best-practices]: https://www.bestpractices.dev/projects/7883\n[link_slack]: https://cyclonedx.org/slack/invite\n[link_discussion]: https://groups.io/g/CycloneDX\n[link_twitter]: https://twitter.com/CycloneDX_Spec\n","funding_links":["https://owasp.org/donate/?reponame=www-project-cyclonedx\u0026title=OWASP+CycloneDX"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyclonedx%2Fcyclonedx-javascript-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyclonedx%2Fcyclonedx-javascript-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyclonedx%2Fcyclonedx-javascript-library/lists"}