Execution - checkmarx-ltd/cx-flow GitHub Wiki
Refer to Webhook Registration for instructions on registering for WebHooks. To launch the WebHook WebService, select the relevant jar file and run the following command:
java -jar cx-flow-<ver>.jar
The relevant configuration is determined by the application.yml file that resides in the same directory as the jar file, or if an explicit configuration is set to override as defined in the command line as follows:
java -jar cx-flow-<ver>.jar --spring.config.location=/path/to/application.yml --web
The CxFlow docker images on Docker Hub checkmarx/cx-flow contain the latest and previous versions of CxFlow.
docker pull checkmarx/cx-flow
docker run --env-file=.checkmarx --name=cx-flow --detach -p <host port>:8080 checkmarx/cx-flow
To provide JAVA_OPTS to the docker image, the entrypoint of the docker image can be overridden in the following way
docker run --env-file=.checkmarx --entrypoint java checkmarx/cx-flow:latest -Xms512m -Xmx4096m -XshowSettings:vm -jar /app/cx-flow.jar
The env-file provides the necessary overrides during the bootstrap process - urls, credentials, etc - sample below. In addition, you can use --env-file <(env)` on *Unix hosts to move the entire environment from the host into the Docker container.
BITBUCKET_TOKEN=<user>:<token>
BITBUCKET_URL=http://xxxxxx:7990
BITBUCKET_API_PATH=/rest/api/1.0/
BITBUCKET_WEBHOOK_TOKEN=XXXXXXX
CHECKMARX_BASE_URL=https://xxxxxxxx
CHECKMARX_CLIENT_SECRET=XXXXXXXXXX
CHECKMARX_PASSWORD=XXXXXXXX
CHECKMARX_USERNAME=XXXXXXXX
CHECKMARX_TEAM=\CxServer\SP\Checkmarx
GITHUB_TOKEN=XXXXXXXXXXXXXX
GITHUB_WEBHOOK_TOKEN=XXXXXXXX
GITLAB_TOKEN=XXXXXXXX
GITLAB_WEBHOOK_TOKEN=XXXXXXXX
JIRA_TOKEN=XXXXXXX
JIRA_USERNAME=XXXXXX
JIRA_URL=https://XXXXXXXXX
JIRA_PROJECT=SS
Note: In order to highly customize the yaml configuration for CxFlow in a Docker environment, use this docker image as a base and add custom configuration. Alternatively build from source (Docker files are found in the git repository).
CxFlow can be integrated via command line using several ways. The table below lists command line arguments and flags to help drive the different execution flows and overrides.
| Option | Description |
|---|---|
--spring.config.location |
Override the main application.yml/properties file for the application. Defaults to the application.yml packaged within the jar |
--parse |
Indicates that a result XML file from Checkmarx is provided (–f is also mandatory). No value provided (flag) |
--project |
Indicates that we would like to retrieve the latest scan results for a given team/project and provide feedback (defect / issue tracking). |
--batch |
Indicates that the entire instance or a given team is iterated through and the latest results are retrieved for each project and feedback is provided (defect/issue tracking) |
--cx-team |
Used to override the team that is used as a base team (optionally defined globally in the yaml configuration). This team is used when creating a project in Source/Scan (zip) mode as well as the team to use when retrieving latest project results in project/batch modes (--project/--batch) |
--namespace |
Repository group (GitLab)/organization (GitHub)/namespace (BitBucket). Used as higher level grouping of repositories. Used along with repo-name and branch for tracking purposes (Jira only). If these three components are not present, an application attribute must be passed (--app). These values are stored in a tracking label within Jira. This value is also stored in the body of the issue. |
--repo-name |
Name of the repository. Used along with repo-name and branch for tracking purposes (Jira Only). If these three components are not present, application attribute must be passed (--app). These values are stored in a tracking label within Jira. This value is also stored in the body of the issue. |
--branch |
Branch used along with repo-name and branch for tracking purposes (Jira only). If these three components are not present, then an application attribute must be passed (--app). These values are stored in a Tracking label within Jira. This value is also stored in the body of the issue. |
--app |
Alternatively used for Tracking purposes. This value is also stored in the body of the issue. |
--repo-url |
Required for issues tracking with GitHub Issues or GitLab Issues. This value is also stored in the body of the issue. |
--f |
File to be processed. This the output from Checkmarx CLI, Jenkins/Bamboo Plugin, etc. |
--exclude-files |
Files to be excluded when running --scan CLI execution |
--exclude-folders |
Folders to be excluded when running --scan CLI execution |
--config |
Optional: Configuration override file (JSON) |
--bbs |
Optional: Indicates that the repository is of the BitBucket Server type as BB Server follows a different URL file format |
--bb |
Optional: Indicates that the repository is of the BitBucket Cloud type as BB Cloud follows a different URL file format (also different from BB Server) |
--bug-tracker |
Optional: Used to override the globally configured bug tracker as defined by the base YAML configuration. The name is case-sensitive and must match the exact bean name as specified in the --bug-tracker-impl list of available implementations. JIRA is the only option that is not on this list, but can be used as well |
--spring.config.location |
Path to application.yml. This file contains the global configuration for CxFlow. It is only required, if the jar file and the application.yml file are not in the current working directory. Refer to the Spring Boot Documentation (section 24.3) |
--offline |
If this flag is raised, the Checkmarx instance is not contacted. This means that no issue description is provided and Checkmarx custom fields cannot be used |
--blocksysexit |
Optional: Mainly for build/test purposes. Avoid System.exit() in the code and exit with java exception |
--alt-project |
Name of the project in ADO. This parameter is required in addition to cx-project parameter. |
--project-custom-field |
Specify a project-level custom field to be set if a project is created or the checkmarx.settings-override property is set. The custom field is specified as name:value (i.e., the field name cannot include a colon). This option may be specified multiple times to set multiple fields.In CLI mode these values can be passed as --project-custom-field="jira-project":"abc" --project-custom-field="jira-issuetype":"issue" |
--scan-custom-field |
Specify a scan-level custom field. The custom field is specified as name:value (i.e., the field name cannot include a colon). This option may be specified multiple times to set multiple fields. |
--default-branch |
Name of the default branch which will be used to created licensed project in CxSAST, so that scans from any branch provied by --branch creates a branched project in CxSAST and not a licensed project. |
--branch-protection-enabled |
Enable branch protection when running in command line mode. |
--scanId |
Can be used with project mode to retrive unique scanId for a given team/project and provide feedback (defect / issue tracking).. |
--sca.team |
This parameter can be use to give team name to SCA projects. |
--merge-id |
This parameter can be use to provide merge id by command line parameter. Cxflow will update comments in respected merge id provided. |
- By using the CLI, any parameter in the application.yml file can be given a value.
- To provide value for parameter present in application yml file through CLI, follow below example
- Section in YML
github:
webhook-token: XXXXXsssss
token: XXXXX
url: https://github.com
api-url: https://api.github.com/repos/
false-positive-label: false-positive
block-merge: true-
The value for
tokeningithubsection can be provided in the following way: -
--github.token=<GH_TOKEN_VALUE> -
Thresholds and Filters via command line can be provided in the following way:
-
--cx-flow.thresholds.high=<High threshold count> --cx-flow.filter-serverity=High --cx-flow.filter-serverity=Medium -
Examples of cx-flow CLI
# Scanning a local repository with cx-flow cli
java -jar cx-flow-<ver>.jar --scan --spring.config.location="location/of/application.yml" --f="location/of/project/on/local" --cx-team="/CxServer" --cx-project="project-name" --app="project-name"
# Scanning a remote repositiory with cx-flow cli
java -jar cx-flow-<ver>.jar --spring.config.location="location/of/application.yml" --scan --github --repo-name="repo-name" --namespace="namespace" --repo-url="repo-url" --branch="master"
java -jar cx-flow-<ver>.jar \
--parse \
--namespace=checkmarx \
--repo-name=Riches.NET \
--repo-url=https://github.com/xxxx/xxxx.git \
--branch=main \
--app=ABC \
--f=Checkmarx/Reports/ScanReport.xml
java -jar cx-flow-<ver>.jar --batch
Example for Checkmarx v9.x:
java -jar cx-flow-<ver>.jar --batch --cx-team="CxServer/SP/Checkmarx/development"
Example for Checkmarx v8.x:
java -jar cx-flow-<ver>.jar --batch --cx-team="CxServer\SP\Checkmarx/development"
Following Command can be used to retrieve the latest scan results for a given team/project and provide feedback (defect / issue tracking).
Example for Checkmarx v9.x:
java -jar cx-flow-<ver>.jar \
--project \
--cx-team="CxServer/SP/Checkmarx/Test" \
--cx-project="riches-main" \
--app=AppName
Example for Checkmarx v8.x:
java -jar cx-flow-<ver>.jar \
--project \
--cx-team="CxServer\SP\Checkmarx\Test" \
--cx-project="riches-main" \
--app=AppName
Following Command can be used to retrieve the results for unique scanId for a given team/project and provide feedback (defect / issue tracking).
java -jar cx-flow-<ver>.jar \
--project \
--scanId=<unique scanId>
--cx-team="CxServer/SP/Checkmarx/Test" \
--cx-project="riches-main" \
--app=AppName
docker pull checkmarx/cx-flow
docker run checkmarx/cx-flow <applicable parameters>