GitHub Workflow Integration

The Veracode GitHub Workflow Integration allows you to set up an automated security scanning program for all of your GitHub repositories with a GitHub app.

The integration repository includes the template workflows required for the GitHub Workflow Integration to function correctly. In addition, it includes the configuration file, veracode.yml, which stores the default settings for you to scan your repositories with Veracode.

This document explains the steps required to install the integration, configure Veracode scans, and view your scan results.

Language support

The GitHub Workflow Integration supports scanning repositories written in the following languages:

Language	Version	Package manager	Static support	SCA support
.NET	.NET 6,7 8	Not applicable	X	X
Android	Not applicable	Gradle 8.7	X
Go	Go 1.22.4	Not applicable	X	X
Java	Java 21 or later	Gradle 8.7	X	X
JavaScript	Not applicable	NPM, Yarn	X	X
Kotlin	Not applicable	Gradle 8.7	X	X
PHP	5.2–7.4, 8.0-8.3	Laravel 5.x-10.x, Zend 1, 2, 3		X
Python	Python 3	pip	X	X
React Native	Not applicable	NPM, Yarn	X
Ruby	Ruby 3.0 or later	Bundler	X
Scala	Latest	Gradle 8.7	X	X
TypeScript	Not applicable	NPM, Yarn	X	X

For Static Analysis, the GitHub Workflow Integration automatically compiles the repository by default. However, for some applications, you may need to provide specific compilation instructions in the original repository. See the packaging requirements for each language.

For SCA, see the agent-based scan support matrix for additional support details.

GitHub support

The GitHub Workflow Integration is supported on GitHub Enterprise. It is not supported on GitHub Enterprise Server.

Configure the integration

To set up the GitHub Workflow Integration for repositories in your organization, import the Veracode repository and download the Veracode app.

Ensure the required GitHub Actions are allowed

Your GitHub organization must allow the GitHub Workflow Integration to perform several actions.

To complete this task:

In the upper-right corner of GitHub, select your profile image.
Select Your organizations.
Next to the organization where you want to install the app, select Settings.
Select Actions > General.

In the Policies section, do one of the following:

Select Allow all actions and reusable workflows.

Select Allow {Your organization}, and select non-{Your organization}, actions and reusable workflows, and paste the following list of actions in the text field:

actions/checkout@*
actions/checkout@*
actions/download-artifact@*
actions/setup-java@*
actions/upload-artifact@*
android-actions/setup-android@*
flutter-actions/setup-flutter@*
octokit/request-action@*
veracode/container_iac_secrets_scanning@*
veracode/github-actions-integration-helper@*
veracode/uploadandscan-action@*
veracode/veracode-flaws-to-issues@*
veracode/Veracode-pipeline-scan-action@*
veracode/veracode-pipeline-scan-results-to-sarif@*
veracode/veracode-sca@*  

Select Save.

Import the integration repository

To scan specific repositories and customize the behavior of the GitHub Workflow Integration, import the veracode repository for the integration into the root folder.

warning

Do not fork the veracode repository. The forked repository would be public, which makes parts of your code and your scan results publicly visible.

Import a new repository.
For the source repository URL, enter https://github.com/veracode/github-actions-integration.git.
For Owner, select the GitHub organization where you want to install the app.
For Repository name, enter veracode.
Select Private.
Select Begin import.

Select the Veracode Workflow App from the GitHub marketplace or select Install on the Veracode Workflow App page in GitHub.
If you used the GitHub marketplace, select Set up a new plan.
Select the organization you selected as the owner when you imported the integration repository.
Select one of the following scopes:
- All repositories - If you want to grant Veracode access to scan every repository, select All repositories.
- Select repositories - If you only want Veracode to scan specific repositories, select Only select repositories, and select the repositories that you want scanned. For this option, you must add the imported veracode repository to your list of selected repositories.
Select Install.

Setting up GitHub secrets for scanning

