Add support for testing extensions

Allows extensions to provide functionality that lets administrators verify whether a given configuration is likely to work.

The primary use case here being a "test" button in the UI.

Having an easy way to test configuration provides much better UX, as the lack of feedback without it can cause a lot of frustration. Especially when the to-be-configured functionality only runs on schedule and can't be triggered manually at all.

Signed-off-by: nscuro <nscuro@protonmail.com>

Author: nscuro

api/src/main/openapi/components/schemas/extensions/extension-test-check-status.yaml

@@ -0,0 +1,21 @@
+# 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.
+type: string
+enum:
+- PASSED
+- FAILED
+- SKIPPED

api/src/main/openapi/components/schemas/extensions/extension-test-check.yaml

@@ -0,0 +1,31 @@
+# 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.
+type: object
+properties:
+  name:
+    type: string
+    example: "connection"
+  status:
+    $ref: "./extension-test-check-status.yaml"
+  message:
+    type: string
+    example: "Connection failed"
+  detail:
+    type: string
+required:
+- name
+- status

api/src/main/openapi/components/schemas/extensions/test-extension-request.yaml

@@ -0,0 +1,21 @@
+# 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.
+type: object
+properties:
+  config:
+    type: object
+    additionalProperties: true

api/src/main/openapi/components/schemas/extensions/test-extension-response.yaml

@@ -0,0 +1,24 @@
+# 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.
+type: object
+properties:
+  checks:
+    type: array
+    items:
+      $ref: "./extension-test-check.yaml"
+required:
+- checks

api/src/main/openapi/openapi.yaml

@@ -130,6 +130,8 @@ paths:
     $ref: "./paths/extension-points__name__extensions__name__config.yaml"
   /extension-points/{extensionPointName}/extensions/{extensionName}/config-schema:
     $ref: "./paths/extension-points__name__extensions__name__config-schema.yaml"
+  /extension-points/{extensionPointName}/extensions/{extensionName}/test:
+    $ref: "./paths/extension-points__name__extensions__name__test.yaml"
   /metrics/portfolio/current:
     $ref: "./paths/metrics_portfolio_current.yaml"
   /metrics/vulnerabilities:

api/src/main/openapi/paths/components.yaml

@@ -34,7 +34,7 @@ post:
       content:
         application/problem+json:
           schema:
-            oneOf:
+            anyOf:
               - $ref: "../components/schemas/invalid-request-problem-details.yaml"
               - $ref: "../components/schemas/problem-details.yaml"
     "401":

api/src/main/openapi/paths/extension-points__name__extensions__name__config.yaml

@@ -58,6 +58,10 @@ put:
   description: |-
     Updates the configuration of an extension.
     
+    **Do not use clear text credentials in the supplied config**.
+    Fields annotated with `x-secret-ref` in the config schema expect
+    a name of a managed secret, which is resolved internally by the API.
+    
     Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_READ` permission.
   tags:
   - Extensions

api/src/main/openapi/paths/extension-points__name__extensions__name__test.yaml

@@ -0,0 +1,79 @@
+# 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: testExtension
+  summary: Test extension
+  description: |-
+    Tests an extension.
+    
+    If the extension is configurable (i.e. `/config-schema` returns status `200`),
+    a valid configuration **must** be provided in the test request.
+    The configuration is validated against the applicable JSON schema.
+    
+    **Do not use clear text credentials in the supplied config**.
+    Fields annotated with `x-secret-ref` in the config schema expect
+    a name of a managed secret, which is resolved internally by the API.
+    
+    Test results contain one or more checks, each of which can have a status of
+    `PASSED`, `FAILED`, or `SKIPPED`. If *at least one* check is `FAILED`,
+    the entire test should be considered `FAILED`.
+    
+    Requires the `SYSTEM_CONFIGURATION` or `SYSTEM_CONFIGURATION_UPDATE` permission.
+  tags:
+  - Extensions
+  parameters:
+  - name: extensionPointName
+    description: Name of the extension point
+    in: path
+    required: true
+    schema:
+      type: string
+  - name: extensionName
+    description: Name of the extension
+    in: path
+    required: true
+    schema:
+      type: string
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: "../components/schemas/extensions/test-extension-request.yaml"
+  responses:
+    "200":
+      description: Test result
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/extensions/test-extension-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"

api/src/main/openapi/paths/secrets.yaml

@@ -73,7 +73,7 @@ post:
       content:
         application/problem+json:
           schema:
-            oneOf:
+            anyOf:
             - $ref: "../components/schemas/invalid-request-problem-details.yaml"
             - $ref: "../components/schemas/problem-details.yaml"
     "401":

api/src/main/openapi/paths/secrets__name_.yaml

@@ -81,7 +81,7 @@ patch:
       content:
         application/problem+json:
           schema:
-            oneOf:
+            anyOf:
             - $ref: "../components/schemas/invalid-request-problem-details.yaml"
             - $ref: "../components/schemas/problem-details.yaml"
     "401":
@@ -120,7 +120,7 @@ delete:
       content:
         application/problem+json:
           schema:
-            oneOf:
+            anyOf:
             - $ref: "../components/schemas/invalid-request-problem-details.yaml"
             - $ref: "../components/schemas/problem-details.yaml"
     "401":