Detect Action

ℹ️ This action is a fork from synopsys-sig/detect-action.

The repository from synopsys is no longer maintained and was deprecated in favour of a new action synopsys-sig/synopsys-action, which is built on top of Synopsys Bridge and has support for several Synopsys tools not focusing only on Black Duck.

In this fork we decided to continue the developments on detect-action, which focus only on Black Duck tool.

⚠️ From v0.4.0 onwards this action requires to be executed with detect v8 or above.

Richly integrate Synopsys Detect into GitHub action workflows.

Configure the action to run Detect in Rapid scan mode to get detailed Black Duck policy reports (default behavior), or in Intelligent scan mode to upload your data into Black Duck for more detailed analysis.

Once your dependencies are clean, configure the action to run Detect in Rapid scan mode to protect your branches with the Black Duck Policy Check and Branch Protection Rules.

Changelog

For a detailed list of changes and releases, please refer to the Changelog.

Recommended Usage

To get the most out of this action, we recommend using RAPID scan-mode for all Pull Requests.

INTELLIGENT scan-mode is best run on a schedule that can vary by repository. A very active repository would benefit from at least one daily scan, while a less active repository might only need to be scanned once or twice a week. It is still important that low-activity repositories be scanned regularly because new vulnerabilities can be discovered for existing dependencies and source-code.

Set Up Workflow

To start using this action, you'll need to create a job within a GitHub Workflow. You can either create a new GitHub Workflow or use an existing one if appropriate for your use-case.

Once you have a GitHub Workflow selected, configure which events will trigger the workflow such as pull requests or schedules.

Example:

name: Example Workflow
on:
  pull_request:
    branches:
      - main
  schedule:
    - cron: '0 0 * * *'

Set Up Job

Once you have set up a GitHub Workflow with event triggers, you will need to create a job in which the Detect Action will run. Your job will look something like this if all configuration options are used:

jobs:
  security:
    runs-on: my-github-runner
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Set up Java 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
      # Because this example is building a Gradle project, it needs to happen after setting up Java
      - name: Grant execute permission for gradlew to build my project
        run: chmod +x gradlew
      - name: Build my project with Gradle
        run: ./gradlew build
      - name: Create Black Duck Policy
        env:
          NODE_EXTRA_CA_CERTS: ${{ secrets.LOCAL_CA_CERT_PATH }}
        uses: blackducksoftware/[email protected]
        with:
          blackduck-url: ${{ secrets.BLACKDUCK_URL }}
          blackduck-api-token: ${{ secrets.BLACKDUCK_API_TOKEN }}
          policy-name: 'My Black Duck Policy For GitHub Actions'
          no-fail-if-policy-exists: true
      - name: Run Synopsys Detect
        uses: tvcsantos/detect-action@v2
        env:
          NODE_EXTRA_CA_CERTS: ${{ secrets.LOCAL_CA_CERT_PATH }}
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          detect-version: 8.11.0
          blackduck-url: ${{ secrets.BLACKDUCK_URL }}
          blackduck-api-token: ${{ secrets.BLACKDUCK_API_TOKEN }}

Runners: Self-Hosted

Using a self-hosted runner provides more flexibility in managing your build environment.

Java

It is possible to skip the Set Up Java step below if you already have Java 17 on your self-hosted runner. Ensure that the Detect Action has access to the correct version of Java on its $PATH or within the GitHub Tool Cache.

Certificates: Self-Hosted

If your Black Duck server is on a private network, the self-hosted runner has access to that network, and the Black Duck server uses custom certificates, then you will likely need to provide a custom certificate to the Detect Action. To do this:

1. Store the root certificate on the self-hosted runner. Example location: /certificates/my_custom_cert.pem

2. Set NODE_EXTRA_CA_CERTS in the Detect Action's environment:

       - name: Run Synopsys Detect
         uses: tvcsantos/detect-action@v2
         env:
           NODE_EXTRA_CA_CERTS: /certificates/my_custom_cert.pem
         with:
           #...

   Note: The path to the certificate can be stored in a GitHub Secret.

Please reference the section Include Custom Certificates (Optional) for more information.

More Info

