Skip to content

Commit c4daf99

Browse files
skywalke34skywalke34
authored
Checkmarx one doc update (#12408)
* Update checkmarx one parser documentation Significantly updating the Checkmarx One parser documentation including mapping table, details of different types of scans, and special data handling. * Update checkmarx_one.md - remove line number references Removed references to line numbers within the parser.py.
1 parent 13e35cf commit c4daf99

File tree

1 file changed

+143
-1
lines changed

1 file changed

+143
-1
lines changed

‎docs/content/en/connecting_your_tools/parsers/file/checkmarx_one.md

Lines changed: 143 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,147 @@ toc_hide: true
44
---
55
Import JSON Checkmarx One scanner reports
66

7+
# Checkmarx One JSON Parser Documentation
8+
9+
## Overview
10+
11+
The Checkmarx One parser for DefectDojo supports importing findings from Checkmarx One in JSON format. The parser handles three types of security findings including SAST (Static Application Security Testing), KICS (Kubernetes/Infrastructure as Code Security), and SCA (Software Composition Analysis) scan results, with specialized parsing logic for each type.
12+
13+
## Supported File Types
14+
15+
The Checkmarx One parser accepts JSON file format. To generate this file:
16+
17+
1. Log in to the Checkmarx One platform
18+
2. Navigate to the Results view
19+
3. Use the Export option to download findings in JSON format
20+
21+
The parser can handle several variations of the Checkmarx One JSON output format:
22+
- Results in a top-level `results` array (primary format)
23+
- Results in `vulnerabilities` array
24+
- Results structured in separate sections (`scanResults`, `iacScanResults`, or `scaScanResults`)
25+
26+
## Standard Format JSON (Main Format)
27+
28+
### Total Fields in JSON
29+
30+
- Total data fields in Checkmarx JSON output: 24 core fields per finding (with nested fields)
31+
- Total data fields parsed into DefectDojo finding: 17 fields
32+
- Total data fields NOT parsed: 7 fields (some fields provide context but aren't directly mapped)
33+
34+
### Standard Format Field Mapping Details
35+
36+
| Data Field # | Checkmarx Data Field | DefectDojo Finding Field | Notes |
37+
|--------------|----------------------|--------------------------|-------|
38+
| 1 | type | unsaved_tags | Added as a tag identifying the finding type (sast, kics, sca, etc.) |
39+
| 2 | id | unique_id_from_tool | Primary unique identifier for the finding |
40+
| 3 | similarityId | unique_id_from_tool | Used as fallback if id not present |
41+
| 4 | status | - | Used for state determination but not directly mapped |
42+
| 5 | state | active, verified, false_p | Maps Checkmarx states to DefectDojo fields through determine_state function |
43+
| 6 | severity | severity | Converted to title case (e.g., "HIGH" → "High") |
44+
| 7 | firstFoundAt | date | Used as finding date if USE_FIRST_SEEN setting is True |
45+
| 8 | foundAt | date | Used as finding date if USE_FIRST_SEEN setting is False |
46+
| 9 | description | description, title | Used for both description and title when available |
47+
| 10 | descriptionHTML | - | Not mapped - HTML version of description is ignored |
48+
| 11 | data.queryId | - | Used in KICS findings but not directly mapped |
49+
| 12 | data.queryName | title (partial) | Used as part of the title construction when needed |
50+
| 13 | data.group/category | description (partial) | Added to description for KICS findings with "Category" prefix |
51+
| 14 | data.line | line | Line number in file where vulnerability exists |
52+
| 15 | data.fileName/filename | file_path | Path to the vulnerable file |
53+
| 16 | data.expectedValue | mitigation (partial) | Added to mitigation for KICS findings |
54+
| 17 | data.value | mitigation (partial) | Added to mitigation for KICS findings |
55+
| 18 | data.nodes[].fileName | description (partial) | Used in node snippets for SAST findings |
56+
| 19 | data.nodes[].method | description (partial) | Used in node snippets for SAST findings |
57+
| 20 | data.nodes[].line | description (partial) | Used in node snippets for SAST findings |
58+
| 21 | data.nodes[].code | description (partial) | Used in node snippets for SAST findings |
59+
| 22 | vulnerabilityDetails.cweId | cwe | CWE ID number |
60+
| 23 | vulnerabilityDetails.cvss | - | Not mapped directly |
61+
| 24 | cveId | unsaved_vulnerability_ids | For SCA findings, mapped to vulnerability IDs list |
62+
63+
### Field Mapping Details
64+
65+
The parser contains three main methods for parsing different formats of Checkmarx One output:
66+
67+
1. `parse_results`: Main entry point for parsing the standard format with a top-level `results` array
68+
2. `parse_vulnerabilities`: For parsing the format with a `vulnerabilities` array
69+
3. `parse_vulnerabilities_from_scan_list`: For parsing formats with separate sections by vulnerability type
70+
71+
Each vulnerability type has specialized parsing logic:
72+
73+
1. **SAST (Static Application Security Testing)** - `get_results_sast`:
74+
- Focuses on code-level vulnerabilities
75+
- Uses file path from the first node
76+
- Tags findings with "sast"
77+
78+
2. **KICS (Kubernetes/IaC Security)** - `get_results_kics`:
79+
- Infrastructure as Code findings
80+
- Extracts filename from data field
81+
- Tags findings with "kics"
82+
83+
3. **SCA (Software Composition Analysis)** - `get_results_sca`:
84+
- Vulnerability in dependencies/packages
85+
- Handles CVE IDs when present
86+
- Tags findings with "sca" or "sca-container"
87+
88+
### Special Processing Notes
89+
90+
#### Status Conversion
91+
- The `determine_state` function handles state conversion for all finding types
92+
- Maps Checkmarx One states to DefectDojo fields:
93+
- "TO_VERIFY", "PROPOSED_NOT_EXPLOITABLE", "CONFIRMED", "URGENT" → active=True
94+
- "NOT_EXPLOITABLE", "CONFIRMED", "URGENT" → verified=True
95+
- "NOT_EXPLOITABLE" → false_p=True
96+
- All findings explicitly set duplicate=False and out_of_scope=False
97+
98+
#### Severity Conversion
99+
- Severity values from Checkmarx One ("HIGH", "MEDIUM", "LOW", etc.) are converted to title case
100+
- The parser takes the severity directly from the Checkmarx One finding and formats it to match DefectDojo's expected format
101+
- No numerical conversion is performed, as Checkmarx One already provides categorical severity levels
102+
103+
#### Description Construction
104+
- For SAST findings with nodes:
105+
- Function `get_node_snippet` formats code snippets
106+
- Includes file name, method name, line number, and code
107+
- Adds node snippets to description with separator
108+
- For KICS findings:
109+
- Adds category information with "Category" prefix
110+
- Includes issue type information
111+
- Can include link to Checkmarx One for viewing the finding
112+
113+
#### Date Processing
114+
- Uses a custom `_parse_date` method to handle multiple date formats
115+
- Supports both string dates (parsed with dateutil.parser) and Timestamp objects with "seconds" field
116+
117+
#### Title Format
118+
- SAST: Uses description text, or queryPath/queryName with underscores replaced by spaces
119+
- KICS: Uses description or severity + queryName with underscores replaced
120+
- SCA: Uses description or severity + queryName with underscores replaced
121+
- When description is missing, title is constructed from severity and query name
122+
123+
#### Mitigation Construction
124+
- For KICS findings:
125+
- Combines actual and expected values
126+
- Format: "**Actual Value**: {value}\n**Expected Value**: {expectedValue}\n"
127+
- For SAST findings:
128+
- Uses general recommendations from CWE information when available
129+
130+
#### Deduplication
131+
- Uses unique_id_from_tool based on finding "id" or "similarityId" as fallback
132+
- Consistent across all finding types (SAST, KICS, SCA)
133+
- No custom hash calculation is performed
134+
135+
#### Tags Handling
136+
- Every finding gets tagged with its type
137+
- Tags include: "sast", "kics", "sca", "sca-container"
138+
139+
#### Common Settings for All Findings
140+
- All findings have static_finding=True
141+
- SCA findings can have unsaved_vulnerability_ids populated with CVE IDs
142+
- SAST findings include CWE information when available
143+
- All findings have explicit settings for active, verified, false_p, duplicate, and out_of_scope
144+
7145
### Sample Scan Data
8-
Sample Checkmarx One scans can be found [here](https://github.com/DefectDojo/django-DefectDojo/tree/master/unittests/scans/checkmarx_one).
146+
Sample Checkmarx One scans can be found [here](https://github.com/DefectDojo/django-DefectDojo/tree/master/unittests/scans/checkmarx_one).
147+
148+
### Link To Tool
149+
- [Checkmarx One](https://checkmarx.com/product/application-security-platform/)
150+
- [Checkmarx One Documentation](https://checkmarx.com/resource/documents/en/34965-68516-checkmarx-one-documentation-portal.html)

0 commit comments

Comments
 (0)