✨ JAVA-3297 Create Scan Project If Not Exists (#36)

Looks up the Contrast Scan project by name, and creates one if it does not exist. Default name is the Maven project name.

Author: gilday

Diff for: scan.http

@@ -0,0 +1,127 @@
+# scan.http
+# HTTP file for experimenting with the scan API
+# To use this file with IntelliJ, create a file http-client.private.env.json with configuration for
+# connecting to your Contrast instance e.g.
+# {
+#   "production": {
+#     "url": "https://app.contrastsecurity.com/Contrast/api",
+#     "apiKey": "<your-api-key>",
+#     "authorization": "<your-authorization-header>",
+#     "organizationId": "<your-organization-id>"
+#   }
+# }
+
+
+### Create Scan Project
+POST {{ url }}/sast/organizations/{{ organizationId }}/projects
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}
+Content-Type: application/json
+
+{
+  "name": "spring-test-application",
+  "language": "JAVA",
+  "includeNamespaceFilters": [],
+  "excludeNamespaceFilters": []
+}
+
+> {% client.global.set("projectId", response.body.id); %}
+
+
+### DELETE Scan Project
+DELETE {{ url }}/sast/organizations/{{ organizationId }}/projects/{{ projectId }}
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}
+
+
+### Find Scan Project
+GET {{ url }}/sast/organizations/{{ organizationId }}/projects?name=spring-test-application&archived=false&unique=true
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}
+Accept: application/json
+
+> {% client.global.set("projectId", response.body.content[0].id); %}
+
+
+### Upload Code Artifact
+
+POST {{ url }}/sast/organizations/{{ organizationId }}/projects/{{ projectId }}/code-artifacts
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}
+Content-Type: multipart/form-data; boundary=WebAppBoundary
+
+--WebAppBoundary
+Content-Disposition: form-data; name="filename"; filename="spring-test-application-0.0.1-SNAPSHOT.jar"
+Content-Type: application/java-archive
+
+< ./target/test-classes/it/spring-boot/target/spring-test-application-0.0.1-SNAPSHOT.jar
+--WebAppBoundary--
+
+> {% client.global.set("artifactId", response.body.id); %}
+
+
+### Start Scan
+
+POST {{ url }}/sast/organizations/{{ organizationId }}/projects/{{ projectId }}/scans
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}
+Content-Type: application/json
+
+{
+  "codeArtifactId": "{{ artifactId }}",
+  "label": "scan.http"
+}
+
+> {% client.global.set("scanId", response.body.id); %}
+
+
+### Cancel Scan
+
+PUT {{ url }}/sast/organizations/{{ organizationId }}/projects/{{ projectId }}/scans/{{ scanId }}
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}
+Content-Type: application/json
+
+{
+  "label": "scan.http",
+  "status": "CANCELLED"
+}
+
+
+### Get Scan
+
+GET {{ url }}/sast/organizations/{{ organizationId }}/projects/{{ projectId }}/scans/{{ scanId }}
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}
+
+
+### Get Scan Results
+
+GET {{ url }}/sast/organizations/{{ organizationId }}/projects/{{ projectId }}/scans/{{ scanId }}/result-instances
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}
+
+
+### Get Scan Results (abreviated)
+
+GET {{ url }}/sast/organizations/{{ organizationId }}/projects/{{ projectId }}/scans/{{ scanId }}/result-instances/info
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}
+
+
+### Get Scan Results Summary
+GET {{ url }}/sast/organizations/{{ organizationId}}/projects/{{ projectId }}/scans/{{ scanId }}/summary
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}
+
+
+### Get Project Results Summary
+GET {{ url }}/sast/organizations/{{ organizationId }}/projects/{{ projectId }}/summary
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}
+
+
+### Get Scan Results in SARIF
+GET {{ url }}/sast/organizations/{{ organizationId }}/projects/{{ projectId }}/scans/{{ scanId }}/raw-output
+API-Key: {{ apiKey }}
+Authorization: {{ authorization }}

Diff for: src/main/java/com/contrastsecurity/maven/plugin/ContrastScanMojo.java

@@ -20,8 +20,11 @@
  * #L%
  */
 
+import com.contrastsecurity.exceptions.UnauthorizedException;
 import com.contrastsecurity.maven.plugin.sdkx.ContrastScanSDK;
+import com.contrastsecurity.maven.plugin.sdkx.CreateProjectRequest;
 import com.contrastsecurity.maven.plugin.sdkx.DefaultContrastScanSDK;
