Merge pull request #148 from Contrast-Security-OSS/AIML-223

AIML-223: Add SESSION_METADATA expansion support for trace queries

Author: ChrisEdwards

sdk/src/main/java/com/contrastsecurity/http/TraceFilterForm.java

@@ -65,7 +65,8 @@ public enum TraceExpandValue {
     REQUEST,
     APPLICATION,
     SERVERS,
-    SERVER_ENVIRONMENTS;
+    SERVER_ENVIRONMENTS,
+    SESSION_METADATA;
 
     public String toURIString() {
       return name().toLowerCase();

sdk/src/main/java/com/contrastsecurity/http/UrlBuilder.java

@@ -207,6 +207,12 @@ public String getTracesWithBodyUrl(String organizationId, String appId)
     return String.format("/ng/%s/traces/%s/filter", organizationId, appId);
   }
 
+  public String getTracesWithBodyUrl(
+      String organizationId, String appId, EnumSet<TraceFilterForm.TraceExpandValue> expandValues) {
+    return String.format(
+        "/ng/%s/traces/%s/filter%s", organizationId, appId, buildExpand(expandValues));
+  }
+
   public String getSessionMetadataForApplicationUrl(
       String organizationId, String appId, TraceFilterForm form)
       throws UnsupportedEncodingException {

sdk/src/main/java/com/contrastsecurity/models/MetadataItem.java

@@ -0,0 +1,64 @@
+package com.contrastsecurity.models;
+
+/*-
+ * #%L
+ * Contrast Java SDK
+ * %%
+ * Copyright (C) 2022 - 2025 Contrast Security, Inc.
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+import com.google.gson.annotations.SerializedName;
+
+/** A single metadata item within session metadata. */
+public class MetadataItem {
+
+  /**
+   * Return the value of this metadata item.
+   *
+   * @return the metadata value
+   */
+  public String getValue() {
+    return value;
+  }
+
+  private String value;
+
+  /**
+   * Return the display label for this metadata item. This is the human-readable label shown in the
+   * Contrast UI.
+   *
+   * @return the display label
+   */
+  public String getDisplayLabel() {
+    return displayLabel;
+  }
+
+  @SerializedName("display_label")
+  private String displayLabel;
+
+  /**
+   * Return the agent label for this metadata item. This is the internal label used by the Contrast
+   * agent.
+   *
+   * @return the agent label
+   */
+  public String getAgentLabel() {
+    return agentLabel;
+  }
+
+  @SerializedName("agent_label")
+  private String agentLabel;
+}

sdk/src/main/java/com/contrastsecurity/models/SessionMetadata.java

@@ -0,0 +1,54 @@
+package com.contrastsecurity.models;
+
+/*-
+ * #%L
+ * Contrast Java SDK
+ * %%
+ * Copyright (C) 2022 - 2025 Contrast Security, Inc.
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+import com.google.gson.annotations.SerializedName;
+import java.util.List;
+
+/**
+ * Session metadata associated with a trace. Contains metadata items collected during the session
+ * when the vulnerability was detected.
+ */
+public class SessionMetadata {
+
+  /**
+   * Return the session ID for this metadata.
+   *
+   * @return the session identifier
+   */
+  public String getSessionId() {
+    return sessionId;
+  }
+
+  @SerializedName("session_id")
+  private String sessionId;
+
+  /**
+   * Return the list of metadata items for this session.
+   *
+   * @return list of metadata items
+   */
+  public List<MetadataItem> getMetadata() {
+    return metadata;
+  }
+
+  private List<MetadataItem> metadata;
+}

sdk/src/main/java/com/contrastsecurity/models/Trace.java

@@ -343,6 +343,24 @@ public List<String> getTags() {
   @SerializedName("tags")
   private List<String> tags;
 
+  /**
+   * Return the session metadata for this trace. Session metadata contains custom key-value pairs
+   * collected by the Contrast agent during the session when this vulnerability was detected.
+   *
+   * <p>Note: This field requires the expand parameter to be set. Use {@link
+   * com.contrastsecurity.http.TraceFilterForm.TraceExpandValue#SESSION_METADATA} when querying
+   * traces to populate this field.
+   *
+   * @return list of session metadata objects containing session IDs and metadata items, or null if
+   *     not expanded
+   */
+  public List<SessionMetadata> getSessionMetadata() {
+    return sessionMetadata;
+  }
+
+  @SerializedName("session_metadata")
+  private List<SessionMetadata> sessionMetadata;
+
   @Override
   public boolean equals(Object o) {
     if (this == o) return true;

sdk/src/main/java/com/contrastsecurity/models/TraceFilterBody.java

@@ -47,4 +47,5 @@ public class TraceFilterBody {
   private boolean untracked;
   private List<String> urls;
   private List<String> vulnTypes;
+  private String agentSessionId;
 }

sdk/src/main/java/com/contrastsecurity/sdk/ContrastSDK.java

@@ -800,10 +800,31 @@ public Traces getTraces(String organizationId, String appId, TraceFilterForm for
    */
   public Traces getTraces(String organizationId, String appId, TraceFilterBody filters)
       throws IOException, UnauthorizedException {
+    return getTraces(organizationId, appId, filters, null);
+  }
+
+  /**
+   * Get the vulnerabilities in the application that match specific metadata filters with expanded
+   * fields.
+   *
+   * @param organizationId the ID of the organization
+   * @param appId the ID of the application
+   * @param filters TraceMetadataFilters filters to query on
+   * @param expand the fields to expand (e.g., SESSION_METADATA, SERVER_ENVIRONMENTS)
+   * @return Traces object that contains the list of Trace's
+   * @throws UnauthorizedException if the Contrast account failed to authorize
+   * @throws IOException if there was a communication problem
+   */
+  public Traces getTraces(
+      String organizationId,
+      String appId,
+      TraceFilterBody filters,
+      EnumSet<TraceFilterForm.TraceExpandValue> expand)
+      throws IOException, UnauthorizedException {
     try (InputStream is =
             makeRequestWithBody(
                 HttpMethod.POST,
-                urlBuilder.getTracesWithBodyUrl(organizationId, appId),
+                urlBuilder.getTracesWithBodyUrl(organizationId, appId, expand),
                 this.gson.toJson(filters),
                 MediaType.JSON);
         Reader reader = new InputStreamReader(is)) {

sdk/src/test/java/com/contrastsecurity/GsonTest.java

@@ -36,6 +36,7 @@
 import com.contrastsecurity.models.Rules;
 import com.contrastsecurity.models.SecurityCheck;
 import com.contrastsecurity.models.Servers;
+import com.contrastsecurity.models.SessionMetadata;
 import com.contrastsecurity.models.Story;
 import com.contrastsecurity.models.StoryResponse;
 import com.contrastsecurity.models.Tags;
@@ -334,4 +335,34 @@ public void testGetTracesWithServerEnvironmentsAndTags() {
     assertThat(trace.getTags()).hasSize(3);
     assertThat(trace.getTags()).containsExactly("SmartFix Remediated", "Custom Tag", "test-tag");
   }
+
+  @Test
+  public void testGetTracesWithSessionMetadata() {
+
+    String tracesString =
+        "{\"count\":1,\"traces\":[{\"title\":\"Test Vulnerability\",\"language\":\"Java\",\"status\":\"Reported\",\"uuid\":\"TEST-1234-5678-ABCD\",\"rule_name\":\"test-rule\",\"severity\":\"High\",\"likelihood\":\"Medium\",\"impact\":\"High\",\"confidence\":\"High\",\"first_time_seen\":1461600923859,\"last_time_seen\":1461601039100,\"category\":\"Injection\",\"platform\":\"Oracle Corporation\",\"total_traces_received\":3,\"visible\":true,\"session_metadata\":[{\"session_id\":\"session-123\",\"metadata\":[{\"value\":\"prod\",\"display_label\":\"Environment\",\"agent_label\":\"env\"},{\"value\":\"user123\",\"display_label\":\"User ID\",\"agent_label\":\"user_id\"}]}]}]}";
+
+    Traces traces = gson.fromJson(tracesString, Traces.class);
+
+    assertThat(traces).isNotNull();
+    assertThat(traces.getTraces()).isNotNull();
+    assertThat(traces.getCount()).isEqualTo(1);
+
+    Trace trace = traces.getTraces().get(0);
+    assertThat(trace.getSessionMetadata()).isNotNull();
+    assertThat(trace.getSessionMetadata()).hasSize(1);
+
+    SessionMetadata sessionMetadata = trace.getSessionMetadata().get(0);
+    assertThat(sessionMetadata.getSessionId()).isEqualTo("session-123");
+    assertThat(sessionMetadata.getMetadata()).isNotNull();
+    assertThat(sessionMetadata.getMetadata()).hasSize(2);
+
+    assertThat(sessionMetadata.getMetadata().get(0).getValue()).isEqualTo("prod");
+    assertThat(sessionMetadata.getMetadata().get(0).getDisplayLabel()).isEqualTo("Environment");
+    assertThat(sessionMetadata.getMetadata().get(0).getAgentLabel()).isEqualTo("env");
+
+    assertThat(sessionMetadata.getMetadata().get(1).getValue()).isEqualTo("user123");
+    assertThat(sessionMetadata.getMetadata().get(1).getDisplayLabel()).isEqualTo("User ID");
+    assertThat(sessionMetadata.getMetadata().get(1).getAgentLabel()).isEqualTo("user_id");
+  }
 }

sdk/src/test/java/com/contrastsecurity/http/TraceFilterFormTest.java

@@ -81,6 +81,29 @@ public void toQuery_should_include_multiple_expand_parameters()
     assertThat(actual).isEqualTo(expected);
   }
 
+  @Test
+  public void toQuery_should_include_session_metadata_expand_parameter()
+      throws UnsupportedEncodingException {
+    final String expected = "?expand=session_metadata&tracked=true&untracked=false";
+    form.setExpand(EnumSet.of(TraceFilterForm.TraceExpandValue.SESSION_METADATA));
+    final String actual = form.toQuery();
+
+    assertThat(actual).isEqualTo(expected);
+  }
+
+  @Test
+  public void toQuery_should_include_multiple_expand_parameters_with_session_metadata()
+      throws UnsupportedEncodingException {
+    final String expected = "?expand=servers,session_metadata&tracked=true&untracked=false";
+    form.setExpand(
+        EnumSet.of(
+            TraceFilterForm.TraceExpandValue.SERVERS,
+            TraceFilterForm.TraceExpandValue.SESSION_METADATA));
+    final String actual = form.toQuery();
+
+    assertThat(actual).isEqualTo(expected);
+  }
+
   @Test
   public void toQuery_should_url_encode_filterTags_with_special_characters()
       throws UnsupportedEncodingException {

sdk/src/test/java/com/contrastsecurity/http/UrlBuilderTest.java

@@ -153,6 +153,38 @@ public void testGetTracesWithBodyUrl() throws UnsupportedEncodingException {
         .isEqualTo(expectedUrl);
   }
 
+  @Test
+  public void testGetTracesWithBodyUrlWithSingleExpand() {
+    String expectedUrl = "/ng/test-org/traces/test-app/filter?expand=session_metadata";
+
+    EnumSet<TraceFilterForm.TraceExpandValue> expand =
+        EnumSet.of(TraceFilterForm.TraceExpandValue.SESSION_METADATA);
+
+    assertThat(urlBuilder.getTracesWithBodyUrl(organizationId, applicationId, expand))
+        .isEqualTo(expectedUrl);
+  }
+
+  @Test
+  public void testGetTracesWithBodyUrlWithMultipleExpand() {
+    String expectedUrl = "/ng/test-org/traces/test-app/filter?expand=servers,session_metadata";
+
+    EnumSet<TraceFilterForm.TraceExpandValue> expand =
+        EnumSet.of(
+            TraceFilterForm.TraceExpandValue.SESSION_METADATA,
+            TraceFilterForm.TraceExpandValue.SERVERS);
+
+    assertThat(urlBuilder.getTracesWithBodyUrl(organizationId, applicationId, expand))
+        .isEqualTo(expectedUrl);
+  }
+
+  @Test
+  public void testGetTracesWithBodyUrlWithNullExpand() {
+    String expectedUrl = "/ng/test-org/traces/test-app/filter";
+
+    assertThat(urlBuilder.getTracesWithBodyUrl(organizationId, applicationId, null))
+        .isEqualTo(expectedUrl);
+  }
+
   @Test
   public void testSecurityCheckUrl() {
     String expectedSecurityCheckUrl = "/ng/test-org/securityChecks";