✨ --include-metadata (metadata.tools)

- When provided, metadata.tools identifies this producer:
  - vendor: CycloneDX
  - name: cyclonedx-ruby
  - version: the gem’s version
- Emitted for both JSON and XML, and only when the selected spec supports metadata (>= 1.2).
- Help and README updated.

- features/metadata_tools.feature (integration)
- spec/cyclonedx/metadata_tools_spec.rb (unit, offline-safe)

Signed-off-by: Peter H. Boling <[email protected]>

Author: pboling

README.md

@@ -32,6 +32,7 @@ cyclonedx-ruby [options]
     `-o, --output bom_file_path` Path to output the bom file
     `-f, --format bom_output_format` Output format for bom. Supported: xml (default), json
     `-s, --spec-version version` CycloneDX spec version to target (default: 1.7). Supported: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
+    `--include-metadata` Include metadata.tools identifying cyclonedx-ruby as the producer
     `--validate` Validate the produced BOM against the selected CycloneDX schema
     `--validate-file PATH` Validate an existing BOM file instead of generating one
     `-h, --help` Show help message
@@ -40,6 +41,7 @@ cyclonedx-ruby [options]
 
 - By default, outputs conform to CycloneDX spec version 1.7.
 - To generate an older spec version, use `--spec-version`.
+- To embed metadata about this tool (vendor/name/version) into the BOM, pass `--include-metadata` (supported for spec >= 1.2).
 
 #### Examples
 ```bash
@@ -54,6 +56,9 @@ cyclonedx-ruby -p /path/to/ruby/project -s 1.3
 
 # JSON at CycloneDX 1.2 to a custom path
 cyclonedx-ruby -p /path/to/ruby/project -f json -s 1.2 -o bom/out.json
+
+# Include producer metadata and validate
+cyclonedx-ruby -p /path/to/ruby/project --include-metadata --validate
 ```
 
 

features/help.feature

@@ -15,5 +15,6 @@ Scenario: Generate help on demand
       -s, --spec-version version       (Optional) CycloneDX spec version to target (default: 1.7). Supported: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
           --validate                   Validate the produced BOM against the selected CycloneDX schema
           --validate-file PATH         Validate an existing BOM file instead of generating one
