feat: Support running Debricked scan & publish results to SSC (#705)

fcli-core/fcli-action/src/main/resources/com/fortify/cli/generic_action/actions/build-time/ci-envvars.yaml

@@ -190,11 +190,16 @@ formatters:
         desc: >-
             ScanCentral SAST Client Authentication Token for authenticating with ScanCentral SAST Controller. This 
             environment variable is required when running a ScanCentral SAST scan.
-      # TODO Add DEBRICKED_TOKEN once implemented
       - names: SSC_LOGIN_EXTRA_OPTS
         desc: >-
             Extra SSC login options, for example for disabling SSL checks or changing connection time-outs; 
-            see `fcli ssc session login` documentation.        
+            see `fcli ssc session login` documentation.
+      - names: DEBRICKED_ACCESS_TOKEN
+        desc: >-
+            Authentication token required to access Debricked (OpenText Core SCA) services. It must be set in 
+            the environment when running a Debricked scan or integrating the Debricked CLI into your CI/CD pipeline. 
+            The value should be an access token generated from your Debricked account, and it is necessary for all 
+            authentication and API requests during vulnerability scans or compliance checks.
     preScan:
       - names: SSC_APPVERSION
         desc: >-
@@ -208,10 +213,19 @@ formatters:
           environment variable.\n\nDepending on your Git workflow, it is recommended to copy state from the
           application version representing your default branch by passing the `--copy-from` option through
           `SETUP_EXTRA_OPTS`.
+      - names: DEBRICKED_CLI_VERSION
+        desc: >-
+            Debricked CLI tool version to be installed to perform the debricked scan.
+      - names: REPOSITORY_NAME
+        desc: >-
+            Debricked repository name or ID.
+      - names: BRANCH_NAME
+        desc: >-
+            Debricked branch name or ID.
     scan:
       - names: DO_SAST_SCAN\nSAST_SCAN_EXTRA_OPTS
         desc: >-
-          The fcli `ci` action currently only supports running a SAST scan, which is enabled by default.
+          The fcli `ci` action supports running a SAST scan, which is enabled by default.
           The `SAST_SCAN_EXTRA_OPTS` environment variable can be used to provide additional options to
           the `fcli sc-sast scan start` command, for example to request a scan completion email notification.
           Note that these environment variables only control the submission of the scan request; see the
@@ -222,6 +236,17 @@ formatters:
           overridden by setting `DO_SAST_WAIT` to `false`, but note that doing so will skip any post-scan
           tasks. The `SAST_WAIT_EXTRA_OPTS` environment variable can be used to pass extra options to
           the `fcli sc-sast scan wait-for` command, for example to adjust the polling interval or timeout.
+      - names: DO_DEBRICKED_SCAN\nDEBRICKED_SCAN_EXTRA_OPTS
+        desc: >-
+          The fcli `ci` action supports running a DEBRICKED scan, which is enabled by default.
+          The `DEBRICKED_SCAN_EXTRA_OPTS` environment variable can be used to provide additional options to the
+          `fcli tool dcli install` command.
+      - names: DO_DEBRICKED_WAIT\nDEBRICKED_WAIT_EXTRA_OPTS
+        desc: >-
+          By default, the fcli `ci` action will wait for the Debricked scan to complete. This behavior can be
+          overridden by setting `DO_DEBRICKED_WAIT` to `false`, but note that doing so will skip any post-scan
+          tasks. The `DEBRICKED_WAIT_EXTRA_OPTS` environment variable can be used to pass extra options to
+          the `fcli ssc artifact wait-for` command.
     postScan:
       - names: AVIATOR_URL\nAVIATOR_TOKEN\nAVIATOR_LOGIN_EXTRA_OPTS
         desc: >-

fcli-core/fcli-action/src/main/resources/com/fortify/cli/generic_action/actions/zip/ci.yaml

@@ -53,6 +53,8 @@ config:
       sensitivity: high
     SSC_TOKEN:
       sensitivity: high
+    DEBRICKED_ACCESS_TOKEN:
+      sensitivity: high
     SC_SAST_TOKEN:
       sensitivity: high
 

fcli-core/fcli-common/src/main/resources/com/fortify/cli/common/actions/zip/ci-vars.yaml

@@ -49,7 +49,7 @@ steps:
     var.set:
       global.ci.name:              GitLab
       global.ci.id:                gitlab
-      global.ci.qualifiedRepoName: ${#env('CI_REPOSITORY_URL').replaceAll('[^:]+://[^/]+/','').replaceAll('\.git$', '')}
+      global.ci.qualifiedRepoName: ${#env('CI_REPOSITORY_URL')?.replaceAll('[^:]+://[^/]+/','')?.replaceAll('\.git$', '')}
       global.ci.sourceBranch:      ${#env('CI_COMMIT_BRANCH')?:#env('CI_MERGE_REQUEST_SOURCE_BRANCH_NAME')}
       global.ci.commitSHA:         ${#env('CI_COMMIT_SHA')}
       global.ci.sourceDir:         ${#env('SOURCE_DIR')?:#env('CI_PROJECT_DIR')?:'.'}
@@ -82,7 +82,9 @@ steps:
       # Set default Fortify repository name (SSC application version or FoD release),
       # from a similarly named global variable set by one of the sections above, or 
       # <qualifiedRepoName>:<sourceBranch>
-      global.ci.defaultFortifyRepo:  ${global.ci.av?:#joinOrNull(':', global.ci.qualifiedRepoName, global.ci.sourceBranch)}
+      global.ci.qualifiedRepoName: ${#env('REPOSITORY_NAME')?:global.ci.qualifiedRepoName}
+      global.ci.sourceBranch: ${#env('BRANCH_NAME')?:global.ci.sourceBranch}
+      global.ci.defaultFortifyRepo:  ${#joinOrNull(':', global.ci.qualifiedRepoName, global.ci.sourceBranch)}
       # Set default reporting actions based on ci identifier. Note that FoD/SSC CI actions should check existence of these actions 
       # TODO Only use default values if not explicitly defined in CI-specific sections above.
       global.ci.fod_prCommentAction:   ${#actionOrNull('fod',#joinOrNull('-', global.ci.id, 'pr-comment'))}

fcli-core/fcli-ssc/src/main/resources/com/fortify/cli/ssc/actions/zip/ci.yaml

@@ -47,14 +47,18 @@ steps:
       # Configure session name
       sessionName: ci-${#action.runID()}
       # Configure scan types to run
-      sca.skipReason:   # TODO
-      sca.skip: true
       dast.skipReason:  # TODO
       dast.skip: true
       sast.skipReason: > # Enabled by default, unless explicitly disabled or other scan type requested
         ${
             #skipReasonIf(#env('DO_SAST_SCAN')=='false', 'SAST scan disabled as DO_SAST_SCAN==false')
-            ?:#skipReasonIf(#env('DO_SAST_SCAN')!='true' && (!sca.skip || !dast.skip), 'SAST scan disabled as DO_SAST_SCAN!=true and other scan type requested')
+            ?:#skipReasonIf(#env('DO_SAST_SCAN')!='true' && !dast.skip, 'SAST scan disabled as DO_SAST_SCAN!=true and other scan type requested')
+        }
+      debricked.skipReason: > # Disabled by default, unless explicitly enabled
+        ${
+            #skipReasonIf(#env('DO_DEBRICKED_SCAN')=='false', 'Debricked scan disabled as DO_DEBRICKED_SCAN==false')
+            ?:#skipReasonIf(#env('DO_DEBRICKED_SCAN')!='true' && !dast.skip, 'Debricked scan disabled as DO_DEBRICKED_SCAN!=true and other scan type requested')
+            ?:#skipReasonIf(#isBlank('DEBRICKED_ACCESS_TOKEN'), 'Debricked scan disabled as the DEBRICKED_ACCESS_TOKEN is not set')
         }
       aviator.skipReason: >
         ${
@@ -109,7 +113,21 @@ steps:
               skip.if-reason:
                 - ${sast.skipReason}                     # Skip if SAST scan is skipped
                 - ${PACKAGE_ACTION.dependencySkipReason} # Skip if PACKAGE_ACTION was skipped or failed
-
+
+            DEBRICKED_SCAN_ACTION: 
+              cmd: ${#actionCmd('DEBRICKED_SCAN', 'ssc', 'debricked-scan')} --source-dir "${global.ci.sourceDir}" --av "${global.ci.av}"
+              skip.if-reason:
+                - ${#actionCmdSkipFromEnvReason('DEBRICKED_SCAN', true)} # This action will be skipped unlesss DO_<envPrefix>==true, or <envPrefix>_EXTRA_OPTS is specified
+                - ${debricked.skipReason} # Skip if Debricked scan is skipped
+
+            DEBRICKED_WAIT:
+              cmd: "${#fcliCmd('DEBRICKED_WAIT', global.debrickedPublish.waitForCmd)}"
+              skip.if-reason:
+                - ${#fcliCmdSkipFromEnvReason('DO_DEBRICKED_WAIT', false)}        # Skip if DO_DEBRICKED_WAIT==false
+                - ${DEBRICKED_SCAN_ACTION.dependencySkipReason}                   # Skip if DEBRICKED_SCAN_ACTION was skipped or failed
+              on.success:
+                - var.set: { postScan.skipReason: } # Reset postScan.skipReason to allow post-scan tasks to run       
+
             # TODO Improve this to:
             # - Wait for scan completion (but not publish completion)
             # - Download logs/fpr if debugging is enabled

fcli-core/fcli-ssc/src/main/resources/com/fortify/cli/ssc/actions/zip/debricked-scan.yaml

@@ -0,0 +1,105 @@
+# yaml-language-server: $schema=https://fortify.github.io/fcli/schemas/action/fcli-action-schema-dev-2.x.json
+
+author: Fortify
+usage:
+  header: (PREVIEW) Run Debricked Scan
+  description: |
+    This action can be used to run a debricked scan of the project.
+
+config:
+  output: immediate
+  rest.target.default: ssc
+  run.fcli.status.log.default: true    # By default, we log all exit statuses
+  run.fcli.status.check.default: true
+
+cli.options:
+  appVersion:
+    names: --app-version, --av
+    description: |
+      Application Version to which the debricked report must be imported to. Defaults to the value of the SSC_APPVERSION environment variable.
+    required: true 
+    default: ${#env('SSC_APPVERSION')}   
+  debrickedAccessToken:
+    names: --access-token, -t
+    description: |
+      Access tokens required for Debricked authentication. Defaults to the value of the DEBRICKED_ACCESS_TOKEN environment variable.
+    required: true 
+    default: ${#env('DEBRICKED_ACCESS_TOKEN')}
+    mask: {sensitivity: high}
+  dcliVersion:
+    names: --cli-version, -v
+    description: |
+      Specify the Debricked CLI tool version version to be installed that shall be used for scanning. Defaults to the value of the DEBRICKED_CLI_VERSION environment variable, or 'latest' if not specified.
+    required: false
+    default: ${#env('DEBRICKED_CLI_VERSION')?:'latest'}
+  sourceDir:
+    names: --source-dir, -d
+    description: |
+      Specify the source directory to be scanned for Open Source vulnerabilities. Defaults to the value of the SOURCE_DIR environment variable, or current working directory if not specified.
+    default: ${#env('SOURCE_DIR')?:'.'}
+    required: true
+  toolDefinitions:
+    names: --tool-definitions
+    description: |
+      Custom tool definitions to use for identifying available Debricked CLI tool versions and download URLs. Defaults to the value of the TOOL_DEFINITIONS environment variable, or the built-in default if not specified.
+    required: false 
+    default: ${#env('TOOL_DEFINITIONS')}
+  debrickedRepository:
+    names: --repository, -r
+    description: |
+      Debricked source repository name or ID.
+    required: false 
+    default: ${#env('REPOSITORY_NAME')}
+  debrickedBranch:
+    names: --branch, -b
+    description: |
+      Debricked source branch name or ID.
+    required: false 
+    default: ${#env('BRANCH_NAME')}
+  debrickedWait:
+    names: --wait
+    description: |
+      An option to be passed to make the action wait until `fcli ssc artifact import-debricked` completes. Defaults to the value of the DO_DEBRICKED_WAIT environment variable.
+    required: false
+    default: ${#env('DO_DEBRICKED_WAIT')}
+    type: boolean
+  extraOpts:
+    names: --extra-opts
+    description: |
+      Extra options to be passed to the 'debricked scan' command. Defaults to the options specified in the DEBRICKED_SCAN_EXTRA_OPTS environment variable, or no extra options if not specified. 
+    required: false
+    default: ${#extraOpts('DEBRICKED_SCAN')}
+
+steps:
+  - if: ${#isBlank(cli.debrickedRepository)||#isBlank(cli.debrickedBranch)}
+    steps:
+      - var.set:
+          localRepository: ${#localRepo(cli.sourceDir)}
+      - if: ${localRepository == null}
+        throw: Cannot fetch the repository details from the given source directory.
+      - var.set:
+          localRepo: ${localRepository?.repository.name.full}
+          localBranch: ${localRepository?.branch.short}
+  - var.set:
+      global.debrickedPublish.fcliVarName: debricked_scan_${#action.runID().replace('-','_')} # fcli variable to store the artifact name to be used in next command to wait-for artifact upload command 
+      global.debrickedPublish.waitForCmd: 'fcli ssc artifact wait-for ::${global.debrickedPublish.fcliVarName}::'
+  - run.fcli:
+      UPDATE_TOOL_DEFINITIONS: fcli tool definitions update ${cli.toolDefinitions?:""}
+  - run.fcli:
+      INSTALL_DEBRICKED: fcli tool dcli install -v ${cli.dcliVersion}
+  - run.fcli:
+      RUN_DEBRICKED_CLI: 
+        cmd: fcli tool dcli run -- scan ${cli.sourceDir} -t ${cli.debrickedAccessToken} -r ${cli.debrickedRepository?:localRepo} -b ${cli.debrickedBranch?:localBranch} ${cli.extraOpts} 
+        stdout: collect
+        stderr: collect
+        on.fail:
+          - if: ${#isNotBlank(RUN_DEBRICKED_CLI.stdout)  && !RUN_DEBRICKED_CLI.stdout.contains('vulnerabilities found') && !RUN_DEBRICKED_CLI.stdout.contains('For full details, visit:')}
+            throw: Debricked Scan failed with errors.
+  - out.write:
+      stdout: ${RUN_DEBRICKED_CLI.stdout}
+      stderr: ${RUN_DEBRICKED_CLI.stderr}
+  - run.fcli:
+      IMPORT_DEBRICKED_SCAN_REPORT: fcli ssc artifact import-debricked --av ${cli.appVersion} -t ${cli.debrickedAccessToken} -r ${cli.debrickedRepository?:localRepo} -b ${cli.debrickedBranch?:localBranch} --store ${global.debrickedPublish.fcliVarName}
+  - if: ${cli.debrickedWait}
+    run.fcli:
+      WAIT: ${global.debrickedPublish.waitForCmd}