Bug Trackers and Feedback Channels - RDR3/cx-flow GitHub Wiki

• Understanding the Data
• Jira
  • Priorities
  • Transitions
  • Fields
• Custom Bug trackers
• Azure DevOps Work Items
• GitLab Issues
• GitLab Security Dashbaord
• GitHub Issues
• Rally Issues
• Service Now
• CxXML
• Json
• CSV
• NONE|WAIT

Understanding the Data

Checkmarx results are processed according to the following scheme.

The breakdown of the XML includes the following:

Query→ Result→ Path

Issues are filtered based on the criteria found in the main configuration of CxFlow along with any particular overrides (severity, category, cwe, status). From the XML structure, the Source identifier is the main tracking element. The Vulnerability+File path is the key, and as additional line references are found for the same key, it is appended to the same issue reference. See the development section for details on the ScanResults/Issue object structure.

The best fix location would be a more appropriate value to track, which is currently unavailable.

Jira

Jira has the most complex configuration use case as it supports a variety of custom fields, custom workflows and custom transitions.

jira:
   url: https://xxxx.atlassian.net
   username: xxxx
   token: xxxx
   project: SS
   issue-type: Application Security Bug
   priorities:
      High: High
      Medium: Medium
      Low: Low
         informational: Lowest
   pen-transition: In Review
   close-transition: Done
   open-status:
      - To Do
      - In Progress
      - In Review
   closed-status:
      - Done
   fields:
#    - type: cx #[ cx | static | result ]
#      name: Platform # cx custom field name | cwe, category, severity, application, *project*, repo-name, branch, repo-url, namespace, recommendations, loc, site, issueLink, filename, language
#      jira-field-name: Application
#      jira-field-type: label #[ security | text | label | single-select | multi-select ]
     - type: result
       name: application
       jira-field-name: Application
       jira-field-type: label
     - type: result
       name: cve
       jira-field-name: CVEs
       jira-field-type: label
     - type: result
       name: cwe
       jira-field-name: CWEs
       jira-field-type: label
     - type: result
       name: category
       jira-field-name: Category
     - type: result
       name: loc
       jira-field-name: LOC
       jira-field-type: label
       jira-default-value: XXXXX

Priorities

priorities:
  High: High
  Medium: Medium
  Low: Low
  informational: Lowest

The value on the left side reflects the Checkmarx severity. The value to the right reflects the priority assigned to the respective issue in Jira.

Transitions

It is very important that issues driven by CxFlow have the ability to transition to and from the open or close transition states regardless of what state the issue is in. In the event that an issue cannot use the appropriate transition defined, it will fail.

open-transition: In Review`
close-transition: Done*`
open-status:`
  - To Do`
  - In Progress`
  - In Review`
closed-status:`
  - Done`

• open-transition → this is the transition to apply to an issue when re-opening an issue
• close-transition → this is the transition to apply to an issue when closing an issue
• open-status → this is a list of the available status an issue can be in that indicate the issue is still in open state according to Jira
• closed-status → this is a list of the available status an issue can be in that indicate the issue is still in closed state according to Jira

Fields

• type
  • static: Used for static values (specifically requires a jira-default-value to be provided)
  • cx: Used to map specific Checkmarx Custom Field values
  • result: Used to map known values from Checkmarx results or repository/scan request details. Refer to the Result values below.
• name: If cx reflects the type, it is the name of the custom field within Checkmarx
  • If result is provided as type, the name must be one of the following:

application - Command line option --app
project - Command line option --cx-project
namespace - Command line option --namespace
repo-name - Command line option --repo-name
repo-url - Command line option --repo-url
branch - Command line option --branch
severity - Severity of issue in Checkmarx
category - Category of issue in Checkmarx
cwe - CWE of issue in Checkmarx
recommendation - Recommendation details based on Mitre/Custom Wiki
loc - csv of lines of code
issue-link - Direct link to issue within Checkmarx
filename - Filename provided by Checkmarx issue
language - Language provided by Checkmarx issue
similarity-id - Cx Similarity ID

