What is it?
Quick Start
Configuration
Server Configuration
CxFlow Configuration
Checkmarx Environment Configuration
Gotchas!

CxFlow is a springboot application that can run anywhere Java is installed. CxFlow glues together Checkmarx CxSAST, CxSCA, and CxOSA scans with feedback to issue tracking systems via webhooks triggered by SCM events. CxFlow can also run as a CLI tool embedded in CI/CD pipelines.

This quick start guide describes how to trigger a CxSAST scan on a Pull Request and a Push to a protected Github branch. Pushes to a protected branch will create GitHub Issues from the scan results.

Requirements:

• Create a folder called CxFlow
• Into this folder, download the latest CxFlow .jar for JDK8
  https://github.com/checkmarx-ltd/cx-flow/releases
  Note This guide is using CxFlow version 1.5.4, if you download another version, input your version in the command below
• In the folder create a file titled application.yml
• Add the text below to the application.yml file replacing any values enclosed in ###<>### with your appropriate value
  Under the Checkmarx heading, you should enter your service account's username, password, and confirm the base-url. Under the Github heading please enter your Github token and web-hook token if you have entered a value for the web-token different from this guide's value of 12345. Finally, enter another port if you are using a port other than 8982.
  Note This .yml file is for CxSAST version 8.9. For later versions, navigate to the 9.0 link on the side bar
  Note The client-secret value included here is the correct value for CxSAST and is not actually a secret value. It is the OIDC client secret used for API login to Checkmarx.

server:
  port: 8982
logging:
  file: flow.log

cxflow:
  bug-tracker: GitHub
  bug-tracker-impl:
  - GitHub
  branches:
  - master
  filter-severity:
  filter-category:
  - SQL_Injection
  - Stored_XSS
  - Reflected_XSS_All_Clients
  filter-cwe:
  filter-status:
  #   - Urgent
  #   - Confirmed
  #mitre-url: https://cwe.mitre.org/data/definitions/%s.html
  #wiki-url: https://custodela.atlassian.net/wiki/spaces/AS/pages/79462432/Remediation+Guidance
  codebash-url: https://checkmarx-demo.codebashing.com/courses/

checkmarx:
  username: ###<username>###
  password: ###<password>###
  client-secret: 014DF517-39D1-4453-B7B3-9930C563627C
  base-url: ###<CxSAST url or http://localhost>###
  team: \CxServer\SP\Company
  url: ${checkmarx.base-url}/cxrestapi
  #WSDL Config
  portal-url: ${checkmarx.base-url}/cxwebinterface/Portal/CxWebService.asmx
  sdk-url: ${checkmarx.base-url}/cxwebinterface/SDK/CxSDKWebService.asmx
  portal-wsdl: ${checkmarx.base-url}/Portal/CxWebService.asmx?wsdl
  sdk-wsdl: ${checkmarx.base-url}/SDK/CxSDKWebService.asmx?wsdl


github:
  webhook-token: 12345
  token: ###<githubtoken>###
  url: https://github.com
  api-url: https://api.github.com/repos/
  false-positive-label: false-positive
  block-merge: true

• If following this guide for demo purposes, you can use ngrok to generate a resolvable address for your CxSAST manager. This guide includes ngrok in its examples
  • Download ngrok from https://ngrok.com/download and unzip to the CxFlow folder
  • Start ngrok on port 8982 by opening CMD and entering the following command:

ngrok http 8982

• Create an account at www.github.com
• Create a public repository titled CxFlowGithub
• Import code from your favorite small demo codebase on github. This guide will use
  https://github.com/psiinon/bodgeit
• Create a token by clicking on your profile in upper right corner > settings
  • Click Developer settings > Personal Access Tokens > Generate New Token
  • Give the token a name, for example cxFlow-minimal, and both repo:status and public_repo scopes.
  • Ensure "Issues" are enabled on the project Settings > Options > Features > Issues
  • Copy this token and keep it safe. It should be posted into the token <> of the application.yml
• Once the .yml is completely filled out, start CxFlow in webhook mode by opening CMD prompt/shell, navigate to your CxFlow directory (created above) and entering the following, after updating the path\to\CxFlow folder:

