diff --git a/src/main/java/com/checkmarx/ast/telemetry/TelemetryEvent.java b/src/main/java/com/checkmarx/ast/telemetry/TelemetryEvent.java new file mode 100644 index 00000000..7ac401ec --- /dev/null +++ b/src/main/java/com/checkmarx/ast/telemetry/TelemetryEvent.java @@ -0,0 +1,60 @@ +package com.checkmarx.ast.telemetry; + +import lombok.Builder; +import lombok.Getter; +import lombok.Singular; + +import java.util.Map; + +/** + * Attributes of a Dev Assist telemetry event sent through {@code cx telemetry ai}. + *

+ * Only non-blank values are forwarded to the CLI. The CLI itself adds the session, unique and machine identifiers. + * Event specific values (for example {@code installationId}, {@code authMethod}, {@code vulnerabilityId}, + * {@code remediationMode}) go in {@link #eventAttributes} and are sent as a single + * {@code --event-attributes "key=value;key=value"} argument, which the CLI nests under {@code eventAttributes}. + */ +@Getter +@Builder +public class TelemetryEvent { + /** AI provider name (e.g. "Copilot"). */ + private final String aiProvider; + /** Event type (e.g. "click", "authentication", "Scan"). */ + private final String eventType; + /** Event sub type (e.g. "fixWithAIChat"). */ + private final String subType; + /** Scan engine (e.g. "Oss", "Secrets", "IaC", "Asca", "Containers"). */ + private final String engine; + /** Severity of the problem the event relates to. */ + private final String problemSeverity; + /** Scan type for scan events. */ + private final String scanType; + /** Event status (e.g. "success"). */ + private final String status; + /** Detailed status / failure reason. */ + private final String statusResult; + /** Number of findings, sent only when not null. */ + private final Integer totalCount; + /** + * IDE or agent name (e.g. "Eclipse"). When set, it is sent as {@code --agent} and replaces + * {@code CxConfig#getAgentName()} for this call. When blank, the configured agent name is used. + */ + private final String agent; + /** Version of the host IDE / agent. */ + private final String agentVersion; + /** Version of the Checkmarx plugin. */ + private final String cxPluginVersion; + /** Plugin type (e.g. "IDE"). */ + private final String pluginType; + /** Repository URL of the scanned project. */ + private final String repoUrl; + /** Telemetry API version (e.g. "v2"). Sent as the top-level {@code --api-version} flag, like the JavaScript wrapper. */ + private final String apiVersion; + /** + * Event specific attributes, sent as {@code --event-attributes key=value;key=value}. + * Entries with a blank value or an invalid key (blank, or containing ';' or '=') are left out, + * and ';' inside a value is replaced with '_'. + */ + @Singular + private final Map eventAttributes; +} diff --git a/src/main/java/com/checkmarx/ast/wrapper/CxConfig.java b/src/main/java/com/checkmarx/ast/wrapper/CxConfig.java index ab0a7329..1c7c5576 100644 --- a/src/main/java/com/checkmarx/ast/wrapper/CxConfig.java +++ b/src/main/java/com/checkmarx/ast/wrapper/CxConfig.java @@ -32,6 +32,14 @@ public void setAdditionalParameters(String additionalParameters) { } List toArguments() { + return toArguments(true); + } + + /** + * @param includeAgent when false, {@code --agent} is not added, so a caller that sends its own agent + * (e.g. a telemetry event) does not send the flag twice. + */ + List toArguments(boolean includeAgent) { List commands = new ArrayList<>(); if (StringUtils.isNotBlank(getClientId()) && StringUtils.isNotBlank(getApiKey())) { @@ -66,7 +74,7 @@ List toArguments() { commands.add(CxConstants.BASE_AUTH_URI); commands.add(getBaseAuthUri()); } - if (getAgentName() != null && !getAgentName().isEmpty()) { + if (includeAgent && getAgentName() != null && !getAgentName().isEmpty()) { commands.add("--agent"); commands.add(getAgentName()); } diff --git a/src/main/java/com/checkmarx/ast/wrapper/CxConstants.java b/src/main/java/com/checkmarx/ast/wrapper/CxConstants.java index 60675448..48f4019b 100644 --- a/src/main/java/com/checkmarx/ast/wrapper/CxConstants.java +++ b/src/main/java/com/checkmarx/ast/wrapper/CxConstants.java @@ -94,6 +94,13 @@ public final class CxConstants { static final String SCAN_TYPE_FLAG = "--scan-type"; static final String STATUS = "--status"; static final String TOTAL_COUNT = "--total-count"; + static final String STATUS_RESULT = "--status-result"; + static final String AGENT_VERSION = "--agent-version"; + static final String CX_PLUGIN_VERSION = "--cx-plugin-version"; + static final String PLUGIN_TYPE = "--plugin-type"; + static final String REPO_URL = "--repo-url"; + static final String API_VERSION = "--api-version"; + static final String EVENT_ATTRIBUTES = "--event-attributes"; static final String DOCKER = "docker"; static final String PODMAN = "podman"; static final String PODMAN_FALLBACK_PATH = "/usr/local/bin/podman"; diff --git a/src/main/java/com/checkmarx/ast/wrapper/CxWrapper.java b/src/main/java/com/checkmarx/ast/wrapper/CxWrapper.java index 6e73560d..261227cb 100644 --- a/src/main/java/com/checkmarx/ast/wrapper/CxWrapper.java +++ b/src/main/java/com/checkmarx/ast/wrapper/CxWrapper.java @@ -19,6 +19,7 @@ import com.checkmarx.ast.results.ResultsSummary; import com.checkmarx.ast.results.result.Node; import com.checkmarx.ast.scan.Scan; +import com.checkmarx.ast.telemetry.TelemetryEvent; import com.checkmarx.ast.tenant.TenantSetting; import com.checkmarx.ast.utils.JsonParser; import com.fasterxml.jackson.databind.ObjectMapper; @@ -816,6 +817,85 @@ public String telemetryAIEvent(String aiProvider, String agent, String eventType return Execution.executeCommand(withConfigArguments(arguments), logger, line -> line); } + /** + * Executes the telemetry AI command with the extended Dev Assist analytics attributes. + * Blank attributes are not sent to the CLI. Event specific attributes are sent as one + * {@code --event-attributes key=value;key=value} argument. When {@link TelemetryEvent#getAgent()} is set it + * replaces {@link CxConfig#getAgentName()} for this call, so {@code --agent} is never sent twice. + * + * @param event the telemetry event attributes + * @return Command output as string + * @throws IOException if I/O error occurs + * @throws InterruptedException if command execution is interrupted + * @throws CxException if CLI command fails + */ + public String telemetryAIEvent(@NonNull TelemetryEvent event) + throws IOException, InterruptedException, CxException { + this.logger.info("Executing telemetry AI event with provider: {}, type: {}, subType: {}", + event.getAiProvider(), event.getEventType(), event.getSubType()); + + boolean includeConfigAgent = StringUtils.isBlank(event.getAgent()); + List arguments = new ArrayList<>(); + arguments.add(this.executable); + arguments.addAll(buildTelemetryArguments(event)); + arguments.addAll(this.cxConfig.toArguments(includeConfigAgent)); + return Execution.executeCommand(arguments, logger, line -> line); + } + + static List buildTelemetryArguments(TelemetryEvent event) { + List arguments = new ArrayList<>(); + arguments.add(CxConstants.CMD_TELEMETRY); + arguments.add(CxConstants.SUB_CMD_TELEMETRY_AI); + addIfNotBlank(arguments, CxConstants.AI_PROVIDER, event.getAiProvider()); + addIfNotBlank(arguments, CxConstants.TYPE, event.getEventType()); + addIfNotBlank(arguments, CxConstants.SUB_TYPE, event.getSubType()); + addIfNotBlank(arguments, CxConstants.ENGINE, event.getEngine()); + addIfNotBlank(arguments, CxConstants.PROBLEM_SEVERITY, event.getProblemSeverity()); + addIfNotBlank(arguments, CxConstants.SCAN_TYPE_FLAG, event.getScanType()); + addIfNotBlank(arguments, CxConstants.STATUS, event.getStatus()); + if (event.getTotalCount() != null && event.getTotalCount() >= 0) { + arguments.add(CxConstants.TOTAL_COUNT); + arguments.add(event.getTotalCount().toString()); + } + addIfNotBlank(arguments, CxConstants.AGENT, event.getAgent()); + addIfNotBlank(arguments, CxConstants.AGENT_VERSION, event.getAgentVersion()); + addIfNotBlank(arguments, CxConstants.CX_PLUGIN_VERSION, event.getCxPluginVersion()); + addIfNotBlank(arguments, CxConstants.PLUGIN_TYPE, event.getPluginType()); + addIfNotBlank(arguments, CxConstants.STATUS_RESULT, event.getStatusResult()); + addIfNotBlank(arguments, CxConstants.REPO_URL, event.getRepoUrl()); + addIfNotBlank(arguments, CxConstants.API_VERSION, event.getApiVersion()); + addIfNotBlank(arguments, CxConstants.EVENT_ATTRIBUTES, serializeEventAttributes(event.getEventAttributes())); + return arguments; + } + + /** + * Serializes attributes as {@code key=value;key=value}. Entries with a blank value or an invalid key + * (blank, or containing ';' or '=') are left out. ';' inside a value is replaced with '_' so it cannot break + * the format; '=' is allowed in a value because the CLI splits each pair on the first '=' only. + */ + static String serializeEventAttributes(Map attributes) { + if (attributes == null || attributes.isEmpty()) { + return ""; + } + List pairs = new ArrayList<>(); + for (Map.Entry entry : attributes.entrySet()) { + String key = entry.getKey(); + String value = entry.getValue(); + if (StringUtils.isBlank(key) || key.contains(";") || key.contains("=") || StringUtils.isBlank(value)) { + continue; + } + pairs.add(key + "=" + value.replace(';', '_')); + } + return String.join(";", pairs); + } + + private static void addIfNotBlank(List arguments, String flag, String value) { + if (StringUtils.isNotBlank(value)) { + arguments.add(flag); + arguments.add(value); + } + } + private int getIndexOfBfLNode(List bflNodes, List resultNodes) { int bflNodeNotFound = -1; diff --git a/src/test/java/com/checkmarx/ast/wrapper/CxWrapperTelemetryArgumentsTest.java b/src/test/java/com/checkmarx/ast/wrapper/CxWrapperTelemetryArgumentsTest.java new file mode 100644 index 00000000..823e18e8 --- /dev/null +++ b/src/test/java/com/checkmarx/ast/wrapper/CxWrapperTelemetryArgumentsTest.java @@ -0,0 +1,169 @@ +package com.checkmarx.ast.wrapper; + +import com.checkmarx.ast.telemetry.TelemetryEvent; +import org.junit.jupiter.api.Test; + +import java.util.Arrays; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.*; + +class CxWrapperTelemetryArgumentsTest { + + @Test + void testBuildTelemetryArguments_allAttributes() { + TelemetryEvent event = TelemetryEvent.builder() + .aiProvider("Copilot") + .eventType("Click") + .subType("fixWithAIChat") + .engine("Oss") + .problemSeverity("High") + .scanType("Oss") + .status("success") + .statusResult("ok") + .totalCount(3) + .agent("Eclipse") + .agentVersion("2024.1") + .cxPluginVersion("2.0.1") + .pluginType("IDE") + .repoUrl("https://github.com/org/repo") + .apiVersion("v2") + .eventAttribute("vulnerabilityId", "CVE-2024-0001") + .eventAttribute("remediationMode", "DevAssist") + .build(); + + List args = CxWrapper.buildTelemetryArguments(event); + + assertEquals(Arrays.asList( + "telemetry", "ai", + "--ai-provider", "Copilot", + "--type", "Click", + "--sub-type", "fixWithAIChat", + "--engine", "Oss", + "--problem-severity", "High", + "--scan-type", "Oss", + "--status", "success", + "--total-count", "3", + "--agent", "Eclipse", + "--agent-version", "2024.1", + "--cx-plugin-version", "2.0.1", + "--plugin-type", "IDE", + "--status-result", "ok", + "--repo-url", "https://github.com/org/repo", + "--api-version", "v2", + "--event-attributes", "vulnerabilityId=CVE-2024-0001;remediationMode=DevAssist"), args); + } + + @Test + void testBuildTelemetryArguments_omitsBlankAndNullAttributes() { + TelemetryEvent event = TelemetryEvent.builder() + .eventType("authentication") + .status("success") + .engine("") + .agent(" ") + .eventAttribute("authMethod", "API_KEY") + .eventAttribute("blank", " ") + .build(); + + List args = CxWrapper.buildTelemetryArguments(event); + + assertEquals(Arrays.asList( + "telemetry", "ai", + "--type", "authentication", + "--status", "success", + "--event-attributes", "authMethod=API_KEY"), args); + } + + @Test + void testBuildTelemetryArguments_noEventAttributesFlagWhenAllAttributesInvalid() { + TelemetryEvent event = TelemetryEvent.builder() + .eventAttribute("a", "") + .eventAttribute("b;c", "1") + .build(); + + assertEquals(Arrays.asList("telemetry", "ai"), CxWrapper.buildTelemetryArguments(event)); + } + + @Test + void testBuildTelemetryArguments_apiVersionIsTopLevelFlagNotAnEventAttribute() { + TelemetryEvent event = TelemetryEvent.builder().eventType("Scan").apiVersion("v2").build(); + + assertEquals(Arrays.asList("telemetry", "ai", "--type", "Scan", "--api-version", "v2"), + CxWrapper.buildTelemetryArguments(event)); + } + + @Test + void testBuildTelemetryArguments_blankApiVersionIsOmitted() { + TelemetryEvent event = TelemetryEvent.builder().apiVersion(" ").build(); + + assertEquals(Arrays.asList("telemetry", "ai"), CxWrapper.buildTelemetryArguments(event)); + } + + @Test + void testBuildTelemetryArguments_zeroTotalCountIsSent() { + TelemetryEvent event = TelemetryEvent.builder().totalCount(0).build(); + + List args = CxWrapper.buildTelemetryArguments(event); + + assertEquals(Arrays.asList("telemetry", "ai", "--total-count", "0"), args); + } + + @Test + void testBuildTelemetryArguments_negativeTotalCountIsOmitted() { + TelemetryEvent event = TelemetryEvent.builder().totalCount(-1).build(); + + assertEquals(Arrays.asList("telemetry", "ai"), CxWrapper.buildTelemetryArguments(event)); + } + + @Test + void testBuildTelemetryArguments_emptyEvent() { + List args = CxWrapper.buildTelemetryArguments(TelemetryEvent.builder().build()); + + assertEquals(Arrays.asList("telemetry", "ai"), args); + } + + @Test + void testSerializeEventAttributes_nullAndEmpty() { + assertEquals("", CxWrapper.serializeEventAttributes(null)); + assertEquals("", CxWrapper.serializeEventAttributes(new LinkedHashMap<>())); + } + + @Test + void testSerializeEventAttributes_keepsInsertionOrder() { + Map attributes = new LinkedHashMap<>(); + attributes.put("apiVersion", "v2"); + attributes.put("authMethod", "API_KEY"); + + assertEquals("apiVersion=v2;authMethod=API_KEY", CxWrapper.serializeEventAttributes(attributes)); + } + + @Test + void testSerializeEventAttributes_sanitizesValuesAndDropsInvalidEntries() { + Map attributes = new LinkedHashMap<>(); + attributes.put("vulnerabilityId", "x;y=z"); + attributes.put("empty", ""); + attributes.put("nullValue", null); + attributes.put("d=x", "2"); + attributes.put("e;y", "3"); + attributes.put(" ", "4"); + + assertEquals("vulnerabilityId=x_y=z", CxWrapper.serializeEventAttributes(attributes)); + } + + @Test + void testConfigArguments_agentIncludedByDefault() { + CxConfig config = CxConfig.builder().apiKey("key").agentName("Eclipse_1.0.0").build(); + + assertEquals(Arrays.asList("--apikey", "key", "--agent", "Eclipse_1.0.0"), config.toArguments()); + assertEquals(config.toArguments(), config.toArguments(true)); + } + + @Test + void testConfigArguments_agentOmittedWhenEventSendsItsOwn() { + CxConfig config = CxConfig.builder().apiKey("key").agentName("Eclipse_1.0.0").build(); + + assertEquals(Arrays.asList("--apikey", "key"), config.toArguments(false)); + } +}