@cyclonedx/cyclonedx-library 1.0.0-beta.1

package/libs/universal-node-xml/index.d.ts

@@ -0,0 +1,33 @@
+/*!
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+*/
+
+import { SimpleXml } from '../../src/serialize/xml/types'
+import { SerializerOptions } from '../../src/serialize/types'
+
+declare type ThrowError = () => never
+
+declare type Stringify = (element: SimpleXml.Element, options?: SerializerOptions) => string
+export declare const stringify: Stringify | undefined
+export declare const stringifyFallback: Stringify | ThrowError
+
+/*
+declare type Parse = (xml: string) => SimpleXml.Element
+export declare const parse: Parse | undefined
+export declare const parseFallback: Parse | ThrowError
+*/

package/libs/universal-node-xml/index.js

@@ -0,0 +1,42 @@
+'use strict'
+/*!
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+*/
+
+const possibleStringifiers = [
+  // prioritized list of possible implementations
+  'xmlbuilder2'
+]
+
+module.exports.stringify = undefined
+let possibleStringifier
+for (const file of possibleStringifiers) {
+  try {
+    possibleStringifier = require(`./stringifiers/${file}`)
+    if (typeof possibleStringifier === 'function') {
+      module.exports.stringify = possibleStringifier
+      break
+    }
+  } catch {
+    /* pass */
+  }
+}
+
+module.exports.stringifyFallback = module.exports.stringify ?? function () {
+  throw new Error('No stringifier available. Please install one of the optional xml libraries.')
+}

package/libs/universal-node-xml/stringifiers/helpers.js

@@ -0,0 +1,17 @@
+
+module.exports.getNS = function (element) {
+  const ns = (element.namespace ?? element.attributes?.xmlns)?.toString() ?? ''
+  return ns.length > 0
+    ? ns
+    : null
+}
+
+module.exports.makeIndent = function (space) {
+  if (typeof space === 'number') {
+    return ' '.repeat(Math.max(0, space))
+  }
+  if (typeof space === 'string') {
+    return space
+  }
+  return ''
+}

package/libs/universal-node-xml/stringifiers/xmlbuilder2.js

