Skip to content

Commit 730c7e5

Browse files
cx-aniket-shindeclaude
cx-aniket-shinde
and
claude
committed
docs AST-146800: Add Cloud.md standardization file
Adds the Cloud.md documentation file covering all essential sections: Project Overview, Architecture, Repository Structure, Technology Stack, Development Setup, Coding Standards, Project Rules, Testing Strategy, Known Issues — plus recommended sections: External Integrations, Deployment, Security & Access, Logging, and Debugging Steps. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
1 parent 1b94a50 commit 730c7e5

1 file changed

Lines changed: 346 additions & 0 deletions

File tree

‎Cloud.md‎

Lines changed: 346 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,346 @@
1+
# Cloud.md — Checkmarx One Eclipse Plugin
2+
3+
> Standardized Cloud MD file for [ast-eclipse-plugin](https://github.com/Checkmarx/ast-eclipse-plugin)
4+
> Following the Cloud MD standardization template defined in epic AST-146793.
5+
6+
---
7+
8+
## Project Overview
9+
10+
The **Checkmarx One Eclipse Plugin** integrates the full Checkmarx One security platform directly into the Eclipse IDE. It enables developers to discover and remediate vulnerabilities without leaving their editor — embodying the shift-left AppSec philosophy.
11+
12+
**Key capabilities:**
13+
- Import scan results (SAST, SCA, IaC Security) from Checkmarx One directly into Eclipse
14+
- Run new scans from the IDE before committing code
15+
- Navigate from a vulnerability directly to the affected source line
16+
- Triage results (adjust severity, state, add comments) without leaving the IDE
17+
- Filter and group results by severity, state, or query name
18+
- View vulnerability descriptions, attack vectors, and Codebashing remediation links
19+
- Best Fix Location (BFL) highlighting for SAST findings
20+
21+
**Supported Eclipse versions:** 2019-03 (4.11) and above
22+
**Supported platforms:** Windows, macOS, Linux/GTK
23+
24+
---
25+
26+
## Architecture
27+
28+
The plugin follows a standard Eclipse **ViewPart** architecture backed by an **OSGi** bundle lifecycle.
29+
30+
```
31+
┌─────────────────────────────────────────────────────┐
32+
│ Eclipse IDE │
33+
│ ┌──────────────────────────────────────────────┐ │
34+
│ │ CheckmarxView (ViewPart) │ │
35+
│ │ ┌──────────┐ ┌──────────┐ ┌────────────┐ │ │
36+
│ │ │ Project │ │ Branch │ │ Scan ID │ │ │
37+
│ │ │ Combo │ │ Combo │ │ Combo │ │ │
38+
│ │ └──────────┘ └──────────┘ └────────────┘ │ │
39+
│ │ ┌────────────────────────────────────────┐ │ │
40+
│ │ │ Results Tree (SWT TreeViewer) │ │ │
41+
│ │ │ Grouped by: Severity / Query / State │ │ │
42+
│ │ └────────────────────────────────────────┘ │ │
43+
│ │ ┌───────────────┐ ┌──────────────────────┐ │ │
44+
│ │ │ Description │ │ Attack Vector / │ │ │
45+
│ │ │ & Triage │ │ Package Data / │ │ │
46+
│ │ │ Panel │ │ BFL Panel │ │ │
47+
│ │ └───────────────┘ └──────────────────────┘ │ │
48+
│ └──────────────────────────────────────────────┘ │
49+
└─────────────────────────────────────────────────────┘
50+
│ EventBus (Guava)
51+
▼
52+
┌─────────────────────┐ ┌──────────────────────┐
53+
│ DataProvider │◄──────►│ ast-cli-java-wrapper │
54+
│ (Singleton) │ │ (Checkmarx One API) │
55+
└─────────────────────┘ └──────────────────────┘
56+
```
57+
58+
**Key architectural decisions:**
59+
- **Event-driven UI:** Google Guava `EventBus` decouples UI actions (filter changes, scan loads) from the view rendering. Events: `FILTER_CHANGED`, `GET_RESULTS`, `CLEAN_AND_REFRESH`, `LOAD_RESULTS_FOR_SCAN`.
60+
- **CLI wrapper:** All communication with the Checkmarx One platform is delegated to `ast-cli-java-wrapper`, which wraps the Checkmarx CLI binary. No direct REST calls from the plugin.
61+
- **Singleton DataProvider:** Holds all loaded scan results, filter state, and project/branch/scan metadata for the current session.
62+
- **Static FilterState:** Severity and state filter flags are stored as static fields persisted to Eclipse preferences via `GlobalSettings`.
63+
64+
---
65+
66+
## Repository Structure
67+
68+
```
69+
ast-eclipse-plugin/
70+
├── checkmarx-ast-eclipse-plugin/ # Main OSGi plugin bundle
71+
│ ├── src/com/checkmarx/eclipse/
72+
│ │ ├── Activator.java # OSGi bundle lifecycle
73+
│ │ ├── enums/ # Severity, State, ActionName enums
74+
│ │ ├── properties/ # Eclipse preferences page & fields
75+
│ │ ├── runner/ # Authentication runner
76+
│ │ ├── utils/ # CxLogger, PluginUtils, PluginConstants
77+
│ │ └── views/
78+
│ │ ├── CheckmarxView.java # Main ViewPart (~2600 lines)
79+
│ │ ├── DataProvider.java # Singleton data/state manager
80+
│ │ ├── DisplayModel.java # Tree node model
81+
│ │ ├── GlobalSettings.java # Eclipse preference store wrapper
82+
│ │ ├── actions/ # Toolbar actions (filters, scan, triage)
83+
│ │ ├── filters/ # FilterState, ActionFilters
84+
│ │ └── provider/ # TreeContentProvider, ColumnProvider
85+
│ ├── META-INF/MANIFEST.MF # OSGi bundle descriptor
86+
│ ├── plugin.xml # Eclipse extension points
87+
│ ├── icons/ # Severity and UI icons
88+
│ └── lib/ # Bundled JAR dependencies
89+
├── checkmarx-ast-eclipse-plugin-tests/ # Test bundle
90+
│ └── src/test/java/.../tests/
91+
│ ├── integration/ # Integration tests (auth)
92+
│ ├── ui/ # SWTBot UI tests
93+
│ └── unit/ # Unit tests
94+
├── com.checkmarx.eclipse.feature/ # Eclipse feature descriptor
95+
├── com.checkmarx.eclipse.site/ # Eclipse p2 update site
96+
├── pom.xml # Root Maven/Tycho POM
97+
├── ast-cli-java-wrapper.version # Pinned wrapper version
98+
└── .github/workflows/ # CI/CD pipelines
99+
```
100+
101+
---
102+
103+
## Technology Stack
104+
105+
| Layer | Technology | Version |
106+
|-------|-----------|---------|
107+
| Language | Java | 17 (Temurin) |
108+
| IDE Framework | Eclipse OSGi / RCP | 4.11+ |
109+
| UI Toolkit | SWT / JFace | Bundled with Eclipse |
110+
| Build System | Maven + Eclipse Tycho | Tycho 4.0.11 |
111+
| Platform API | ast-cli-java-wrapper | 2.4.23 |
112+
| Event Bus | Google Guava | Bundled with Eclipse |
113+
| Git Integration | JGit | Bundled with Eclipse |
114+
| JSON | Jackson | 2.21.1 |
115+
| Utilities | Apache Commons Lang3 | 3.18.0 |
116+
| Logging | SLF4J + Eclipse ILog (CxLogger) | 2.0.17 |
117+
118+
---
119+
120+
## Development Setup
121+
122+
### Prerequisites
123+
124+
1. **Java 17** (Temurin recommended)
125+
2. **Eclipse IDE for RCP and RAP Developers** (2019-03 or later) — includes PDE (Plugin Development Environment)
126+
3. **Maven 3.x** with Tycho support
127+
4. **Checkmarx One account** with an API key (`ast-scanner` + `default-roles` IAM roles)
128+
129+
### Clone and Import
130+
131+
```bash
132+
git clone https://github.com/Checkmarx/ast-eclipse-plugin.git
133+
cd ast-eclipse-plugin
134+
```
135+
136+
Import into Eclipse:
137+
- `File → Import → Maven → Existing Maven Projects`
138+
- Select the repo root — all four modules will be detected
139+
140+
### Build from CLI
141+
142+
```bash
143+
# Full build (plugin + feature + site + tests)
144+
mvn clean verify
145+
146+
# Build plugin only (skip tests)
147+
mvn clean package -pl checkmarx-ast-eclipse-plugin -am -DskipTests
148+
```
149+
150+
### Run in Development
151+
152+
1. Open `checkmarx-ast-eclipse-plugin/plugin.xml` in Eclipse
153+
2. Click **Launch an Eclipse Application** (creates a new Eclipse instance with the plugin loaded)
154+
3. Configure credentials: `Window → Preferences → Checkmarx`
155+
156+
### Run Tests
157+
158+
```bash
159+
# UI tests (requires Xvfb on Linux)
160+
Xvfb -ac :99 -screen 0 1920x1080x16 &
161+
mvn verify -Dtest.includes="**/ui/*.java" \
162+
-DCX_BASE_URI=<url> -DCX_TENANT=<tenant> \
163+
-DCX_APIKEY=<key> -DCX_TEST_SCAN=<scan-id>
164+
165+
# Unit tests only
166+
mvn test -pl checkmarx-ast-eclipse-plugin-tests
167+
```
168+
169+
---
170+
171+
## Coding Standards
172+
173+
- **Java 17** language level — use modern constructs (streams, lambdas, records where appropriate)
174+
- **Logging:** Always use `CxLogger` (Eclipse ILog wrapper), never raw `System.out` or SLF4J directly in plugin code. SLF4J is available only for passing to the CLI wrapper internals.
175+
- **UI thread safety:** All SWT widget updates must happen on the UI thread. Use `UISynchronizeImpl.asyncExec()` for background-to-UI transitions.
176+
- **EventBus events:** Post events via `pluginEventBus.post(new PluginListenerDefinition(...))`. Subscribe with `@Subscribe`. Never call UI update methods directly from non-UI threads.
177+
- **Constants:** Add all string literals used in UI or logic to `PluginConstants.java`. Never hardcode strings inline.
178+
- **SWT layout:** Use `GridData`/`GridLayout` for all composites. Avoid fixed `widthHint` on combos that may contain variable-length content — use `SWT.FILL` with `grabExcessHorizontalSpace = true` instead.
179+
- **Null safety:** Check `selectedItem.getResult()` and `selectedItem.getSeverity()` before accessing them — tree nodes may be group-level nodes with no attached result.
180+
181+
---
182+
183+
## Project Rules
184+
185+
- **All PRs target `main`** (or an integration branch when batching multiple bug fixes).
186+
- **Branch naming:**
187+
- Bug fixes: `bug/AST-XXXXX`
188+
- Features: `feature/AST-XXXXX`
189+
- Documentation: `docs/AST-XXXXX`
190+
- Other: `other/AST-XXXXX`
191+
- **Commit messages** must reference the Jira ticket: `Fix AST-XXXXX: <description>`
192+
- **Never commit secrets.** Checkmarx credentials are injected via environment variables or Eclipse preferences at runtime — never hardcoded.
193+
- **Wrapper version** is pinned in `ast-cli-java-wrapper.version`. Update this file and the JAR in `lib/` when upgrading the CLI wrapper.
194+
- **Icons** must be placed in `checkmarx-ast-eclipse-plugin/icons/` and registered in `plugin.xml` if used as action images.
195+
- **PR size:** Keep PRs focused on a single ticket. Use an integration branch to batch multiple related fixes before merging to main.
196+
197+
---
198+
199+
## Testing Strategy
200+
201+
### Test Types
202+
203+
| Type | Location | Runner | Purpose |
204+
|------|----------|--------|---------|
205+
| Unit | `unit/` | JUnit | Test logic in isolation (DataProvider, FilterState, PluginUtils) |
206+
| UI (SWTBot) | `ui/` | SWTBot + JUnit | Test full plugin behavior inside a headless Eclipse instance |
207+
| Integration | `integration/` | JUnit | Test authentication and API connectivity against a real Checkmarx One tenant |
208+
209+
### CI Triggers
210+
211+
- All tests run on **every PR to `main`** via GitHub Actions (`.github/workflows/ci.yml`)
212+
- UI tests run on **Ubuntu** with **Xvfb** (virtual display)
213+
- Integration tests require secrets: `CX_BASE_URI`, `CX_TENANT`, `CX_APIKEY`, `CX_TEST_SCAN`
214+
215+
### Coverage
216+
217+
- JaCoCo coverage reports generated per run
218+
- Reports uploaded as GitHub Actions artifacts
219+
- Coverage badge auto-generated via `cicirello/jacoco-badge-generator`
220+
221+
---
222+
223+
## External Integrations
224+
225+
| Integration | Purpose | How |
226+
|-------------|---------|-----|
227+
| **Checkmarx One Platform** | Fetch projects, branches, scans, results; submit triage | Via `ast-cli-java-wrapper` (wraps the Checkmarx CLI binary) |
228+
| **JGit** | Detect current git branch to auto-select in branch combo | `RefsChangedListener` on local repo |
229+
| **Eclipse Marketplace** | Plugin distribution and install | p2 update site published on release |
230+
| **Codebashing** | Remediation lesson links per vulnerability | REST call to Checkmarx Codebashing API |
231+
232+
---
233+
234+
## Deployment
235+
236+
### Release Process
237+
238+
Releases are created via `.github/workflows/release.yml` (triggered manually or via `workflow_call`):
239+
240+
1. Input: `tag` (semver), `jira_ticket`, optional `rbranch` for dev releases
241+
2. Tycho builds the p2 update site into `com.checkmarx.eclipse.site/target/`
242+
3. Site artifact is published as a GitHub Release
243+
4. Dev releases are cleaned up automatically before publishing a stable release
244+
245+
### Distribution
246+
247+
- **Eclipse Marketplace:** [checkmarx-ast-plugin](https://marketplace.eclipse.org/content/checkmarx-ast-plugin)
248+
- **p2 Update Site:** published as a GitHub Release asset
249+
250+
### Install (End Users)
251+
252+
```
253+
Help → Install New Software → Add repository URL (GitHub Release asset)
254+
```
255+
256+
---
257+
258+
## Security & Access
259+
260+
- **API Key authentication:** Users configure a Checkmarx One API key in `Window → Preferences → Checkmarx`. The key is stored in the Eclipse secure preferences store.
261+
- **Required roles:** `ast-scanner` (composite role) + `default-roles` IAM role on the Checkmarx One tenant.
262+
- **No credentials in code:** All secrets are injected at runtime via preferences or environment variables (CI). Never commit API keys or tokens.
263+
- **TLS:** All communication with Checkmarx One is HTTPS, enforced by the CLI wrapper.
264+
- **Triage permissions:** Triage actions (severity/state changes) require the user's API key to have write permissions on the project.
265+
266+
---
267+
268+
## Logging
269+
270+
The plugin uses two logging mechanisms — use the right one for the right context:
271+
272+
| Logger | Class | Output | When to use |
273+
|--------|-------|--------|-------------|
274+
| `CxLogger` | `com.checkmarx.eclipse.utils.CxLogger` | Eclipse Error Log view + `.metadata/.log` | All plugin-level log messages |
275+
| SLF4J | `org.slf4j.Logger` | No-op inside OSGi (dropped) | Only for passing to `CxWrapper` internals |
276+
277+
**Usage:**
278+
```java
279+
CxLogger.info("Loading results for scan: " + scanId);
280+
CxLogger.error("Failed to fetch projects: " + e.getMessage(), e);
281+
CxLogger.warning("Could not fetch platform states: " + e.getMessage());
282+
```
283+
284+
**Viewing logs:**
285+
- Eclipse IDE: `Window → Show View → Error Log`
286+
- File: `<workspace>/.metadata/.log`
287+
288+
---
289+
290+
## Debugging Steps
291+
292+
### Plugin not loading
293+
294+
1. Check `Window → Show View → Error Log` for bundle activation errors
295+
2. Verify Java 17 is set as the JRE: `Window → Preferences → Java → Installed JREs`
296+
3. Confirm the plugin is enabled: `Help → About Eclipse → Installation Details`
297+
298+
### Authentication failures
299+
300+
1. Verify API key in `Window → Preferences → Checkmarx` — click **Authenticate**
301+
2. Check Error Log for `CxLogger` messages containing `authentication` or `CxException`
302+
3. Confirm the API key has `ast-scanner` + `default-roles` roles on the tenant
303+
304+
### No results / empty tree
305+
306+
1. Confirm project, branch, and scan ID are selected in the top combos
307+
2. Check filter state — all severity filters may be disabled (toolbar toggle buttons)
308+
3. Check Error Log for errors from `DataProvider.getResultsForScanId()`
309+
310+
### UI not updating after filter change
311+
312+
1. Confirm you are on a build that includes the AST-136035 fix
313+
2. If the tree collapses entirely, check that `FILTER_CHANGED` calls `updateResultsTree(..., true)`
314+
315+
### Custom state dropdown overflow
316+
317+
1. Fixed in AST-137779 — ensure you are on a build that includes the `truncate()` fix in `ActionFilterStatePreference`
318+
319+
### Running UI tests locally (Linux)
320+
321+
```bash
322+
Xvfb -ac :99 -screen 0 1920x1080x16 &
323+
export DISPLAY=:99.0
324+
mvn verify -Dtest.includes="**/ui/*.java" \
325+
-DCX_BASE_URI=$CX_BASE_URI \
326+
-DCX_TENANT=$CX_TENANT \
327+
-DCX_APIKEY=$CX_APIKEY \
328+
-DCX_TEST_SCAN=$CX_TEST_SCAN
329+
```
330+
331+
---
332+
333+
## Known Issues
334+
335+
| Issue | Ticket | Status |
336+
|-------|--------|--------|
337+
| Severity filter clears description/attack vector panels | AST-136035 | Fixed |
338+
| Severity filter collapses entire results tree | AST-136035 | Fixed |
339+
| Authentication logs not routed to Eclipse Error Log | AST-136023 | Fixed |
340+
| Custom State dropdown occupies entire screen | AST-137779 | Fixed |
341+
| Scan ID combo overflows window on small screens | AST-136035 | Fixed |
342+
| New scan ID not marked as latest in scan list after notification | AST-137779 | Open |
343+
344+
---
345+
346+
*Generated for AST-146800 · Checkmarx Integrations Team*

0 commit comments

Comments
 (0)