+          --include-metadata           Include metadata.tools identifying cyclonedx-ruby as the producer
       -h, --help                       Show help message
   """

features/metadata_tools.feature

@@ -0,0 +1,56 @@
+Feature: Include metadata.tools in BOM
+
+  Scenario: JSON output includes metadata.tools when flag is set
+    Given I use a fixture named "simple"
+    And I run `cyclonedx-ruby --path . --format json --include-metadata`
+    Then a file named "bom.json" should exist
+    And the output should contain:
+    """
+    5 gems were written to BOM located at ./bom.json
+    """
+    And the file "bom.json" should contain:
+    """
+    "metadata": {
+      "tools": [
+        {
+          "vendor": "CycloneDX",
+          "name": "cyclonedx-ruby"
+        }
+      ]
+    }
+    """
+
+  Scenario: JSON metadata BOM validates against schema
+    Given I use a fixture named "simple"
+    And I run `cyclonedx-ruby --path . --format json --include-metadata --validate`
+    Then the output should contain:
+    """
+    5 gems were written to BOM located at ./bom.json
+    """
+    And a file named "bom.json" should exist
+
+  Scenario: XML output includes metadata.tools when flag is set
+    Given I use a fixture named "simple"
+    And I run `cyclonedx-ruby --path . --format xml --include-metadata`
+    Then a file named "bom.xml" should exist
+    And the output should contain:
+    """
+    5 gems were written to BOM located at ./bom.xml
+    """
+    And the file "bom.xml" should contain:
+    """
+    <metadata>
+      <tools>
+        <tool>
+          <vendor>CycloneDX</vendor>
+          <name>cyclonedx-ruby</name>
+    """
+
+  Scenario: XML metadata BOM validates against schema
+    Given I use a fixture named "simple"
+    And I run `cyclonedx-ruby --path . --format xml --include-metadata --validate`
+    Then the output should contain:
+    """
+    5 gems were written to BOM located at ./bom.xml
+    """
+    And a file named "bom.xml" should exist

lib/cyclonedx/bom_builder.rb

@@ -31,7 +31,7 @@ def self.build(path)
       end
 
       specs_list
-      bom = build_bom(@gems, @bom_output_format, @spec_version)
+      bom = build_bom(@gems, @bom_output_format, @spec_version, include_metadata: @options[:include_metadata])
 
       begin
         @logger.info("Changing directory to the original working directory located at #{original_working_directory}")
@@ -106,6 +106,9 @@ def self.setup(path)
         opts.on('--validate-file PATH', 'Validate an existing BOM file instead of generating one') do |path|
           @options[:validate_file] = path
         end
+        opts.on('--include-metadata', 'Include metadata.tools identifying cyclonedx-ruby as the producer') do
+          @options[:include_metadata] = true
+        end
         opts.on_tail('-h', '--help', 'Show help message') do
           puts opts
           exit

lib/cyclonedx/bom_helpers.rb

@@ -23,6 +23,8 @@
 # Copyright (c) OWASP Foundation. All Rights Reserved.
 #
 
+require 'securerandom'
+
 require_relative 'bom_component'
 
 module Cyclonedx
@@ -41,15 +43,29 @@ def random_urn_uuid
       "urn:uuid:#{SecureRandom.uuid}"
     end
 
-    def build_bom(gems, format, spec_version)
+    # Determine if the selected spec version supports metadata/tools (>= 1.2)
+    def metadata_supported?(spec_version)
+      %w[1.2 1.3 1.4 1.5 1.6 1.7].include?(spec_version)
+    end
+
+    # Identity of this producer tool
+    def tool_identity
+      {
+        vendor: 'CycloneDX',
+        name: 'cyclonedx-ruby',
+        version: ::Cyclonedx::Ruby::Version::VERSION
+      }
+    end
+
+    def build_bom(gems, format, spec_version, include_metadata: false)
       if format == 'json'
-        build_json_bom(gems, spec_version)
+        build_json_bom(gems, spec_version, include_metadata: include_metadata)
       else
-        build_bom_xml(gems, spec_version)
+        build_bom_xml(gems, spec_version, include_metadata: include_metadata)
       end
     end
 
-    def build_json_bom(gems, spec_version)
+    def build_json_bom(gems, spec_version, include_metadata: false)
       bom_hash = {
         bomFormat: 'CycloneDX',
         specVersion: spec_version,
@@ -58,17 +74,39 @@ def build_json_bom(gems, spec_version)
         components: []
       }
 
+      # Optionally include metadata.tools when supported by selected spec
+      if include_metadata && metadata_supported?(spec_version)
+        ti = tool_identity
+        ti = ti.compact # omit nil values like version
+        bom_hash[:metadata] = {
+          tools: [ti]
+        }
+      end
+
       gems.each do |gem|
         bom_hash[:components] += Cyclonedx::BomComponent.new(gem).hash_val
       end
 
       JSON.pretty_generate(bom_hash)
     end
 
-    def build_bom_xml(gems, spec_version)
+    def build_bom_xml(gems, spec_version, include_metadata: false)
       builder = Nokogiri::XML::Builder.new(encoding: 'UTF-8') do |xml|
         attributes = { 'xmlns' => cyclonedx_xml_namespace(spec_version), 'version' => '1', 'serialNumber' => random_urn_uuid }
         xml.bom(attributes) do
+          # Optionally include metadata.tools when supported by selected spec
+          if include_metadata && metadata_supported?(spec_version)
+            xml.metadata do
+              xml.tools do
+                xml.tool do
+                  xml.vendor tool_identity[:vendor]
+                  xml.name tool_identity[:name]
+                  xml.version tool_identity[:version] if tool_identity[:version]
+                end
+              end
+            end
+          end
+
           xml.components do
             gems.each do |gem|
               xml.component('type' => 'library') do
@@ -165,7 +203,7 @@ def get_gem(name, version, logger)
       url = "https://rubygems.org/api/v1/versions/#{name}.json"
       begin
         RestClient.proxy = ENV.fetch('http_proxy', nil)
-        response = RestClient.get(url)
+        response = RestClient::Request.execute(method: :get, url: url, read_timeout: 2, open_timeout: 2)
         body = JSON.parse(response.body)
         body.select { |item| item['number'] == version.to_s }.first
       rescue StandardError

lib/cyclonedx/ruby.rb

@@ -15,9 +15,9 @@
 
 # This gem
 require_relative 'ruby/version'
-require_relative 'bom_helpers'
+require_relative 'bom_component' # no dependencies
+require_relative 'bom_helpers' # depends on bom_component
 require_relative 'bom_builder' # depends on bom_helpers
-require_relative 'bom_component'
 
 module Cyclonedx
   module Ruby

spec/cyclonedx/metadata_tools_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'nokogiri'
+require_relative '../../lib/cyclonedx/bom_helpers'
+require_relative '../../lib/cyclonedx/ruby/version'
+
+RSpec.describe 'metadata.tools emission' do
+  let(:spec_version) { '1.7' }
+
+  it 'adds metadata.tools in JSON when include_metadata is true and spec >= 1.2' do
+    json = Cyclonedx::BomHelpers.build_json_bom([], spec_version, include_metadata: true)
+    data = JSON.parse(json)
+    expect(data['metadata']).to be_a(Hash)
+    expect(data['metadata']['tools']).to be_a(Array)
+    expect(data['metadata']['tools'].first['vendor']).to eq('CycloneDX')
+    expect(data['metadata']['tools'].first['name']).to eq('cyclonedx-ruby')
+  end
+
+  it 'does not add metadata when include_metadata is false' do
+    json = Cyclonedx::BomHelpers.build_json_bom([], spec_version, include_metadata: false)
+    data = JSON.parse(json)
+    expect(data).not_to have_key('metadata')
+  end
+
+  it 'adds metadata.tools in XML when include_metadata is true and spec >= 1.2' do
+    xml = Cyclonedx::BomHelpers.build_bom_xml([], spec_version, include_metadata: true)
+    doc = Nokogiri::XML(xml)
+    ns = { 'c' => Cyclonedx::BomHelpers.cyclonedx_xml_namespace(spec_version) }
+    expect(doc.at_xpath('/c:bom/c:metadata/c:tools/c:tool/c:vendor', ns)&.text).to eq('CycloneDX')
+    expect(doc.at_xpath('/c:bom/c:metadata/c:tools/c:tool/c:name', ns)&.text).to eq('cyclonedx-ruby')
+  end
+
+  it 'omits metadata in XML when flag is false' do
+    xml = Cyclonedx::BomHelpers.build_bom_xml([], spec_version, include_metadata: false)
+    doc = Nokogiri::XML(xml)
+    ns = { 'c' => Cyclonedx::BomHelpers.cyclonedx_xml_namespace(spec_version) }
+    expect(doc.at_xpath('/c:bom/c:metadata', ns)).to be_nil
+  end
+end
+