Quickstart: Black Duck Security Scan Pipe with Black Duck SCA

definitions:
  services:
    docker:
      memory: 3072 # Allocate 3GB (3072MB) memory to docker service
  steps:
    - step: &blackduck-security-scan
        name: Black Duck Security Scan
        script:
          - pipe: blackduck-inc/blackduck-security-scan:1.6.0
            variables:
              BRIDGE_BLACKDUCKSCA_URL: $BLACKDUCKSCA_URL
              BRIDGE_BLACKDUCKSCA_TOKEN: $BRIDGE_BLACKDUCKSCA_TOKEN
              BRIDGE_BITBUCKET_API_TOKEN: $BITBUCKET_REPO_ACCESS_TOKEN
              BRIDGE_BLACKDUCKSCA_FIXPR_ENABLED: "true"
              BRIDGE_BLACKDUCKSCA_AUTOMATION_PRCOMMENT: "true"
              BRIDGE_BLACKDUCKSCA_REPORTS_SARIF_CREATE: "true"
              BRIDGE_BLACKDUCKSCA_SCAN_FAILURE_SEVERITIES: BLOCKER
              DETECT_PROJECT_VERSION_NAME: ${BITBUCKET_PR_DESTINATION_BRANCH:-$BITBUCKET_BRANCH}
              # INCLUDE_DIAGNOSTICS: true
        # artifacts:
        #  - ".blackduck/integrations/blackducksca/sarif/report.sarif.json"
        #  - ".bridge/**"

pipelines:
  pull-requests:
    "**":
      - step: *blackduck-security-scan
  branches:
    "{main,master,develop,stage,release}":
      - step: *blackduck-security-scan

In the example above a Black Duck Security Scan step runs whenever code is pushed to the main, master, develop, stage or release branches, or when a Pull Request is created. The scan type is automatically determined by the Black Duck Security Scan Pipe depending on the context in which the pipeline was triggered. The scan behavior is explained below.

The pipeline integrates with a Black Duck® SCA server instance via the BRIDGE_BLACKDUCKSCA_URL and BRIDGE_BLACKDUCKSCA_TOKEN parameters. A scan will run for a Black Duck® SCA project named after the Bitbucket workspace and repository slug, e.g. my-bitbucket-workspace/my-repository-slug. Within this project, the project version is derived from the DETECT_PROJECT_VERSION_NAME environment variable. For full scans this corresponds to the name of the branch that had commits pushed. For Pull Request scans the project version is set to the name of the target branch of the Pull Request.

The behavior of the scans is as follows:

• Full Scan: Triggered by push events to main, master, develop, stage or release branches. In this scenario the following actions will be performed:

  • An SCA assessment will be run.

  • A SARIF report will be generated and exported only for full scans. This operation requires a Bitbucket Access Token.

  • Fix PRs will be automatically raised to fix vulnerable direct dependencies. This operation requires a Bitbucket Access Token.

• Pull Request Scan: Triggered for Pull Request push events. A Pull Request scan is performed that will run an SCA assessment to scan the source code. Review comments will be injected (BRIDGE_BLACKDUCKSCA_AUTOMATION_PRCOMMENT: true) for any new issues introduced since the latest full scan of the Pull Request's target branch. This operation requires a Bitbucket Access Token.

Both scans will fail the CI/CD build if a Black Duck SCA Policy violation is detected with a severity level of BLOCKER.

Uncomment the INCLUDE_DIAGNOSTICS parameter and artifacts section to upload logs and reports as Bitbucket artifacts. These artifacts can be accessed and downloaded from the Artifacts tab of the pipeline's job page in Bitbucket (Repository > Pipelines).

git add bitbucket-pipelines.yml
git commit -m "update pipeline to add security scan"
git push -u origin main

Once the changes have been saved to bitbucket-pipelines.yml the pipeline should be triggered to run on the main, master, develop, stage or release branch. Subsequently, it is then possible to open Bitbucket Pull Requests to run one or more Black Duck® SCA Pull Request scans.

An example review comment added to a Bitbucket Pull Request after a Black Duck® SCA Pull Request scan has run is shown below.