The integration of static application security testing (SAST) and software composition analysis (SCA) directly into the developer workflow is a critical component of modern DevSecOps strategies. Checkmarx provides two distinct mechanisms to integrate its security scanners with GitHub: the legacy CxFlow-based action and the newer Checkmarx One GitHub Action. These integrations allow development teams to trigger scans for SAST, SCA, Infrastructure as Code (IaC) Security, API Security, Container Security, and Software Supply Chain Security directly from GitHub workflows. By embedding these checks early in the Software Development Life Cycle (SDLC), organizations can identify vulnerabilities in custom code and open-source dependencies before they reach production, thereby reducing remediation costs and improving overall code quality.
The primary distinction between the available tools lies in their underlying architecture and target platforms. The Checkmarx One GitHub Action serves as a wrapper around the Checkmarx One CLI tool, designed for the cloud-native Checkmarx One platform. In contrast, the Checkmarx CxFlow GitHub Action is a wrapper around the CxFlow orchestration layer, designed for legacy on-premise or cloud-hosted Checkmarx SAST and CxSCA servers. Understanding the specific capabilities, configuration requirements, and deprecation status of these tools is essential for engineering teams looking to establish a robust security pipeline.
Checkmarx One GitHub Action Architecture
The Checkmarx One GitHub Action is the current recommended method for integrating security scanning with GitHub repositories for users of the Checkmarx One platform. This action functions as a high-level wrapper around the Checkmarx One Command Line Interface (CLI) tool. The operational workflow involves the action creating a zip archive of the source code repository and uploading it to the Checkmarx One platform for analysis. This approach abstracts the complexity of manual CLI usage while retaining the full functionality and flexibility of the underlying tool.
The action supports a comprehensive suite of security scans, including:
- SAST for identifying vulnerabilities in custom code
- SCA for detecting open-source vulnerabilities and license issues
- IaC Security for scanning infrastructure definitions
- API Security for analyzing API endpoints
- Container Security for inspecting container images
- Software Supply Chain Security for broader dependency analysis
One of the primary advantages of this integration is its flexibility in triggering scans. The GitHub Action can be configured to initiate scans based on specific repository events, such as a push to a branch or the creation of a pull request. Engineers can further refine these triggers to target specific branches, ensuring that scans only run when necessary. Additionally, the workflow supports the inclusion of pre-scan and post-scan steps. For instance, a pre-scan step might include logic to screen commits, verifying whether the changes made warrant the computational cost of a new full scan. This optimization helps prevent redundant scanning of unchanged codebases.
It is important to note that while the GitHub Action provides a convenient interface for triggering scans, an alternative integration method exists where the connection is established directly from the Checkmarx One platform to GitHub Cloud. This direct integration method operates outside the GitHub Actions framework and may be preferable for organizations with specific platform-level requirements.
Legacy CxFlow GitHub Action and Deprecation Status
The Checkmarx CxFlow GitHub Action, found under the repository path checkmarx-ts/checkmarx-github-action, represents an older generation of integration tools. This action serves as a CLI wrapper to trigger Checkmarx SAST (CxSAST) or Open Source Analysis (OSA/SCA) scans. It launches scans using the latest version of CxFlow through Docker containers. CxFlow itself is an orchestration tool that automates scan initiation, results management, and feedback integration into various tools, including GitHub and Jira.
Despite its historical significance, the Checkmarx CxFlow GitHub Action is marked for deprecation. Official documentation explicitly states that this action will be deprecated soon and advises users to migrate to the newer checkmarx-cxflow-github-action (available at github.com/checkmarx-ts/checkmarx-cxflow-github-action) as soon as possible. This migration is particularly relevant for organizations that have not yet transitioned to the Checkmarx One platform but still rely on the traditional Checkmarx SAST and CxSCA servers.
The legacy action supports Alpine OS environments. For teams operating in Debian-based environments, a separate action named checkmarx-cxflow-github-debian is required. This distinction in operating system support highlights the need for careful environment configuration when implementing legacy scanners.
Key features of the CxFlow-based action include:
- Enterprise-grade static analysis for custom code (SAST)
- Next-generation software composition analysis (SCA)
- Multi-scanner support allowing simultaneous SAST and SCA execution
- SARIF output generation for compatibility with GitHub Code Scanning
- Flexible bug tracking integration with GitHub Issues, Pull Request comments, or Jira tickets
Configuring GitHub Workflows for Checkmarx Scans
Integrating either the Checkmarx One action or the CxFlow action into a GitHub repository involves editing workflow files located in the .github/workflows directory. These YAML files define the triggers, runners, and steps required to execute the scans.
To create a new workflow for Checkmarx One, users navigate to the Actions tab in their GitHub repository and select the option to set up a workflow themselves. The default workflow file is named main.yml, but this can be renamed to something more descriptive, such as CheckmarxScan.yml. Within the code editor, developers customize triggers and branches. The actual integration snippet is obtained from the GitHub Marketplace by searching for "Checkmarx AST Github Action." The provided YAML snippet is then pasted into the steps section of the workflow, below the runs-on directive. Alignment and indentation must be adjusted to ensure valid YAML syntax.
If the workflow includes the SCA Resolver as part of the scan process, the script requires additional modification to accommodate the resolver's specific execution parameters.
For the legacy CxFlow action, the configuration involves defining inputs, secrets, and filters within the YAML file. The action requires valid credentials to authenticate with the Checkmarx server. A critical prerequisite for both integrations is network connectivity. The GitHub Action agents must be able to connect to the Checkmarx server or platform. To avoid connectivity issues, especially in restrictive network environments, organizations are advised to use self-hosted runners for GitHub Actions. For on-premise runners, it is essential to ensure that the Checkmarx server IP addresses are whitelisted in the runner's firewall configuration.
Reviewing Results and Feedback Integration
The value of automated security scanning is realized when the results are effectively communicated to developers. Checkmarx integrations provide multiple mechanisms for displaying scan results within the GitHub ecosystem, ensuring that security feedback is visible at the point of development.
When a workflow is configured to scan on pull requests, a report of the Checkmarx scan is displayed within the GitHub Pull Request Overview. This provides immediate visibility into new vulnerabilities introduced by the proposed changes. If the --bug-tracker option is configured to use GITHUBPULL in the params field of the YAML file, specific issues found by CxSAST and CxSCA are opened as individual GitHub Issues. This allows for granular tracking and assignment of remediation tasks to specific developers.
For a more centralized view, Checkmarx supports Code Alerting via SARIF (Static Analysis Results Interchange Format) output. By enabling this feature, scan results are uploaded to GitHub's Security Tab. This requires adding an additional step to the YAML file that uploads the generated cx.sarif file to GitHub. Once uploaded, these results appear as code scanning alerts, allowing security teams to review and triage vulnerabilities in a unified interface.
The following table summarizes the available result integration methods and their configuration requirements:
| Integration Method | Configuration Requirement | Visibility Location |
|---|---|---|
| Pull Request Comment | Trigger on pull_request event |
Pull Request Overview |
| GitHub Issues | Set --bug-tracker to GITHUBPULL in params |
GitHub Issues List |
| Code Scanning Alerts | Upload cx.sarif file via additional step |
GitHub Security Tab |
Triggering Scans and Workflow Management
GitHub Actions workflows are controlled by YAML files that respond to specific events. Common triggers include push events to specific branches (such as the main branch) and pull request events. These triggers can be automated to run on every commit or pull request, ensuring that no code change goes unscanned. Additionally, workflows can be configured to run manually, providing developers with the ability to initiate on-demand scans during debugging or investigation phases.
The choice of trigger strategy significantly impacts the feedback loop. Scanning on pull requests ensures that vulnerabilities are caught before code is merged, enforcing a "shift-left" security philosophy. Scanning on commits to the main branch provides a safety net for direct pushes and ensures that the primary codebase remains compliant with security policies.
For organizations using the legacy CxFlow action, compatibility with Checkmarx SAST version 9.x and Checkmarx CxSCA is confirmed. The workflow must include the necessary secrets, such as API tokens, which are securely stored in the GitHub repository settings and referenced in the action configuration.
Conclusion
The integration of Checkmarx security scanners into GitHub workflows represents a mature approach to automating application security. While the ecosystem includes both the modern Checkmarx One GitHub Action and the legacy CxFlow-based actions, the industry trajectory points toward the former. The Checkmarx One action offers a broader range of scanning capabilities, including API and container security, and provides a streamlined wrapper around the CLI tool. However, for organizations still operating on legacy infrastructure, the CxFlow action remains a viable, albeit temporary, solution.
Successful implementation requires careful attention to workflow configuration, particularly regarding trigger events, network connectivity for self-hosted runners, and the method of result dissemination. By leveraging SARIF output for GitHub Code Scanning and integrating bug tracking directly into GitHub Issues and Pull Requests, teams can ensure that security findings are actionable and visible to the developers who can fix them. As the legacy CxFlow action approaches deprecation, migration to the supported Checkmarx One action or the updated CxFlow action is necessary to maintain compliance and access to the latest security features.