You must add the appropriate GitHub secrets to this repository to allow Veracode to run Static Analysis and SCA scans.

Configure Veracode API ID and secret for Static Analysis

If you want to perform Veracode Static Analysis scans of your repositories, you must:

Generate your Veracode API ID and secret key from the Veracode Platform.
Configure a GitHub secret in your repository called VERACODE_API_ID for your Veracode API ID and another called VERACODE_API_KEY for your API secret key.

Configure SCA agent token

Veracode uses the Software Composition Analysis (SCA) agent within your workflows to scan your code.

If you want to perform SCA agent-based scans of your repositories, you must:

Identify the agent token value for the SCA workspace in which you want your scan results to appear. If you do not know the token, you can regenerate it.
Configure a GitHub secret in your repository called VERACODE_AGENT_TOKEN for your token.

How scanning works

In your veracode.yml file, you can customize the behavior of the GitHub Workflow Integration. You can apply several configurations, including:

The types of scans to run
Which branches to target
Which Veracode security policy to apply
Whether a failure breaks the build
Whether the scan is triggered by a push or a pull
The compilation instructions

See the full list of available configurations.

Important

The GitHub Workflow Integration only supports jobs that run on Linux runners.

By default, your veracode.yml file is configured with the following scan triggers:

Static pipeline scan on any push activity on any branch
SCA agent-based scan on any push activity on any branch
Veracode Container Security scan on any push activity on any branch

If you set analysis_on_platform to true, these additional scans are triggered by default:

Sandbox scan, which sends results to the Veracode Platform, when a pull request is open to your analysis_branch
Policy scan, which sends results to the Veracode Platform, after code is merged into your analysis_branch

You can configure all of these to fit your own organization's process by editing the veracode.yml file.

Specify repositories to scan

By default, the GitHub Workflow Integration scans all repositories except for the veracode repository.

Exclude specific repositories

Open repo_list.yml in the veracode repository.
Under exclude_repos: enter the list of repositories you want to exclude. Each repository name must be surrounded by single quotes, for example: 'java_Repo'

Include only specific repositories

Open repo_list.yml in the veracode repository.
Under include_repos: enter the list of repositories you want to include. Each repository name must be surrounded by single quotes, for example: 'java_Repo'
If the list includes '*', delete it. If it is present, Veracode will scan all repositories that are not listed under exclude_repos:.

`veracode.yml` configurations

In your veracode.yml file, you can configure the following values to customize the integration:

