Policy Integration

[cx-nathan-leach]

Describe the problem

Checkmarx One has the ability to apply one or more defined policies to a project. Each policy can be configured to break the build. These policies and the build-break flag should be considered by CxOneFlow in PR feedback. The logic for integration is SCM-specific but generally has these outcomes:

• The PR is blocked from merging while the scan is executing.
• The build-break flag can optionally block the PR merge upon policy violation.
• Scan results are integrated into the PR evaluation tooling provided with the SCM.

Proposed solution

The current YAML configuration for feedback is available for enabling pull request feedback. This will not change; a new element ignore-break-build will be added that defaults to true so that current PR workflow configurations do not change on upgrade. When set to false, the appropriate method for blocking PR merges on policy failure will be used for the SCM.

The field use-scm-result-reporting will default to true so that the current PR workflow configurations do not change on upgrade. When true, the feedback summary and details are provided in the comments regardless of SCM provided methods for reporting vulnerabilities in the PR. When set to false, the feedback integration mechanism will use any SCM provided integration intended to make the PR review integrated with the SCM PR review mechanism.

The field wait-for-scan will default to false so that the current PR workflow configurations do not change on upgrade. When true, the status of the scan reflected in the SCM integration will be set so that a merge can not complete until the scan completes. If set to false, the status of the scan execution will be set such that the PR merge can be executed (with any post-scan updates still updating in the PR record).

An example of a configuration snippet is below:

feedback:
  pull-request:
    ... # Existing options
    wait-for-scan: true # Default to false
    ignore-break-build: false # Default to true
    use-scm-result-reporting: true # Defaults to false

Additional Details

This is a basic overview of each integration point per SCM. Some of the SCM integration may require specific integration con figuration options that may not be presented in detail here. The intent here is to understand the high-level approach for each supported SCM type. Specific configuration for an SCM can be documented in the manual.

GitHub "Commit Status"

"Commit Status" is the integration point available when not using GitHub apps as the integration with CxOneFlow. It shows the status of the pending scan execution and any final outcome. This solution would be a change to the current integration method to be used when not using a GitHub app integration.

When ignore-break-build is false, the commit status indicates the scan is pending which blocks the PR from merge. When the scan completes, policy failures are evaluated. If any assigned policy fails and indicates the break-build configuration of the policy is enabled, the state of the status is set to failure which blocks the PR merge.

When ignore-break-build is true, the Commit Status updates to indicate scan progress and policy failure but the status is always success. This allows the PR to merge while the comments continue to update after the scan is completed.

A link to the scan id of the scan replaces the annotation message indicating that a scan has started. A comment is added/updated with a scan result summary once the scan is complete. The names of the failed policies, if any, are added to the summary section of the result message.

GitHub "Checks"

"Checks" are available only when using a GitHub app integration with CxOneFlow. The Checks display status in the conversation view the same as Commit Status and a failure conclusion will block the PR merge. The results summary display can be viewed on the Check run details tab rather than place it in the PR conversation.

There are also "actions" available in the form of buttons that show on the Checks display. This will be useful for actions like:

• "Cancel Scan" while scan is executing.
• "Refresh Results" to refresh the results/policy evaluation after triage.

The Check also has the ability to request the check is "re-run" which could cause the scan to execute again.

The Check run has annotations that could be used to indicate policy failure details.

When using the GitHub app integration in CxOneFlow, this option would be the default

Bitbucket Data Center "Code Insights"

Code Insights is an integration mechanism for BBDC that can be used as logic for blocking a PR merge until a Code Insights report is provided with a scan. This requires setup on the BBDC project to set a "report key" (which will need to be configured in CxOneFlow) and some policies about how the Code Insights results block the PR merge. These policies may be redundant if used with Checkmarx One policies, but overall they will not affect the CxOneFlow logic for blocking PR merges.

The main configuration needed for Code Insights is to block PR merge until the Code Insights report is filed. At the end of the scan, in lieu of PR conversation thread comments, the Code Insights report is submitted with the scan results. Review of the summary of reported vulnerabilities is then available in the Code Insights report.

Gitlab integration

No specific integration will be performed for Gitlab. External status checks are only available with Gitlab Ultimate. Future work may support the external status checks pending availability of Gitlab Ultimate.

Azure DevOps integration

Branch policies can set "Required Status Checks" that makes the PR merge block until a PR status with a matching name and optional genre has the status succeeded.

Reported vulnerabilities and failed policies are reported as comments in the PR thread.