For more information on self-hosted runners, please visit GitHub's documentation.

Runners: GitHub-Hosted

GitHub hosted runners are convenient, but can require extra setup when managing sensitive information.

Certificates: GitHub-Hosted

Because a GitHub-hosted runner starts with a clean file-system each run, if custom certificate files are needed, they must be created in your workflow. There are many ways to do this, two possible ways are:

Option 1: Download the certificate file.

Option 2: Store the base-64 encoded certificate in a GitHub secret, then use a workflow-step to create a .pem file with that certificate's content:

    - name: Create certificate
      shell: bash
      env:
        BASE_64_CERTIFICATE: ${{ secrets.BASE_64_CERTIFICATE_CONTENT }}
      run: cat <<< "${BASE_64_CERTIFICATE}" > my-cert.pem

The file created through one of those options can then be provided as a value for NODE_EXTRA_CA_CERTS in the Detect Action step:

    - name: Run Synopsys Detect
      uses: tvcsantos/detect-action@v2
      env:
        NODE_EXTRA_CA_CERTS: ./my-cert.pem
      with:
        #...

Checkout

Checkout the source-code onto your GitHub Runner with the following step:

    - uses: actions/checkout@v4

Build Your Project

Detect is meant to be run post-build. You should add steps necessary to build your project before invoking the Detect Action. For example, here is how this might be done in a Gradle project:

    - name: Grant execute permission for gradlew
      run: chmod +x gradlew
    - name: Build with Gradle
      run: ./gradlew build

In the example job above, this needed to be done after setting up Java because Gradle requires Java. If your project does not use Java, this step can be done before setting up Java.

Set Up Java

Detect runs using Java. Configure the step it as follows:

    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'

Create Black Duck Policy (Optional)

In order to run Detect using RAPID mode (which is the default mode for the Detect Action), the Black Duck server Detect connects to must have at least one policy and that policy must be enabled. You can create a policy within your Black Duck instance, or you can create a policy directly from your workflow using Black Duck's Create Policy Action. Note: The Create Policy Action is provided for convenience and not the preferred way to manage Black Duck policies.

The most basic usage of the action looks something like this:

    - name: Create Black Duck Policy
      env:
        NODE_EXTRA_CA_CERTS: ${{ secrets.LOCAL_CA_CERT_PATH }}
      uses: blackducksoftware/[email protected]
      with:
        blackduck-url: ${{ secrets.BLACKDUCK_URL }}
        blackduck-api-token: ${{ secrets.BLACKDUCK_API_TOKEN }}
        policy-name: 'My Black Duck Policy For GitHub Actions'
        no-fail-if-policy-exists: true

Please refer to that action's documentation for more information on available parameters, certificate management, and troubleshooting.

Set Up Detect Action

Once your project is checked-out, built, and Java is configured, the Detect Action can be run. At minimum for Detect to run, provide:

• Black Duck URL (blackduck-url)
• Black Duck API Token (blackduck-api-token)
• Your desired Detect Version (detect-version), or empty if you want to scan using the latest version
• Your GITHUB_TOKEN (github-token) to comment on Pull Requests or hook into GitHub Checks (in most cases, this is ${{ secrets.GITHUB_TOKEN }})

Choose your Scanning Mode

The Detect Action can be configured either to monitor your commits for policy violations or upload the status of your repository to Black Duck as a project through use of the scan-mode option.

Set the scan mode to:

• RAPID (default) if you want to enable the Black Duck policy check and comments on your pull requests, for example:

  name: 'Example: Policy check all commits and all Pull Requests to main'
  on:
    pull_request:
      branches:
        - main
    push:
  #...
      - name: Run Synopsys Detect
        uses: tvcsantos/detect-action@v2
        env:
          NODE_EXTRA_CA_CERTS: ${{ secrets.LOCAL_CA_CERT_PATH }}
        with:
            scan-mode: RAPID # Can be omitted, since this is the default value
            github-token: ${{ secrets.GITHUB_TOKEN }}
            detect-version: 8.11.0
            blackduck-url: ${{ secrets.BLACKDUCK_URL }}
            blackduck-api-token: ${{ secrets.BLACKDUCK_API_TOKEN }}

