Toolクラスの非推奨について

[KAWAHARA-souta]

related to #1

cyclonedx/model/tool.py内において，Toolクラスは以下のように宣言され，またコメントがかかれている．

 39 @serializable.serializable_class                                              
 40 class Tool:                                                                   
 41     """                                                                       
 42     This is our internal representation of the `toolType` complex type within the CycloneDX standard.     
 43                                                                                                   
 44     Tool(s) are the things used in the creation of the CycloneDX document.                                                                           
 45                                                                                                                                                    
 46     Tool might be deprecated since CycloneDX 1.5, but it is not deprecated in this library.             
 47     In fact, this library will try to provide a compatibility layer if needed.
 48                                                                                                                                                      
 49     .. note::                                                                 
 50         See the CycloneDX Schema for toolType: https://cyclonedx.org/docs/1.6/#type_toolType

コメントには，Toolクラスはcyclonedx1.5でdeprecatedされているようであるとかかれている．
これが本当であるかの事実確認．およびなんらかのコードの修正が必要な場合には具体的にどうすべきかを調査する．

[KAWAHARA-souta]

まずコメントにも書いてあるとおり，Toolクラスはcyclonedxのstandardにおける toolType の実装であることに注意する必要がある．

この上でこのデータの仕様は https://cyclonedx.org/docs/1.6/xml/#type_toolType に記載されており，また例えばxmlでそのデータの表現(Serialize?)は，xmlのスキーマ(xsd)である https://cyclonedx.org/schema/bom-1.6.xsd を確認する必要がある．

後のコメントではこれらのドキュメントをもとに議論をするため留意する．

[KAWAHARA-souta]

https://cyclonedx.org/schema/bom-1.6.xsd より，toolTypeの扱いについて確認する．

metadataはトップ直下にある

  <xs:complexType name="metadata">
    <xs:sequence minOccurs="0" maxOccurs="1">
      <xs:element name="timestamp" type="xs:dateTime" minOccurs="0">
        ...
      </xs:element>
      <xs:element name="lifecycles" minOccurs="0" maxOccurs="1">
        ...
      </xs:element>
      <xs:element name="tools" minOccurs="0" maxOccurs="1">
        <xs:annotation>
          <xs:documentation>The tool(s) used in the creation of the BOM.</xs:documentation>
        </xs:annotation>
        <xs:complexType>
          <xs:choice>
            <xs:sequence minOccurs="0" maxOccurs="unbounded">
              <xs:element name="tool" minOccurs="0" type="bom:toolType">
                <xs:annotation>
                  <xs:documentation>DEPRECATED. Use tools\components or tools\services instead.</xs:documentation>
                </xs:annotation>
              </xs:element>
            </xs:sequence>
            <xs:sequence minOccurs="0" maxOccurs="1">
              <xs:element name="components" type="bom:componentsType" minOccurs="0" maxOccurs="1">
                <xs:annotation>
                  <xs:documentation>A list of software and hardware components used as tools.</xs:documentation>
                </xs:annotation>
              </xs:element>
              <xs:element name="services" type="bom:servicesType" minOccurs="0" maxOccurs="1">
                <xs:annotation>
                  <xs:documentation>A list of services used as tools.</xs:documentation>
                </xs:annotation>
              </xs:element>
            </xs:sequence>
          </xs:choice>
        </xs:complexType>
      </xs:element>

metadata配下にtoolsという名前があり，古くはToolクラスの要素をこの配下にぶら下げていくが，これはDEPRECATEDになっている．
これに並列してchoiceで並んでcomponentsとservicesがある．ツールをcomponentのリストもしくはserviceのリストにしてぶら下げるのだと思う．(servicesの場合はSAASとかなのかな?)
ちなみにこれはalma-sbomでも1.6対応の時にこの対処をしたはず．Toolはcomponentsに置き換えた記憶がある．

[KAWAHARA-souta]

https://cyclonedx.org/schema/bom-1.6.xsd より，もう少ししたにはtoolTypeの定義がされているので一応記載

    <xs:complexType name="toolType">
      <xs:annotation>
        <xs:documentation>Information about the automated or manual tool used</xs:documentation>
      </xs:annotation>
      <xs:sequence minOccurs="0" maxOccurs="1">
        <xs:element name="vendor" minOccurs="0" maxOccurs="1" type="xs:normalizedString">
          <xs:annotation>
            <xs:documentation>The name of the vendor who created the tool</xs:documentation>
          </xs:annotation>
        </xs:element>
        <xs:element name="name" minOccurs="0" maxOccurs="1" type="xs:normalizedString">
          <xs:annotation>
            <xs:documentation>The name of the tool</xs:documentation>
          </xs:annotation>
        </xs:element>
        <xs:element name="version" minOccurs="0" maxOccurs="1" type="bom:versionType">
          <xs:annotation>
            <xs:documentation>The version of the tool</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="externalReferences" type="bom:externalReferences" minOccurs="0" maxOccurs="1">
          <xs:annotation>
            <xs:documentation>Provides the ability to document external references related to the tool.</xs:documentation>
          </xs:annotation>
        </xs:element>
        <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded">
          <xs:annotation>
            <xs:documentation> Allows any undeclared elements as long as the elements are placed in a different namespace.</xs:documentation>
          </xs:annotation>
        </xs:any>
      </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>

[KAWAHARA-souta]

長くなるので詳細は載せないが，さらに https://cyclonedx.org/schema/bom-1.6.xsd より，
VulnerabilityType(vulnerabiliesType配下のvulnerability)の定義配下にもtools elementがあり，先ほどと同じようにtoolTypeが要素としてあって，同じようなdeprecatedの構図だった．

[KAWAHARA-souta]

ソースコード内で一つ発見があった．

cyclonedx/model/tool.py より

196 class ToolRepository:                                                              
197     """                                                                            
198     The repository of tool formats                                                 
199     """                                                                            
200                                                                                    
201     def __init__(                                                                  
202         self, *,                                                                   
203         components: Optional[Iterable[Component]] = None,                          
204         services: Optional[Iterable[Service]] = None,                              
205         # Deprecated since v1.5                                                    
206         tools: Optional[Iterable[Tool]] = None                                     
207     ) -> None:                                                                     
208         if tools:                                                                  
209             warn('`@.tools` is deprecated from CycloneDX v1.5 onwards. '           
210                  'Please use `@.components` and `@.services` instead.',            
211                  DeprecationWarning)                                               
212         self.components = components or ()  # type:ignore[assignment]              
213         self.services = services or ()  # type:ignore[assignment]                  
214         self.tools = tools or ()  # type:ignore[assignment]

ここも先ほどの内容に関係するところ．
たしかにtoolsがdeprecatedなwarningがすでに実装されている．