• jira-field-name - Custom field name in Jira (readable name, not Custom field name)
• jira-field-type - Type of custom field in Jira:
  • label (if using static or cx values, the CSV format is used and broken into multiple labels)
  • text (applies to many custom field types: url, text box, text, etc
  • multi-select (the CSV format is used and broken into multiple select values)
  • single-select
  • security (used for issue security levels)
• jira-default-value - Static value if no value can be determined for the respective field (Optional)

Custom Bug Trackers

Refer to the development section for the implementation approach. To use one of the Custom Bug Trackers, the cx-flow tag within the application yaml config must have the specified Spring Boot bean under bug-tracker-impl:

cx-flow:
   contact: [email protected]
   bug-tracker: Json
   bug-tracker-impl:
     - CxXml
     - Csv
     - Json
     - GitLab
     - GitHub

Valid options for bug-tracker-impl are currently the following ones:

• CxXML
• Csv
• Json
• GitHub
• GitLab
• Azure
• GitLabDashboard

Azure DevOps WorkItems

Azure DevOps workitems only supports an issue body/description. Custom/template field values are not available at present. The available issue-type values are built/tested around issue and impediment (Scrum)

GitLab Issues

GitLab Issues leverages the same configuration as specified for WebHook listeners → API token (token) and valid urls are required

gitlab:
   webhook-token: XXXX
   token: xxx
   url: https://gitlab.com
   api-url: https://gitlab.com/api/v4/
   false-positive-label: false-positive
   block-merge: true

GitLab Security Dashboard

cx-flow:
   bug-tracker: GitLabDashboard
   bug-tracker-impl:
     - GitLab
     - GitLabDashboard
   filter-severity:
     - High
   mitre-url: [https://cwe.mitre.org/data/definitions/%s.html](https://cwe.mitre.org/data/definitions/%s.html)
   break-build: true
  
gitlab:
   file-path: ./gl-sast-report.json

GitHub Issues

GitHub Issues leverages the same configuration as specified for WebHook listeners → API token (token) and valid URLs are required.

github:
   webhook-token: xxxx
   token: xxxx
   url: https://github.com
   api-url: https://api.github.com/repos/
   false-positive-label: false-positive
   block-merge: true

Rally Issues

Rally Issues require the configuration displayed below. In addition to the API security token the Rally API requires that you provide both a project ID and a work space ID. The Rally plugin uses tags to track defects.

rally:
   token: xxxx
   rally-project-id: xxxx
   rally-workspace-id: xxxx
   url: [https://rallydev.com](https://rallydev.com)
   api-url: [https://rally1.rallydev.com/slm/webservice/v2.0](https://rally1.rallydev.com/slm/webservice/v2.0)

Locating Rally Project and Workspace IDs can be tricky, but the easiest way to locate the values is by looking up the URLs in your browser as there are not any screens that directly expose the values. To find the Project ID, simply log into Rally and you are taken to your default project. If you look at the URL you see the Projects OID, example:

Remember that projects are associated with workspaces and you can find the workspace setup at the projects screen. Simply go to Setup by clicking the wrench icon in the upper right-hand corner, example:

From the setup screen click on 'Workspaces & Projects', you will see a list of workspaces, example:

Click the workspace that you are are interesting in, in this case Checkmarx. You will be taken to the Workspace setup screen and now you find the associated OID by looking at the URL, for example:

If you are logged in to Rally, you can generate your API token here. To do so, click 'Create New API' on the API Keys screen as illustrated in the example below:

From that dialog box, just name your key and provide it with Full Access:

The API key is created and the token appears on the API Keys screen. Now you have all the required information to configure the Rally bug tracker.

Service Now

Integration with Incident records: Coming soon.

CxXML

The XML bug-tracker (defined as CxXml) is useful, if you want to retrieve the latest scan results per project (batch mode) from Checkmarx per project, Team, or the entire instance. This is the original XML report provided by Checkmarx.

Note: The Checkmarx config block must specify preserve-xml as true for this feedback type.

checkmarx:
   ...
   ...
     preserve-xml: true
cx-xml:
   file-name-format: "[NAMESPACE]-[REPO]-[BRANCH]-[TIME].xml"
   data-folder: "C:\\tmp"

The file system path as well as the file naming format is required.

Json

The JSON bug-tracker (defined as Json), is useful if you would like to retrieve all of the latest scan results per project (batch mode) from Checkmarx per project, Team, or entire instance. This is the JSON representation of the ScanResults object, which include issues based on the filtering specified in the main config block (cx-flow).

json:
   file-name-format: "[NAMESPACE]-[REPO]-[BRANCH]-[TIME].xml"
   data-folder: "C:\\tmp

The file system path and the file naming format are required.

CSV

checkmarx:
  ...
  ...
    preserve-xml: true
 
cx-xml:
  file-name-format: "[NAMESPACE]-[REPO]-[BRANCH]-[TIME].xml"
  data-folder: "C:\\tmp"

The file system path and the file naming format are required.

NOTE: All of the file based outputs have a file-name-format attribute, which allows for dynamic naming substitution. File name follows a substitution pattern with the following elements:

[APP] → Application

[TEAM] → Checkmarx Team ( \ is replaced with _ in the filename)

[PROJECT] → Checkmarx Project [PROJECT] → Checkmarx Project

[NAMESPACE] → Checkmarx Project [PROJECT] → Org/Group/Namespace for the repo (if available)

[REPO] → Checkmarx Project [PROJECT] → Repository name (if available)

[BRANCH] → Checkmarx Project [PROJECT] → Branch name (if available)

[TIMESTAMP] → Current timestamp (yyyyMMdd.HHmmss format)

NONE | WAIT

If you want to trigger scans asynchronously, use NONE If you want to trigger scans, but wait for feedback | summary console output, use WAIT | wait