• INTELLIGENT if you want to execute a full analysis of Detect and upload your results into a project in Black Duck, for example:

  name: 'Example: Every day at midnight, update Black Duck project'
  on:
    schedule:
      - cron:  '0 0 * * *'
  #...
      - name: Run Synopsys Detect
        uses: tvcsantos/detect-action@v2
        env:
          NODE_EXTRA_CA_CERTS: ${{ secrets.LOCAL_CA_CERT_PATH }}
        with:
            scan-mode: INTELLIGENT
            github-token: ${{ secrets.GITHUB_TOKEN }}
            detect-version: 8.11.0
            blackduck-url: ${{ secrets.BLACKDUCK_URL }}
            blackduck-api-token: ${{ secrets.BLACKDUCK_API_TOKEN }}

These modes also have implications for how Detect is run. RAPID will not persist the results and disables select Detect functionality for faster results. INTELLIGENT persists the results and permits all features of Detect.

See also: Detect Documentation of Rapid Scan.

Additional Action Parameters

• output-path-override: Override for where to output Detect files
  • Default: $RUNNER_TEMP/blackduck/

Additional Detect Properties

Passing additional Detect properties can be done in several ways:

1. Use individual environment variables

   Example:

       - name: Synopsys Detect
         uses: tvcsantos/detect-action@v2
         env:
           DETECT_TOOLS: DOCKER
           DETECT_DOCKER_IMAGE_ID: abc123
           DETECT_DOCKER_PATH_REQUIRED: TRUE
         with:
           #...

2. Use the SPRING_APPLICATION_JSON environment variable

   Example:

       - name: Synopsys Detect
         uses: tvcsantos/detect-action@v2
         env:
           SPRING_APPLICATION_JSON: '{"detect.tools":"DOCKER","detect.docker.image.id":"abc123","detect.docker.path.required":"TRUE"}'
         with:
           #...

3. Expose an application.properties or application.yml file in your repository's root directory, or in a config subdirectory

   Please refer to the Detect documentation on this topic for more information.

Detect Diagnostic ZIP

When passing the properties DETECT_DIAGNOSTIC or DETECT_DIAGNOSTIC_EXTENDED as environment variables, the action will helpfully upload the ZIP as a build artifact for convenient troubleshooting. Note: These properties must be set to true or false (rather than 1) when using the action.

Detect Exit Code output

After running detect this action will set the following output variables with detect exit code information:

• detect-exit-code - A number indicating Detect exit code.
• detect-exit-code-name - The corresponding human name of the error code.

Note that if Detect is not called these variables are not populated. Also, if a mapping for the exit code number is not found on our side detect-exit-code-name we will set it to UNKNOWN.

Include Custom Certificates (Optional)

To include one or more certificates, set NODE_EXTRA_CA_CERTS to the certificate file-path(s) in the environment. Notes:

• The certificate(s) must be in pem format.
• This environment variable can also be used with the Create Policy Action.

Example:

  - name: Synopsys Detect
    uses: tvcsantos/detect-action@v2
    env:
      NODE_EXTRA_CA_CERTS: ${{ secrets.LOCAL_CA_CERT_PATH }}
    with:
      #...

Troubleshooting Certificates

• Problem: An error saying the file-path to the certificate cannot be read.
  • Solution: Ensure whitespace and other special characters are properly escaped based on your runner's OS.
• Problem: An error about missing certificates in the certificate-chain or missing root certificates.
  • Solution: You may only be including the server's certificate and not the root CA certificate. Ensure you are using the root CA certificate.

Policy Checks

When the Detect Action runs in RAPID mode, it creates a 'Black Duck Policy Check'. This check can be used within Branch Protection Rules to prevent merging Pull Requests that would introduce Black Duck Policy Violations.

License

This project is licensed under the Apache License 2.0 - see the License file for details.

Contributing and Code of Conduct

Please refer to our Contribution Guidelines for detailed information on how to propose changes, submit pull requests, and ensure a smooth collaboration process within the team. Also, don't forget to read and respect our established Code of Conduct in all your interactions and contributions.

If you have any questions or require clarification on our guidelines, please reach out!