java -jar cx-flow-1.5.4.jar --spring.config.location="<path\to>\CxFlow\application.yml" --web

• Create a webhook by selecting your profile and selecting the repo you just created
  • Navigate to Settings > Webhooks > Add Webhook and fill in the details
    • Payload URL: ngrok example: http://4d91e7ed.ngrok.io
    • Content type: application/json
    • Secret: Webhook token from .yml file, in this example 12345
    • Select Events: Pull Requests, Pushes
  • Click Add Webhook, there should be a checkmarx next to the hook name now
• Open your IDE of choice. This demo will use IntelliJ
  • Check out code using Check out from Version Control, input the URL for your repo example:
    https://github.com/<username>/CxFlowGithub
  • Open README.md and add a line, example: CxFlowMasterPush-Test1
  • Commit to local git repo and push to origin with comments by clicking the following: VCS > Git > Commit File enter a message like CxFlow push to a protected branch
  • Click commit and push
  • Click Push and enter Github credentials on popup. Username is your username, password is the token you created above.
• Navigate to the Checkmarx web portal. You should see a new scan in the CxSAST queue
  Notice the project name is the RepoName-Branch
  Notice the team is the Github organization. This is set by the team line in the .yml file. It auto creates a team if it does not exist. This can be overridden in the config file with the multi-tenant setting. Please see the CxFlow configuration page for more information.
• When the scan finishes, you should see issues on the Issue tab of your Github repo
  https://github.com/<username>/CxFlowGithub/issues
• Examine the following issue CX SQL_Injection @ roost/basket.jsp [master]
• Open the Checkmarx link and examine the finding
• We will now trigger CxFlow from a Pull Request to a protected branch, from branch security-fix to master
• Open IntelliJ and create a new local branch called security-fix VCS > Git > Branches > New Branch
• Type security-fix and click ok
• Open basket.jsp under the root folder and replace lines 53-55 with the following

//Statement stmt = conn.createStatement();
//Security Fix
PreparedStatement preparedStatement = con.prepareStatement(sql);
try {
//ResultSet rs = stmt.executeQuery("SELECT * FROM Baskets WHERE basketid = " + basketId);
String sql = "SELECT * FROM Baskets WHERE basketid =?");
preparedStatement.setString(1, basketId);
ResetSet rs = preparedStatement.executeQuery();

• add the following to line 7 to import the correct package

<%@ page import="java.sql.PreparedStatement" %>

• Save the file, commit to the local repo and push to origin:
  • File > Save All
  • VCS > Git > Commit File and add commit message like added prepared statement on line 55
  • Click Commit and Push, then Push
• Navigate to Github
  • Navigate to Pull Requests
  • Click Compare and Pull Request > Create Pull Request
  • Alternatively you can create the pull request through the IDE. In IntelliJ click VCS > Create Pull Request
• In Github there will be some checks that have not finished yet - Checkmarx Scan
• In the Checkmarx web portal there will be a new CxSAST scan where the project name is RepoName-Branch
  • Once the scan finished you can see the post in the Github merge pull request comments with all the vulnerabilites found
  • The basket.jsp SQLi is gone
  • Click Merge Pull Request > Confirm Merge to accept the risk CxSAST has posted in the comments
• After confirming the pull request, there will be a new CxSAST scan in the Checkmarx web portal for the master branch
• In Github Issues there will be one fewer vulnerability
• In the Checkmarx web portal, the CxFlowGithub-master project will now have both solved and recurrent issues.

Note This information is duplicated on the Configuration page

No* = Default is applied

• Make sure the path to Git is configured in the Checkmarx web portal under Settings > Application Settings > General
• The guides here were written for CxSAST version 8.9. For version 9.0+ please see the 9.0 update page. For example, team path now uses / instead of \
• Tokens have a maximum lifespan of 365 days. Having a secret rotation cycle in place is an important practice
• It is important to choose an encryption algorithm appropriate for your deployment
• The automatic team name creation and assignment can be overwritten using the multi-tenant parameter in the .yml file