@@ -0,0 +1,51 @@
+'use strict'
+/*!
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+*/
+
+const { create } = require('xmlbuilder2')
+const { getNS, makeIndent } = require('./helpers')
+
+module.exports = typeof create === 'function'
+  ? stringify
+  : undefined
+
+function stringify (element, { space } = {}) {
+  const indent = makeIndent(space)
+  const doc = create({ encoding: 'UTF-8' })
+  addEle(doc, element)
+  return doc.end({
+    format: 'xml',
+    newline: '\n',
+    prettyPrint: indent.length > 0,
+    indent
+  })
+}
+
+function addEle (parent, element, parentNS = null) {
+  if (element.type !== 'element') { return }
+  const ns = getNS(element) ?? parentNS
+  const ele = parent.ele(ns, element.name, element.attributes)
+  if (typeof element.children === 'string' || typeof element.children === 'number') {
+    ele.txt(element.children.toString())
+  } else if (Array.isArray(element.children)) {
+    for (const child of element.children) {
+      addEle(ele, child, ns)
+    }
+  }
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@cyclonedx/cyclonedx-library",
+  "version": "1.0.0-beta.1",
+  "description": "Core functionality of CycloneDX for JavaScript (Node.js or WebBrowser).",
+  "keywords": [
+    "CycloneDX",
+    "SBOM",
+    "BOM",
+    "inventory",
+    "bill-of-materials",
+    "software-bill-of-materials",
+    "component",
+    "dependency",
+    "package-url",
+    "PURL",
+    "spdx"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CycloneDX/cyclonedx-javascript-library"
+  },
+  "bugs": {
+    "url": "https://github.com/CycloneDX/cyclonedx-javascript-library/issues"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Jan Kowalleck",
+    "email": "jan.kowalleck@gmail.com"
+  },
+  "contributors": [
+    {
+      "name": "Jan Kowalleck",
+      "email": "jan.kowalleck@gmail.com"
+    }
+  ],
+  "type": "commonjs",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "packageurl-js": "^0.0.6"
+  },
+  "optionalDependencies": {
+    "xmlbuilder2": "^3.0.2"
+  },
+  "devDependencies": {
+    "@types/mocha": "^9.1.1",
+    "@types/node": "^17.0.39",
+    "@types/webpack": "^5.28.0",
+    "deepmerge": "4.2.2",
+    "mocha": "10.0.0",
+    "npm-run-all": "^4.1.5",
+    "ts-loader": "9.3.0",
+    "ts-standard": "^11.0.0",
+    "typescript": "4.6.4",
+    "webpack": "5.73.0",
+    "webpack-cli": "4.9.2",
+    "xmlbuilder2": "^3.0.2"
+  },
+  "browser": "./dist.web/lib.js",
+  "types": "./src/_index.node.ts",
+  "main": "./dist.node/_index.node.js",
+  "exports": "./dist.node/_index.node.js",
+  "directories": {
+    "doc": "./docs",
+    "src": "./src",
+    "lib": "./dist.node",
+    "test": "./tests",
+    "example": "./examples"
+  },
+  "scripts": {
+    "prepublish": "npm run build",
+    "prepublishOnly": "npm run build",
+    "lint": "tsc --noEmit",
+    "build": "run-p --aggregate-output -l build:*",
+    "prebuild:node": "node -r fs -e 'fs.rmSync(\"dist.node\",{recursive:true,force:true})'",
+    "build:node": "tsc -b ./tsconfig.node.json",
+    "prebuild:web": "node -r fs -e 'fs.rmSync(\"dist.web\",{recursive:true,force:true})'",
+    "build:web": "webpack",
+    "cs-fix": "eslint --fix .",
+    "test": "run-p --aggregate-output -lc test:*",
+    "test:node": "mocha -p",
+    "test:web": "node -e 'console.log(\"TODO: write web test\")'",
+    "test:standard": "eslint ."
+  }
+}

package/res/README.md