Value	Description	Default value
`push`:`trigger`	If `true`, a pipeline scan is triggered when you commit changes to a branch.	`true`
`push`:`branches_to_run`	The branches that trigger pipeline scans when you commit changes. If `'*'`, all branches can trigger scans.	`'*'`
`push`:`branches_to_exclude`	The branches that do not trigger scans. Only applies if `branches_to_run` is set to `'*'`.
`pull_request`:`trigger`	If `true`, a scan is triggered when you perform a pull request action.	`true`
`pull_request`:`action`	Pull request actions that trigger scans. Valid values are: `opened`, `reopened`, `edited`, `synchronize`, `closed`.	`opened` and `synchronize`
`pull_request`:`target_branch`	The target branch that triggers scans when you perform pull request actions.	`default_branch`
`analysis_branch`	The branch submitted to the Veracode Platform for analysis. If you do not enter a valid branch name, Veracode uses the default branch.	`default_branch`
`analysis_on_platform`	If `false`, no scans are submitted to the Veracode Platform. If `true`, scans from the `analysis_branch` are submitted to the Platform, creating an application profile that has the repository's name.	`false`
`break_build_policy_findings`	If `true`, the build breaks when the policy name is invalid.	`true`
`error_message`	The error message that appears when the build fails.	`Veracode SAST scan faced a problem. Please contact your Veracode administrator for more information.`
`policy`	The application security policy applied to your scan findings, if a policy is not already assigned to your application profile.	`'Veracode Recommended Medium + SCA'`
`create_code_scanning_alert`	If `true`, GitHub generates alerts for your Static Analysis findings in the Security tab.	`false`
`create_issue`	If `true`, GitHub generates issues for scan findings.	`false`
`profile`	The application profile associated with the GitHub project.	The name of the GitHub repository
`issues`:`trigger`	If `true`, a scan is triggered when you create an issue containing the `commands` value or add a comment containing the `commands` value to an issue.	`false`
`issues`:`commands`	The text that triggers an on-demand scan when you add it to a GitHub issue.	`"ENTER_COMMAND_TO_EXECUTE_SCAN"`
`use_custom_workflow`	The workflow the Veracode Workflow App uses to build your project before scanning. By default, it uses the workflows in the `veracode` repository’s `.github/workflows folder`. You might want to customize it in a developer's repository.	The workflows in the `veracode` repository’s `.github/workflows folder`
`filter_mitigated_flaws`	If `true`, mitigated flaws are excluded from repository checks, the Issues tab, and the code scanning alerts.	`true`
`actions`:`ruby`:`version`	The Ruby version that your project requires. For projects not written in Ruby, Veracode ignores this configuration.	`3.3.4`
`actions`:`ruby`:`bundle`	The bundle version that your Ruby project requires. For projects not written in Ruby, Veracode ignores this configuration.	`2.5.7`
`actions`:`{scan type}`:`build`:`runs_on`	The operating system on which to run your GitHub workflows.	`ubuntu-latest`
`actions`:`{scan type}`:`build`:`packager_image`	The public Docker image to use for building your project.	`veracode/scm-packaging:3.0.0`
`actions`:`{scan type}`:`build`:`predependency_command`	Set of commands that must be executed before building the project. For example: `apt-get install -y vim`

See the following example veracode.yml file:

veracode_static_scan:
  push:
    trigger: true
    # Please only specify either branches_to_run or branches_to_exclude
    # Entering both will only execute branches_to_run
    # Leaving them both blank means this will never run
    branches_to_run:
      - '*'
    branches_to_exclude:
  pull_request:
    trigger: false
    action:
      - opened
      - synchronize
    target_branch:
      - default_branch
  # If the analysis_on_platform is set to true,
  # Veracode will save your last scan result, on the default branch, as an application profile with the same name as your scanned repository on the Veracode platform. 
  # If the analysis_on_platform is set to false, scan results will not be saved to the Veracode platform.
  analysis_on_platform: false
  # If break_build_policy_findings is set to true, the build will break when findings violate the policy.
  break_build_policy_findings: true
  # If break_build_invalid_policy is set to true, the build will break when the policy name is invalid.
  break_build_invalid_policy: true
  # If the break_build_on_error is set to true, the build will break if the scan failed to complete in time or with an error and the error_message will be displayed.
  break_build_on_error: false
  error_message: "Veracode static scan faced a problem. Please contact your Veracode administrator for more information."
  # Default policy to be used if a policy isn't already assigned to the application profile.
  policy: 'Veracode Recommended Medium + SCA'
  # If the create_code_scanning_alert is set to true, GitHub security code scanning vulnerability alerts will be created for static findings.
  create_code_scanning_alert: false
  # If the create_issue is set to true, GitHub Issues will be created for static findings.
  create_issue: false
  # If the trigger is set to true, a scan is triggered when you create an issue containing the commands value or add a comment containing the commands value to an issue.
  # Syntax to be used - COMMANDS_VALUE [branch: BRANCH_NAME]
  issues:
    trigger: false
    commands:
      - "Veracode Static Scan"

