Plugin to extract output from Checkmarx security scanner

docs/automations/integrations/checkmarx/label-checkmarx-scan-results/README.md

@@ -0,0 +1,45 @@
+---
+title: Automation - Auto-Label Checkmarx Scan Results
+description: Automatically apply labels to PRs that indicate the result of Checkmarx scans.
+category: [security, checkmarx]
+---
+# Auto-Label Checkmarx Scan Results
+
+
+<!-- --8<-- [start:example]-->
+Automatically apply labels to PRs that indicate the result of Checkmarx scans.
+
+!!! warning "Required gitStream Plugin"
+    This example requires you to [install the `extractCheckmarxFindings` plugin](/filter-function-plugins/#extractcheckmarxfindings).
+
+    [Learn more about gitStream plugins](/plugins/).
+
+<div class="automationDescription" markdown="1">
+!!! info "Configuration Description"
+    Conditions (all must be true):
+
+    * Checkmarx detects one or more new issues with the code in the PR.
+
+    Automation Actions:
+
+    * Apply a label that indicates which scan type identified the issue (SAST, SCA, or IaC).
+
+</div>
+<div class="automationExample" markdown="1">
+!!! example "Auto-Label Checkmarx Scan Results"
+    ```yaml+jinja
+    --8<-- "docs/downloads/automation-library/integrations/checkmarx/label_checkmarx_scan_results.cm"
+    ```
+    <div class="result" markdown>
+      <span>
+      [:octicons-download-24: Download this example as a CM file.](/downloads/automation-library/integrations/checkmarx/label_checkmarx_scan_results.cm){ .md-button }
+      </span>
+    </div>
+</div>
+<!-- --8<-- [end:example]-->
+
+## Additional Resources
+
+--8<-- "docs/snippets/general.md"
+
+--8<-- "docs/snippets/automation-footer.md"

docs/automations/integrations/checkmarx/review-checkmarx-alerts/README.md

@@ -0,0 +1,44 @@
+---
+title: Automation - Review Checkmarx Security Alerts
+description: Automatically require review from your SecOps team for Checkmarx security violations in pull requests.
+category: [security, checkmarx]
+---
+# Require Security Review for Checkmarx Alerts
+<!-- --8<-- [start:example]-->
+Automatically require review from your SecOps team for Checkmarx security violations in pull requests.
+
+!!! warning "Required gitStream Plugin"
+    This example requires you to [install the `extractCheckmarxFindings` plugin](/filter-function-plugins/#extractcheckmarxfindings).
+
+    [Learn more about gitStream plugins](/plugins/).
+
+<div class="automationDescription" markdown="1">
+!!! info "Configuration Description"
+    Conditions (all must be true):
+
+    * The PR contains a SAST finding, SCA vulnerability, or IaC issue flagged as Critical or High.
+
+    Automation Actions:
+
+    * Require review from your organization's security team.
+    * Post a comment explaining the requirement.
+
+</div>
+<div class="automationExample" markdown="1">
+!!! example "Review Checkmarx Security Alerts"
+    ```yaml+jinja
+    --8<-- "docs/downloads/automation-library/integrations/checkmarx/review_checkmarx_alerts.cm"
+    ```
+    <div class="result" markdown>
+      <span>
+      [:octicons-download-24: Download this example as a CM file.](/downloads/automation-library/integrations/checkmarx/review_checkmarx_alerts.cm){ .md-button }
+      </span>
+    </div>
+</div>
+<!-- --8<-- [end:example]-->
+
+## Additional Resources
+
+--8<-- "docs/snippets/general.md"
+
+--8<-- "docs/snippets/automation-footer.md"

docs/downloads/automation-library/integrations/checkmarx/label_checkmarx_scan_results.cm

@@ -0,0 +1,28 @@
+# -*- mode: yaml -*-
+
+manifest:
+  version: 1.0
+
+automations:
+  {% for item in reports %}
+  label_checkmarx_{{ item.name }}:
+    if:
+      - {{ item.count > 0 }}
+    run:
+      - action: add-label@v1
+        args:
+          label: 'checkmarx:{{ item.name }}'
+  {% endfor %}
+
+checkmarx: {{ pr | extractCheckmarxFindings }}
+
+reports:
+  - name: sast-findings
+    count: {{ checkmarx.sast.count }}
+  - name: sca-findings
+    count: {{ checkmarx.sca.count }}
+  - name: iac-findings
+    count: {{ checkmarx.kics.count }}
+
+colors:
+  red: 'b60205'

docs/downloads/automation-library/integrations/checkmarx/review_checkmarx_alerts.cm

@@ -0,0 +1,23 @@
+# -*- mode: yaml -*-
+
+manifest:
+  version: 1.0
+automations:
+  review_checkmarx_alerts:
+    if:
+      - {{ has.sast_alert or has.sca_alert or has.iac_alert }}
+    run:
+      - action: require-reviewers@v1
+        args:
+          reviewers: [my-organization/security-team]
+      - action: add-comment@v1
+        args:
+          comment: |
+            This PR requires additional review because Checkmarx identified security issues that need attention.
+
+checkmarx: {{ pr | extractCheckmarxFindings }}
+
+has:
+  sast_alert: {{ checkmarx.sast.severity.critical > 0 or checkmarx.sast.severity.high > 0 }}
+  sca_alert: {{ checkmarx.sca.severity.critical > 0 or checkmarx.sca.severity.high > 0 }}
+  iac_alert: {{ checkmarx.kics.severity.critical > 0 or checkmarx.kics.severity.high > 0 }}

docs/filter-function-plugins.md

@@ -26,6 +26,8 @@ JavaScript plugins that enable custom filter functions for gitStream. To learn h
 
 --8<-- "plugins/filters/extractSnykVersionBump/README.md"
 
+--8<-- "plugins/filters/extractCheckmarxFindings/README.md"
+
 --8<-- "plugins/filters/extractOrcaFindings/README.md"
 
 --8<-- "plugins/filters/generateDescription/README.md"

docs/integrations/README.md

@@ -95,6 +95,12 @@ visible: false
 
 <div class="integrations-list" markdown="1">
 
+<div class="integrations-card" markdown="1">
+<div class="integrations-card-title" markdown="1">
+[:material-shield-search: Checkmarx](/integrations/checkmarx/)
+</div>
+</div>
+
 <div class="integrations-card" markdown="1">
 <div class="integrations-card-title" markdown="1">
 <a href=/integrations/orca-security/>![Orca Security](../downloads/images/Orca-Mark-Black.png#only-light) ![LinearB](../downloads/images/Orca-Mark-White.png#only-dark) Orca</a>

docs/integrations/checkmarx.md

@@ -0,0 +1,19 @@
+---
+title: Integrate gitStream with Checkmarx
+description: Implement workflow automations for Checkmarx.
+---
+# Integrate gitStream with Checkmarx
+
+## Auto-Label Checkmarx Scan Results
+--8<-- "docs/automations/integrations/checkmarx/label-checkmarx-scan-results/README.md:example"
+
+## Require Security Review for Checkmarx Alerts
+--8<-- "docs/automations/integrations/checkmarx/review-checkmarx-alerts/README.md:example"
+
+
+
+## Additional Resources
+
+--8<-- "docs/snippets/general.md"
+
+--8<-- "docs/snippets/automation-footer.md"

plugins/filters/extractCheckmarxFindings/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LinearB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plugins/filters/extractCheckmarxFindings/README.md

@@ -0,0 +1,24 @@
+--8<-- "plugins/filters/extractCheckmarxFindings/reference.md"
+
+Usage example, that adds labels based on Checkmarx scan findings.
+
+??? note "Plugin Code: extractCheckmarxFindings"
+    ```javascript
+    --8<-- "plugins/filters/extractCheckmarxFindings/index.js"
+    ```
+    <div class="result" markdown>
+    <span>
+    </span>
+    </div>
+
+
+??? example "gitStream CM Example: extractCheckmarxFindings"
+    ```yaml+jinja
+    --8<-- "plugins/filters/extractCheckmarxFindings/extract_checkmarx_findings.cm"
+    ```
+    <div class="result" markdown>
+    <span>
+    </span>
+    </div>
+
+[Download Source Code](https://github.com/linear-b/gitstream/tree/main/plugins/filters/extractCheckmarxFindings)

plugins/filters/extractCheckmarxFindings/extract_checkmarx_findings.cm

@@ -0,0 +1,28 @@
+# -*- mode: yaml -*-
+
+manifest:
+  version: 1.0
+
+automations:
+  {% for item in reports %}
+  label_checkmarx_{{ item.name }}:
+    if:
+      - {{ item.count > 0 }}
+    run:
+      - action: add-label@v1
+        args:
+          label: 'checkmarx:{{ item.name }}'
+  {% endfor %}
+
+checkmarx: {{ pr | extractCheckmarxFindings }}
+
+reports:
+  - name: sast-findings
+    count: {{ checkmarx.sast.count }}
+  - name: sca-findings
+    count: {{ checkmarx.sca.count }}
+  - name: iac-findings
+    count: {{ checkmarx.kics.count }}
+
+colors:
+  red: 'b60205'

plugins/filters/extractCheckmarxFindings/index.js

@@ -0,0 +1,91 @@
+/**
+ * @module extractCheckmarxFindings
+ * @description Extract security findings from Checkmarx PR comments
+ * @param {Object} pr - the gitStream's PR context variable
+ * @returns {Object} Findings
+ * Findings.sast: { count: null, severity: '' },
+ * Findings.sca: { count: null, severity: '' },
+ * Findings.kics: { count: null, severity: '' },
+ * @example {{ pr | extractCheckmarxFindings }}
+ * @license MIT
+**/
+
+const SCANNERS = ['sast', 'sca', 'kics'];
+const SEVERITY_LEVELS = ['critical', 'high', 'medium', 'low', 'info'];
+
+function emptySeverity() {
+  return { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+}
+
+function emptyFindings() {
+  return { count: null, severity: '' };
+}
+
+function detectScanner(line) {
+  if (/\b(IaC[\s-]*Security|KICS)\b/i.test(line)) return 'kics';
+  if (/\bSAST\b/i.test(line)) return 'sast';
+  if (/\bSCA\b/i.test(line)) return 'sca';
+  return null;
+}
+
+function parseCheckmarxComment(content) {
+  const findings = {};
+  SCANNERS.forEach(s => { findings[s] = emptyFindings(); });
+
+  const severityCounts = {};
+  SCANNERS.forEach(s => { severityCounts[s] = emptySeverity(); });
+
+  const lines = content.split('\n');
+  let currentScanner = null;
+  let inNewIssues = false;
+
+  for (const line of lines) {
+    // Track whether we're in a "New Issues" or "Fixed Issues" section.
+    // Only count findings from the "New Issues" section.
+    if (/\bNew\s+Issues\b/i.test(line)) {
+      inNewIssues = true;
+    } else if (/\bFixed\s+Issues\b/i.test(line)) {
+      inNewIssues = false;
+    }
+
+    // Update current scanner section when we see a scanner name
+    const scanner = detectScanner(line);
+    if (scanner) {
+      currentScanner = scanner;
+    }
+
+    // Match table rows where the first cell contains a severity level
+    // Checkmarx tables use: | SEVERITY | Issue | ... |
+    if (!inNewIssues) continue;
+    const tableMatch = line.match(/^\s*\|\s*(CRITICAL|HIGH|MEDIUM|LOW|INFO)\b/i);
+    if (tableMatch && currentScanner) {
+      const level = tableMatch[1].toLowerCase();
+      severityCounts[currentScanner][level]++;
+    }
+  }
+
+  SCANNERS.forEach(s => {
+    const counts = severityCounts[s];
+    const total = counts.critical + counts.high + counts.medium + counts.low + counts.info;
+    findings[s] = { count: total, severity: counts };
+  });
+
+  return findings;
+}
+
+module.exports = (pr) => {
+  let checkmarxObject = {};
+  SCANNERS.forEach(s => { checkmarxObject[s] = emptyFindings(); });
+
+  // Checkmarx comments can appear as PR comments or reviews
+  const checkmarxComment = pr.comments
+    .filter(x => x.commenter.includes('checkmarx'))
+    .concat(pr.reviews.filter(x => x.commenter.includes('checkmarx')));
+
+  if (checkmarxComment.length) {
+    const latestComment = checkmarxComment[checkmarxComment.length - 1].content;
+    checkmarxObject = parseCheckmarxComment(latestComment);
+  }
+
+  return JSON.stringify(checkmarxObject);
+}

plugins/filters/extractCheckmarxFindings/reference.md

@@ -0,0 +1,19 @@
+<a name="module_extractCheckmarxFindings"></a>
+
+## extractCheckmarxFindings
+Extract security findings from Checkmarx PR comments
+
+**Returns**: <code>Object</code> - Findings
+Findings.sast: { count: null, severity: '' },
+Findings.sca: { count: null, severity: '' },
+Findings.kics: { count: null, severity: '' },
+**License**: MIT
+
+| Param | Type | Description |
+| --- | --- | --- |
+| PR | <code>Object</code> | the gitStream's PR context variable |
+
+**Example**
+```js
+{{ pr | extractCheckmarxFindings }}
+```