@@ -0,0 +1,27 @@
+# Resources
+
+These resources are shipped with the library.
+
+## Schema files
+
+some schema for offline use.  
+original sources: https://github.com/CycloneDX/specification/tree/master/schema
+
+Currently using version
+[82bf9e30ba3fd6413e72a0e66adce2cdf3354f32](https://github.com/CycloneDX/specification/tree/82bf9e30ba3fd6413e72a0e66adce2cdf3354f32)
+
+| file                                                                         | note |
+| ---  | --- |
+| [`bom-1.0.SNAPSHOT.xsd`](bom-1.0.SNAPSHOT.xsd)                               | `http://cyclonedx.org/schema/spdx` was replaced with `spdx.SNAPSHOT.xsd` |
+| [`bom-1.1.SNAPSHOT.xsd`](bom-1.1.SNAPSHOT.xsd)                               | `http://cyclonedx.org/schema/spdx` was replaced with `spdx.SNAPSHOT.xsd` |
+| [`bom-1.2.SNAPSHOT.xsd`](bom-1.2.SNAPSHOT.xsd)                               | `http://cyclonedx.org/schema/spdx` was replaced with `spdx.SNAPSHOT.xsd` |
+| [`bom-1.3.SNAPSHOT.xsd`](bom-1.3.SNAPSHOT.xsd)                               | `http://cyclonedx.org/schema/spdx` was replaced with `spdx.SNAPSHOT.xsd` |
+| [`bom-1.4.SNAPSHOT.xsd`](bom-1.4.SNAPSHOT.xsd)                               | `http://cyclonedx.org/schema/spdx` was replaced with `spdx.SNAPSHOT.xsd` |
+| [`bom-1.2.SNAPSHOT.schema.json`](bom-1.2.SNAPSHOT.schema.json)               | `spdx.schema.json` was replaced with `spdx.SNAPSHOT.schema.json` |
+| [`bom-1.3.SNAPSHOT.schema.json`](bom-1.3.SNAPSHOT.schema.json)               | `spdx.schema.json` was replaced with `spdx.SNAPSHOT.schema.json` |
+| [`bom-1.4.SNAPSHOT.schema.json`](bom-1.4.SNAPSHOT.schema.json)               | `spdx.schema.json` was replaced with `spdx.SNAPSHOT.schema.json` |
+| [`bom-1.2-strict.SNAPSHOT.schema.json`](bom-1.2-strict.SNAPSHOT.schema.json) | `spdx.schema.json` was replaced with `spdx.SNAPSHOT.schema.json` |
+| [`bom-1.3-strict.SNAPSHOT.schema.json`](bom-1.3-strict.SNAPSHOT.schema.json) | `spdx.schema.json` was replaced with `spdx.SNAPSHOT.schema.json` |
+| [`spdx.SNAPSHOT.xsd`](spdx.SNAPSHOT.xsd)                                     | |
+| [`spdx.SNAPSHOT.schema.json`](spdx.SNAPSHOT.schema.json)                     | |
+| [`jsf-0.82.SNAPSHOT.schema.json`](jsf-0.82.SNAPSHOT.schema.json) | |

package/res/bom-1.0.SNAPSHOT.xsd

@@ -0,0 +1,247 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning"
+           xmlns:bom="http://cyclonedx.org/schema/bom/1.0"
+           xmlns:spdx="http://cyclonedx.org/schema/spdx"
+           elementFormDefault="qualified"
+           targetNamespace="http://cyclonedx.org/schema/bom/1.0"
+           vc:minVersion="1.0"
+           vc:maxVersion="1.1"
+           version="1.0.1">
+
+    <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.SNAPSHOT.xsd"/>
+
+    <xs:complexType name="component">
+        <xs:sequence>
+            <xs:element name="publisher" type="xs:normalizedString" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>The person(s) or organization(s) that published the component</xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="group" type="xs:normalizedString" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>The grouping name or identifier. This will often be a shortened, single
+                        name of the company or project that produced the component, or the source package or
+                        domain name. Whitespace and special characters should be avoided. Examples include:
+                        apache, org.apache.commons, and apache.org.</xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="name" type="xs:normalizedString" minOccurs="1" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>The name of the component. This will often be a shortened, single name
+                        of the component. Examples: commons-lang3 and jquery</xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="version" type="xs:normalizedString" minOccurs="1" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>The component version. The version should ideally comply with semantic versioning
+                    but is not enforced.</xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="description" type="xs:normalizedString" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>Specifies a description for the component</xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="scope" type="bom:scope" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>Specifies the scope of the component. If scope is not specified, 'runtime'
+                    scope will be assumed.</xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="hashes" minOccurs="0" maxOccurs="1">
+                <xs:complexType>
+                    <xs:sequence minOccurs="0" maxOccurs="unbounded">
+                        <xs:element name="hash" type="bom:hashType"/>
+                    </xs:sequence>
+                </xs:complexType>
+            </xs:element>
+            <xs:element name="licenses" minOccurs="0" maxOccurs="1">
+                <xs:complexType>
+                    <xs:sequence minOccurs="1" maxOccurs="unbounded">
+                        <xs:element name="license">
+                            <xs:complexType>
+                                <xs:sequence>
+                                    <xs:choice>
+                                        <xs:element name="id" type="spdx:licenseId" minOccurs="0" maxOccurs="unbounded">
+                                            <xs:annotation>
+                                                <xs:documentation>A valid SPDX license ID</xs:documentation>
+                                            </xs:annotation>
+                                        </xs:element>
+                                        <xs:element name="name" type="xs:normalizedString" minOccurs="0" maxOccurs="unbounded">
+                                            <xs:annotation>
+                                                <xs:documentation>If SPDX does not define the license used, this field may be used to provide the license name</xs:documentation>
+                                            </xs:annotation>
+                                        </xs:element>
+                                    </xs:choice>
+                                </xs:sequence>
+                            </xs:complexType>
+                        </xs:element>
+                    </xs:sequence>
+                </xs:complexType>
+            </xs:element>
+            <xs:element name="copyright" type="xs:normalizedString" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>An optional copyright notice informing users of the underlying claims to copyright ownership in a published work.</xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="cpe" type="bom:cpe" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>Specifies a well-formed CPE name. See https://nvd.nist.gov/products/cpe</xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="purl" type="xs:anyURI" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>
+                        Specifies the package-url (PURL). The purl, if specified, must be valid and conform
+                        to the specification defined at: https://github.com/package-url/purl-spec
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="modified" type="xs:boolean" minOccurs="1" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>
+                        A boolean value indicating is the component has been modified from the original.
+                        A value of true indicates the component is a derivative of the original.
+                        A value of false indicates the component has not been modified from the original.
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="components" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>
+                        Specifies optional sub-components. This is not a dependency tree. It simply provides
+                        an optional way to group large sets of components together.
+                    </xs:documentation>
+                </xs:annotation>
+                <xs:complexType>
+                    <xs:sequence minOccurs="0" maxOccurs="unbounded">
+                        <xs:element name="component" type="bom:component"/>
+                    </xs:sequence>
+                </xs:complexType>
+            </xs:element>
+        </xs:sequence>
+        <xs:attribute name="type" type="bom:classification" use="required">
+            <xs:annotation>
+                <xs:documentation>
+                    Specifies the type of component. Software applications, libraries, frameworks, and
+                    other dependencies should be classified as 'application'.
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
+        <xs:anyAttribute namespace="##other" processContents="lax">
+            <xs:annotation>
+                <xs:documentation>User-defined attributes may be used on this element as long as they
+                    do not have the same name as an existing attribute used by the schema.</xs:documentation>
+            </xs:annotation>
+        </xs:anyAttribute>
+    </xs:complexType>
+
+    <xs:complexType name="hashType">
+        <xs:annotation>
+            <xs:documentation>Specifies the file hash of the component</xs:documentation>
+        </xs:annotation>
+        <xs:simpleContent>
+            <xs:extension base="bom:hashValue">
+                <xs:attribute name="alg" type="bom:hashAlg" use="required">
+                    <xs:annotation>
+                        <xs:documentation>Specifies the algorithm used to create hash</xs:documentation>
+                    </xs:annotation>
+                </xs:attribute>
+            </xs:extension>
+        </xs:simpleContent>
+    </xs:complexType>
+
+    <xs:simpleType name="scope">
+        <xs:restriction base="xs:string">
+            <xs:enumeration value="required">
+                <xs:annotation>
+                    <xs:documentation>The component is required for runtime</xs:documentation>
+                </xs:annotation>
+            </xs:enumeration>
+            <xs:enumeration value="optional">
+                <xs:annotation>
+                    <xs:documentation>The component is optional at runtime. Optional components are components that
+                    are not capable of being called due to them not be installed or otherwise accessible by any means.
+                    Components that are installed but due to configuration or other restrictions are prohibited from
+                    being called must be scoped as 'required'.</xs:documentation>
+                </xs:annotation>
+            </xs:enumeration>
+        </xs:restriction>
+    </xs:simpleType>
+
+    <xs:simpleType name="classification">
+        <xs:restriction base="xs:string">
+            <xs:enumeration value="application"/>
+            <xs:enumeration value="framework"/>
+            <xs:enumeration value="library"/>
+            <xs:enumeration value="operating-system"/>
+            <xs:enumeration value="device"/>
+        </xs:restriction>
+    </xs:simpleType>
+
+    <xs:simpleType name="hashAlg">
+        <xs:restriction base="xs:string">
+            <xs:enumeration value="MD5"/>
+            <xs:enumeration value="SHA-1"/>
+            <xs:enumeration value="SHA-256"/>
+            <xs:enumeration value="SHA-384"/>
+            <xs:enumeration value="SHA-512"/>
+            <xs:enumeration value="SHA3-256"/>
+            <xs:enumeration value="SHA3-512"/>
+        </xs:restriction>
+    </xs:simpleType>
+    
+    <xs:simpleType name="hashValue">
+        <xs:restriction base="xs:token">
+            <xs:pattern value="([a-fA-F0-9]{32})|([a-fA-F0-9]{40})|([a-fA-F0-9]{64})|([a-fA-F0-9]{96})|([a-fA-F0-9]{128})"/>
+        </xs:restriction>
+    </xs:simpleType>
+    
+    <xs:simpleType name="cpe">
+        <xs:annotation>
+            <xs:documentation xml:lang="en">
+                Define the format for acceptable CPE URIs. Supports CPE 2.2 and CPE 2.3 formats. Refer to https://nvd.nist.gov/products/cpe for official specification.
+            </xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="xs:string">
+            <xs:pattern value="([c][pP][eE]:/[AHOaho]?(:[A-Za-z0-9\._\-~%]*){0,6})|(cpe:2\.3:[aho\*\-](:(((\?*|\*?)([a-zA-Z0-9\-\._]|(\\[\\\*\?!&quot;#$$%&amp;'\(\)\+,/:;&lt;=&gt;@\[\]\^`\{\|}~]))+(\?*|\*?))|[\*\-])){5}(:(([a-zA-Z]{2,3}(-([a-zA-Z]{2}|[0-9]{3}))?)|[\*\-]))(:(((\?*|\*?)([a-zA-Z0-9\-\._]|(\\[\\\*\?!&quot;#$$%&amp;'\(\)\+,/:;&lt;=&gt;@\[\]\^`\{\|}~]))+(\?*|\*?))|[\*\-])){4})"/>
+        </xs:restriction>
+    </xs:simpleType>
+
+    <xs:element name="bom">
+        <xs:complexType>
+            <xs:sequence>
+                <xs:element name="components">
+                    <xs:complexType>
+                        <xs:sequence minOccurs="0" maxOccurs="unbounded">
+                            <xs:element name="component" type="bom:component"/>
+                        </xs:sequence>
+                        <xs:anyAttribute namespace="##other" processContents="lax">
+                            <xs:annotation>
+                                <xs:documentation>User-defined attributes may be used on this element as long as they
+                                    do not have the same name as an existing attribute used by the schema.</xs:documentation>
+                            </xs:annotation>
+                        </xs:anyAttribute>
+                    </xs:complexType>
+                </xs:element>
+            </xs:sequence>
+            <xs:attribute name="version" type="xs:integer" default="1">
+                <xs:annotation>
+                    <xs:documentation>The version allows component publishers/authors to make changes to existing
+                    BOMs to update various aspects of the document such as description or licenses. When a system
+                    is presented with multiiple BOMs for the same component, the system should use the most recent
+                    version of the BOM. The default version is '1' and should be incremented for each version of the
+                    BOM that is published. Each version of a component should have a unique BOM and if no changes are
+                    made to the BOMs, then each BOM will have a version of '1'.</xs:documentation>
+                </xs:annotation>
+            </xs:attribute>
+            <xs:anyAttribute namespace="##other" processContents="lax">
+                <xs:annotation>
+                    <xs:documentation>User-defined attributes may be used on this element as long as they
+                        do not have the same name as an existing attribute used by the schema.</xs:documentation>
+                </xs:annotation>
+            </xs:anyAttribute>
+        </xs:complexType>
+    </xs:element>
+</xs:schema>