veracode_sca_scan:
  push:
    trigger: false
    # Please only specify either branches_to_run or branches_to_exclude
    # Entering both will only execute branches_to_run
    # Leaving them both blank means this will never run
    branches_to_run:
      - '*'
    branches_to_exclude:
  pull_request:
    trigger: false
    action:
      - opened
      - synchronize
    target_branch:
      - default_branch
  # If the break_build_on_error is set to true, the build will break if the scan failed to complete or with an error, no libraries were found, 
  # or no build system was found and the error_message will be displayed.
  break_build_on_error: true
  error_message: "Veracode SCA scan faced a problem. Please contact your Veracode administrator for more information."
  # If the trigger is set to true, a scan is triggered when you create an issue containing the commands value or add a comment containing the commands value to an issue.
  # Syntax to be used - COMMANDS_VALUE [branch: BRANCH_NAME]
  issues:
    trigger: false
    commands:
      - "Veracode SCA Scan"
  
actions:
  ruby:
    version: 3.2.2
    bundle: 2.4.6
  veracode_static_scan:
    build:
      runs_on:
      packager_image: veracode/scm-packaging:3.0.0
      predependency_command: | 
        apt-get install -y vim

  veracode_sca_scan:
    build:
      runs_on:
      packager_image:
      predependency_command: |  

Use your source repositories' build steps

By default, the Veracode Workflow App uses the workflows in the veracode repository to build your project before scanning.

You have the option use your own build artifact created on the source repository, instead of the default build that Veracode provides.

Before you begin:

Your repository must include a workflow YAML file that builds your project.

To complete this task:

In your source repository's workflow file that builds the project, add the following register step:

  register:
   runs-on: ubuntu-latest
   name: register
   steps:
     - name: Register build
       id: register-build
       uses: veracode/github-actions-integration-[email protected]
       with:
         action: registerBuild
         token: ${{ github.event.client_payload.token }}
         appname: ${{ github.event.client_payload.user_config.profile_name }}
         source_repository: ${{ github.event.client_payload.repository.full_name }}
         check_run_id: ${{ github.run_id }}
         check_run_name: ${{ github.workflow }}
         head_sha: ${{ github.event.client_payload.sha }}
         event_type: ${{ github.event.client_payload.event_type }}
         branch: ${{ github.event.client_payload.user_config.sandbox_scan.branch }}
         issue_trigger_flow: ${{ github.event.client_payload.user_config.issue_trigger_flow }}

In the same workflow file, change the event type to repository_dispatch.
In the veracode.yml file in your source repository, make the following configurations:
- Set the use_custom_workflow parameter to the name of the workflow file that builds the project.
- Set the artifact_file parameter to the relative path of the artifact file that gets generated during the local build of the project. For example:
```
veracode_static_scan:
 use_custom_workflow: veracode-build
 artifact_file: ./veracode-artifact/veracode-artifact.zip
```

Configure integration for individual repositories

Adding a veracode.yml file to individual repositories lets you overwrite specific scan settings defined in your organization's central veracode.yml file.

To overwrite the settings:

Add a veracode.yml file to the root of your developer's repository.
Add the updated configuration to the file. All veracode.yml files must include the heading and the value that you want to overwrite. For example, this veracode.yml file overwrites the policy applied to Static Analysis scans and sets a custom workflow for the repository:
```
veracode_static_scan:
policy: 'Veracode Recommended Very High'
use_custom_workflow: my_custom_build
```

Trigger on-demand scanning with GitHub issues

You can trigger scans on demand using GitHub issues.

Before you begin:

Have permissions to create issues in GitHub.
In your veracode.yml file, under issues:
- Set trigger to true.
- Set commands to the value that you will use as the description for your issues. If you want to trigger Static Analysis, SCA, and Container Security scans separately, they must have different commands values.

To complete this task:

In your GitHub repository, select the Issues tab.
Enter a title.
In the Add a description field, enter the commands value from the veracode.yml file. For example, veracode-static-scan or veracode-sca-scan. By default, this triggers a policy scan of the analysis branch, which is usually the main branch. To include multiple commands, enter a comma-separated list. To specify a branch to scan, add the branch in parentheses. For example, veracode-static-scan[branch:dev-patch-101].
To trigger additional scans for the same issue, enter the commands value in a comment on the issue.

On-demand scan findings, like the push-triggered scans findings, are available in the check for the repository.