+import com.contrastsecurity.maven.plugin.sdkx.Project;
 import com.contrastsecurity.maven.plugin.sdkx.ScanSummary;
 import com.contrastsecurity.maven.plugin.sdkx.scan.ArtifactScanner;
 import com.contrastsecurity.maven.plugin.sdkx.scan.ScanOperation;
@@ -33,6 +36,7 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.time.Duration;
+import java.util.Collections;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionStage;
 import java.util.concurrent.ExecutionException;
@@ -61,15 +65,14 @@
 public final class ContrastScanMojo extends AbstractContrastMojo {
 
   @Parameter(defaultValue = "${project}", readonly = true)
-  private MavenProject project;
+  private MavenProject mavenProject;
 
   /**
    * Contrast Scan project unique ID to which the plugin runs new Scans. This will be replaced
    * imminently with a project name
    */
-  // TODO[JAVA-3297] replace this with "project"
-  @Parameter(required = true)
-  private String projectId;
+  @Parameter(property = "project", defaultValue = "${project.name}")
+  private String projectName;
 
   /**
    * File path of the Java artifact to upload for scanning. By default, uses the path to this
@@ -113,13 +116,13 @@ public final class ContrastScanMojo extends AbstractContrastMojo {
   private ContrastSDK contrast;
 
   /** visible for testing */
-  String getProjectId() {
-    return projectId;
+  String getProjectName() {
+    return projectName;
   }
 
   /** visible for testing */
-  void setProjectId(final String projectId) {
-    this.projectId = projectId;
+  void setProjectName(final String projectName) {
+    this.projectName = projectName;
   }
 
   /** visible for testing */
@@ -136,21 +139,27 @@ void setConsoleOutput(final boolean consoleOutput) {
   public void execute() throws MojoExecutionException, MojoFailureException {
     // initialize plugin
     initialize();
+    final ContrastScanSDK contrastScan = new DefaultContrastScanSDK(contrast, getURL());
 
     // check that file exists
     final Path file =
-        artifactPath == null ? project.getArtifact().getFile().toPath() : artifactPath.toPath();
+        artifactPath == null
+            ? mavenProject.getArtifact().getFile().toPath()
+            : artifactPath.toPath();
     if (!Files.exists(file)) {
       throw new MojoExecutionException(
           file
               + " does not exist. Make sure to bind the scan goal to a phase that will execute after the artifact to scan has been built");
     }
 
-    final ContrastScanSDK contrastScan = new DefaultContrastScanSDK(contrast, getURL());
+    // get or create project
+    final Project project = findOrCreateProject(contrastScan);
+
+    // start scan
     final ScheduledExecutorService executor = Executors.newSingleThreadScheduledExecutor();
     final ArtifactScanner scanner =
         new ArtifactScanner(
-            executor, contrastScan, getOrganizationId(), getProjectId(), POLL_SCAN_INTERVAL);
+            executor, contrastScan, getOrganizationId(), project.getId(), POLL_SCAN_INTERVAL);
     try {
       getLog().info("Uploading " + file.getFileName() + " to Contrast Scan");
       final ScanOperation operation = scanner.scanArtifact(file, label);
@@ -161,7 +170,7 @@ public void execute() throws MojoExecutionException, MojoFailureException {
       }
 
       // show link in build log
-      final URL clickableScanURL = createClickableScanURL(operation.id());
+      final URL clickableScanURL = createClickableScanURL(project.getId(), operation.id());
       getLog().info("Scan results will be available at " + clickableScanURL.toExternalForm());
 
       // optionally wait for results, output summary to console, output sarif to file system
@@ -174,13 +183,70 @@ public void execute() throws MojoExecutionException, MojoFailureException {
     }
   }
 
+  /**
+   * Finds a Scan project with the project name from the plugin configuration, or creates such a
+   * "Java" project if one does not exist.
+   *
+   * <p>Note: the Scan API does not expose an endpoint for doing this atomically, so it is possible
+   * that another process creates the project after having determined it to not-exist but before
+   * attempting to create it.
+   *
+   * @param contrastScan client with which to make the requests
+   * @return existing or new {@link Project}
+   * @throws MojoExecutionException when fails to make request to the Scan API
+   */
+  private Project findOrCreateProject(final ContrastScanSDK contrastScan)
+      throws MojoExecutionException {
+    final Project project;
+    try {
+      project = contrastScan.findProjectByName(getOrganizationId(), projectName);
+    } catch (final IOException e) {
+      throw new MojoExecutionException("Failed to retrieve project " + projectName, e);
+    } catch (final UnauthorizedException e) {
+      throw new MojoExecutionException(
+          "Authentication failure while retrieving project "
+              + projectName
+              + " - verify Contrast connection configuration",
+          e);
+    }
+    if (project != null) {
+      getLog().debug("Found project with name " + projectName);
+      if (project.isArchived()) {
+        // TODO the behavior of tools like this plugin has yet to be defined with respect to
+        // archived projects; however, the UI exposes no way to archive projects at the moment.
+        // For now, simply log a warning to help debug this in the future should we encounter this
+        // case
+        getLog().warn("Project " + projectName + " is archived");
+      }
+      return project;
+    }
+
+    // project does not exist, so create a new one
+    getLog().debug("No project exists with name " + projectName + " - creating one");
+    final CreateProjectRequest request =
+        new CreateProjectRequest(
+            projectName, "JAVA", Collections.emptyList(), Collections.emptyList());
+    try {
+      return contrastScan.createProject(getOrganizationId(), request);
+    } catch (final IOException e) {
+      throw new MojoExecutionException("Failed to create project " + projectName, e);
+    } catch (final UnauthorizedException e) {
+      throw new MojoExecutionException(
+          "Authentication failure while creating project "
+              + projectName
+              + " - verify Contrast connection configuration",
+          e);
+    }
+  }
+
   /**
    * visible for testing
    *
    * @return Contrast browser application URL for users to click-through and see their scan results
    * @throws MojoExecutionException when the URL is malformed
    */
-  URL createClickableScanURL(final String scanId) throws MojoExecutionException {
+  URL createClickableScanURL(final String projectId, final String scanId)
+      throws MojoExecutionException {
     final String path =
         String.join(
             "/",

Diff for: src/main/java/com/contrastsecurity/maven/plugin/sdkx/ContrastAPIException.java

@@ -21,7 +21,7 @@
  */
 
 /** Indicates an error occurred while using the Contrast HTTP API */
-public class ContrastAPIException extends RuntimeException {
+public class ContrastAPIException extends ContrastException {
 
   private final int status;
 
@@ -47,4 +47,10 @@ public ContrastAPIException(final int status, final String message, final Except
   public int getStatus() {
     return status;
   }
+
+  @Override
+  public String getMessage() {
+    final String message = super.getMessage();
+    return message == null ? String.valueOf(status) : status + " " + super.getMessage();
+  }
 }

Diff for: src/main/java/com/contrastsecurity/maven/plugin/sdkx/ContrastException.java

@@ -0,0 +1,38 @@
+package com.contrastsecurity.maven.plugin.sdkx;
+
+/*-
+ * #%L
+ * Contrast Maven Plugin
+ * %%
+ * Copyright (C) 2021 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%
+ */
+
+/**
+ * Generic {@link RuntimeException} thrown by Contrast code to indicate an unexpected error has
+ * occurred.
+ */
+public class ContrastException extends RuntimeException {
+
+  /** @see RuntimeException#RuntimeException(String) */
+  public ContrastException(final String message) {
+    super(message);
+  }
+
+  /** @see RuntimeException#RuntimeException(String, Throwable) */
+  public ContrastException(final String message, final Throwable inner) {
+    super(message, inner);
+  }
+}

Diff for: src/main/java/com/contrastsecurity/maven/plugin/sdkx/ContrastScanSDK.java

@@ -32,6 +32,30 @@
  */
 public interface ContrastScanSDK {
 
+  /**
+   * Creates a new Scan project.
+   *
+   * @param organizationId unique ID for the user's organization
+   * @param request new project request
+   * @return the new {@link Project}
+   * @throws IOException when an IO error occurs sending the request to the Contrast Scan API
+   * @throws UnauthorizedException when Contrast rejects this request as unauthorized
+   */
+  Project createProject(final String organizationId, final CreateProjectRequest request)
+      throws IOException, UnauthorizedException;
+
+  /**
+   * Scan project lookup.
+   *
+   * @param organizationId unique ID for the user's organization
+   * @param projectName unique project name to find
+   * @return the {@link Project}, or {@code null} if no such project is found
+   * @throws IOException when an IO error occurs sending the query to the Contrast Scan API
+   * @throws UnauthorizedException when Contrast rejects this request as unauthorized
+   */
+  Project findProjectByName(final String organizationId, final String projectName)
+      throws IOException, UnauthorizedException;
+
   /**
    * Transfers a file from the file system to Contrast Scan to create a new code artifact for
    * analysis.