components.yaml

# This file is part of Dependency-Track.
#
# 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.
post:
  operationId: createComponent
  summary: Creates a new component for the project
  description: Requires permission <strong>PORTFOLIO_MANAGEMENT</strong> or <strong>PORTFOLIO_MANAGEMENT_UPDATE</strong>
  tags:
    - Components
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: "../components/schemas/create-component-request.yaml"
  responses:
    "201":
      description: Component Created
    "400":
      description: Bad Request
      content:
        application/problem+json:
          schema:
            anyOf:
              - $ref: "../components/schemas/invalid-request-problem-details.yaml"
              - $ref: "../components/schemas/problem-details.yaml"
    "401":
      $ref: "../components/responses/generic-unauthorized-error.yaml"
    "403":
      $ref: "../components/responses/generic-forbidden-error.yaml"
    "409":
      $ref: "../components/responses/generic-conflict-error.yaml"
    default:
      $ref: "../components/responses/generic-error.yaml"

get:
  operationId: listComponents
  summary: List all components
  description: |-
    Retrieves a list of all components that have the specified component identity. This resource accepts coordinates (group, name, version) , `purl`, `cpe`, `swidTagId`, `project_uuid`, or `hash`.
    
    ### Sortable fields
    
    Sorting is supported for the following fields:
    
    * `name`
    * `version`
    * `group`
    * `purl`
    * `cpe`
    * `swid_tag_id`
    * `last_inherited_risk_score`
    
    Requires permission <strong>VIEW_PORTFOLIO</strong>
  tags:
    - Components
  parameters:
    - name: project_uuid
      in: query
      description: The UUID of the project to retrieve components for
      schema:
        type: string
        format: uuid
    - name: group
      in: query
      description: The group of the component
      schema:
        type: string
    - name: name
      in: query
      description: The name of the component
      schema:
        type: string
    - name: version
      in: query
      description: The version of the component
      schema:
        type: string
    - name: purl
      in: query
      description: The PURL of the component
      schema:
        type: string
    - name: cpe
      in: query
      description: The CPE of the component
      schema:
        type: string
    - name: swid_tag_id
      in: query
      description: The SWID Tag ID of the component
      schema:
        type: string
    - name: hash_type
      in: query
      description: The MD5, SHA1, SHA_256, SHA_384, SHA_512, SHA3_256, SHA3_384, SHA3_512, BLAKE2B_256, BLAKE2B_384, BLAKE2B_512, or BLAKE3 hash type of the component
      schema:
        type: string
        enum:
          - MD5
          - SHA1
          - SHA_256
          - SHA_384
          - SHA_512
          - SHA3_256
          - SHA3_384
          - SHA3_512
          - BLAKE2B_256
          - BLAKE2B_384
          - BLAKE2B_512
          - BLAKE3
    - name: hash
      in: query
      description: The hash value of the component
      schema:
        type: string
    - $ref: "../components/parameters/pagination-limit.yaml"
    - $ref: "../components/parameters/page-token.yaml"
    - $ref: "../components/parameters/sort-direction.yaml"
    - $ref: "../components/parameters/sort-by.yaml"
  responses:
    "200":
      description: A list of all components for a given identity
      content:
        application/json:
          schema:
            $ref: "../components/schemas/list-components-response.yaml"
    "400":
      description: Bad Request
      content:
        application/problem+json:
          schema:
            anyOf:
              - $ref: "../components/schemas/json-schema-validation-problem-details.yaml"
              - $ref: "../components/schemas/problem-details.yaml"
    "401":
      $ref: "../components/responses/generic-unauthorized-error.yaml"
    "403":
      $ref: "../components/responses/generic-forbidden-error.yaml"
    "404":
      $ref: "../components/responses/generic-not-found-error.yaml"
    default:
      $ref: "../components/responses/generic-error.yaml"