View results in GitHub

You can view Veracode scan results in GitHub in status checks of the repository, as code scanning alerts, and as issues.

Status checks

After scans of a repository are complete, the Veracode security findings are available in the check for the repository.

To view the findings:

Open a GitHub repository in which a scan has been completed.
Select the branch you want to view.
Select the status icon of the check. The icon can be a green checkmark, a red X, or an orange circle to indicate that the security checks were successful, unsuccessful, or in progress, respectively.
Select Details.

For scans triggered by a pull request, you can also view the findings on the request.

Open a GitHub repository in which a scan has been completed.
Select the Pull Requests tab.
Select the pull request.
Select the Checks tab or the Files changed tab. The Files changed tab displays the findings details inline, so you can see exactly where in the code the flaw was identified.

For sandbox scans and policy scans, you can also view results

Code scanning alerts

You can view your Static Analysis findings as code scanning alerts in GitHub.

Before you begin:

Have code scanning alerts enabled for your repository.
In your veracode.yml file, have create_code_scanning_alert set to true.

To complete this task:

Open a GitHub repository in which a scan has been completed.
Select the Security tab.
Select Code scanning.
Select the finding you want to review.

GitHub Issues

If you have used on-demand scanning with GitHub issues, you can view your issues in the dashboard for your project.

Reviewing results in the Veracode Platform

If you set analysis_on_platform to true, you can view scan results in the Veracode Platform.

Static Analysis scans return a list of annotations describing each static flaw and a link to the Veracode Platform where you can view a full report of your results. If an application profile for a scanned repository does not already exist in the Veracode Platform, Veracode automatically creates one using the name of the repository as the name of the profile.

If you mitigate findings from Static pipeline scans, by default, Veracode synchronizes your findings so that the mitigated findings do not appear in subsequent pipeline scans.

For more information on reviewing Static Analysis findings, see Reviewing scan results.

SCA scans return a summary report of your open source security findings as well as a detailed list of libraries, vulnerabilities, and licenses. For more information about SCA findings, see Viewing agent-based scan results.

GitHub Workflow Integration

Language support

GitHub support

Configure the integration

Ensure the required GitHub Actions are allowed

Import the integration repository

Download the app

Setting up GitHub secrets for scanning

Configure Veracode API ID and secret for Static Analysis

Configure SCA agent token

How scanning works

Specify repositories to scan

Exclude specific repositories

Include only specific repositories

`veracode.yml` configurations

Use your source repositories' build steps

Configure integration for individual repositories

Trigger on-demand scanning with GitHub issues

View results in GitHub

Status checks

Code scanning alerts

GitHub Issues

Reviewing results in the Veracode Platform

Did you find this helpful?

Language support​

GitHub support​

Configure the integration​

Ensure the required GitHub Actions are allowed​

Import the integration repository​

Download the app​

Setting up GitHub secrets for scanning​

Configure Veracode API ID and secret for Static Analysis​

Configure SCA agent token​

How scanning works​

Specify repositories to scan​

Exclude specific repositories​

Include only specific repositories​

veracode.yml configurations​

Use your source repositories' build steps​

Configure integration for individual repositories​

Trigger on-demand scanning with GitHub issues​

View results in GitHub​

Status checks​

Code scanning alerts​

GitHub Issues​

Reviewing results in the Veracode Platform​

Did you find this helpful?

Language support

GitHub support

Configure the integration

Ensure the required GitHub Actions are allowed

Import the integration repository

Download the app

Setting up GitHub secrets for scanning

Configure Veracode API ID and secret for Static Analysis

Configure SCA agent token

How scanning works

Specify repositories to scan

Exclude specific repositories

Include only specific repositories

`veracode.yml` configurations

Use your source repositories' build steps

Configure integration for individual repositories

Trigger on-demand scanning with GitHub issues

View results in GitHub

Status checks

Code scanning alerts

GitHub Issues

Reviewing results in the Veracode Platform