feat: support image scan in cli

Author: soul2zimate

README.md

@@ -609,6 +609,22 @@ Options:
 - `--summary` - Output summary in JSON format
 - (default) - Output full report in JSON format
 
+**Image Analysis**
+```shell
+java -jar trustify-da-java-client-cli.jar image <image_ref> [<image_ref>...] [--summary|--html]
+```
+Perform security analysis on the specified container image(s).
+
+Arguments:
+- `<image_ref>` - Container image reference (e.g., `nginx:latest`, `registry.io/image:tag`)
+- Multiple images can be analyzed at once
+- Optionally specify platform with `^^` notation (e.g., `image:tag^^linux/amd64`)
+
+Options:
+- `--summary` - Output summary in JSON format
+- `--html` - Output full report in HTML format
+- (default) - Output full report in JSON format
+
 #### Backend Configuration
 
 The client requires the backend URL to be configured through the environment variable:
@@ -637,6 +653,18 @@ java -jar trustify-da-java-client-cli.jar component /path/to/requirements.txt
 # Component analysis with summary
 java -jar trustify-da-java-client-cli.jar component /path/to/go.mod --summary
 
+# Container image analysis with JSON output (default)
+java -jar trustify-da-java-client-cli.jar image nginx:latest
+
+# Multiple container image analysis
+java -jar trustify-da-java-client-cli.jar image nginx:latest docker.io/library/node:18
+
+# Container image analysis with platform specification
+java -jar trustify-da-java-client-cli.jar image nginx:latest^^linux/amd64 --summary
+
+# Container image analysis with HTML output
+java -jar trustify-da-java-client-cli.jar image quay.io/redhat/ubi8:latest --html
+
 # Show help
 java -jar trustify-da-java-client-cli.jar --help
 ```

src/main/java/io/github/guacsec/trustifyda/cli/App.java

@@ -27,13 +27,17 @@
 import io.github.guacsec.trustifyda.api.v5.AnalysisReport;
 import io.github.guacsec.trustifyda.api.v5.ProviderReport;
 import io.github.guacsec.trustifyda.api.v5.SourceSummary;
+import io.github.guacsec.trustifyda.image.ImageRef;
+import io.github.guacsec.trustifyda.image.ImageUtils;
 import io.github.guacsec.trustifyda.impl.ExhortApi;
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.Map;
+import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutionException;
 
@@ -82,25 +86,81 @@ private static CliArgs parseArgs(String[] args) {
 
     Command command = parseCommand(args[0]);
 
+    switch (command) {
+      case STACK:
+      case COMPONENT:
+        return parseFileBasedArgs(command, args);
+      case IMAGE:
+        return parseImageBasedArgs(command, args);
+      default:
+        throw new IllegalArgumentException("Unsupported command: " + command);
+    }
+  }
+
+  private static CliArgs parseFileBasedArgs(Command command, String[] args) {
+    if (args.length < 2) {
+      throw new IllegalArgumentException("Missing required file path for " + command + " command");
+    }
+
     Path path = validateFile(args[1]);
 
     OutputFormat outputFormat = OutputFormat.JSON;
     if (args.length == 3) {
       outputFormat = parseOutputFormat(command, args[2]);
+    } else if (args.length > 3) {
+      throw new IllegalArgumentException("Too many arguments for " + command + " command");
     }
 
     return new CliArgs(command, path, outputFormat);
   }
 
+  private static CliArgs parseImageBasedArgs(Command command, String[] args) {
+    if (args.length < 2) {
+      throw new IllegalArgumentException(
+          "Missing required image references for " + command + " command");
+    }
+
+    OutputFormat outputFormat = OutputFormat.JSON;
+    int imageArgCount = args.length - 1;
+
+    if (args.length >= 3) {
+      String lastArg = args[args.length - 1];
+      if (lastArg.startsWith("--")) {
+        outputFormat = parseOutputFormat(command, lastArg);
+        imageArgCount = args.length - 2;
+      }
+    }
+
+    if (imageArgCount < 1) {
+      throw new IllegalArgumentException(
+          "At least one image reference is required for " + command + " command");
+    }
+
+    Set<ImageRef> imageRefs = new HashSet<>();
+    for (int i = 1; i <= imageArgCount; i++) {
+      try {
+        ImageRef imageRef = ImageUtils.parseImageRef(args[i]);
+        imageRefs.add(imageRef);
+      } catch (Exception e) {
+        throw new IllegalArgumentException(
+            "Invalid image reference '" + args[i] + "': " + e.getMessage(), e);
+      }
+    }
+
+    return new CliArgs(command, imageRefs, outputFormat);
+  }
+
   private static Command parseCommand(String commandStr) {
     switch (commandStr) {
       case "stack":
         return Command.STACK;
       case "component":
         return Command.COMPONENT;
+      case "image":
+        return Command.IMAGE;
       default:
         throw new IllegalArgumentException(
-            "Unknown command: " + commandStr + ". Use 'stack' or 'component'");
+            "Unknown command: " + commandStr + ". Use 'stack', 'component', or 'image'");
     }
   }
 
@@ -109,8 +169,9 @@ private static OutputFormat parseOutputFormat(Command command, String formatArg)
       case "--summary":
         return OutputFormat.SUMMARY;
       case "--html":
-        if (command != Command.STACK) {
-          throw new IllegalArgumentException("HTML format is only supported for stack command");
+        if (command != Command.STACK && command != Command.IMAGE) {
+          throw new IllegalArgumentException(
+              "HTML format is only supported for stack and image commands");
         }
         return OutputFormat.HTML;
       default:
@@ -137,6 +198,8 @@ private static CompletableFuture<String> executeCommand(CliArgs args) throws IOE
       case COMPONENT:
         return executeComponentAnalysis(
             args.filePath.toAbsolutePath().toString(), args.outputFormat);
+      case IMAGE:
+        return executeImageAnalysis(args.imageRefs, args.outputFormat);
       default:
         throw new AssertionError();
     }
@@ -178,6 +241,44 @@ private static String toJsonString(Object obj) {
     }
   }
 
+  private static CompletableFuture<String> executeImageAnalysis(
+      Set<ImageRef> imageRefs, OutputFormat outputFormat) throws IOException {
+    Api api = new ExhortApi();
+    switch (outputFormat) {
+      case JSON:
+        return api.imageAnalysis(imageRefs).thenApply(App::formatImageAnalysisResult);
+      case HTML:
+        return api.imageAnalysisHtml(imageRefs).thenApply(bytes -> new String(bytes));
+      case SUMMARY:
+        return api.imageAnalysis(imageRefs)
+            .thenApply(App::extractImageSummary)
+            .thenApply(App::toJsonString);
+      default:
+        throw new AssertionError();
+    }
+  }
+
+  private static String formatImageAnalysisResult(Map<ImageRef, AnalysisReport> analysisResults) {
+    try {
+      return MAPPER.writeValueAsString(analysisResults);
+    } catch (JsonProcessingException e) {
+      throw new RuntimeException("Failed to serialize image analysis results", e);
+    }
+  }
+
+  private static Map<String, Map<String, SourceSummary>> extractImageSummary(
+      Map<ImageRef, AnalysisReport> analysisResults) {
+    Map<String, Map<String, SourceSummary>> imageSummaries = new HashMap<>();
+
+    for (Map.Entry<ImageRef, AnalysisReport> entry : analysisResults.entrySet()) {
+      String imageKey = entry.getKey().toString();
+      Map<String, SourceSummary> imageSummary = extractSummary(entry.getValue());
+      imageSummaries.put(imageKey, imageSummary);
+    }
+
+    return imageSummaries;
+  }
+
   private static Map<String, SourceSummary> extractSummary(AnalysisReport report) {
     Map<String, SourceSummary> summary = new HashMap<>();
     if (report.getProviders() == null) {

src/main/java/io/github/guacsec/trustifyda/cli/CliArgs.java

@@ -16,16 +16,27 @@
  */
 package io.github.guacsec.trustifyda.cli;
 
+import io.github.guacsec.trustifyda.image.ImageRef;
 import java.nio.file.Path;
+import java.util.Set;
 
 public class CliArgs {
   public final Command command;
   public final Path filePath;
+  public final Set<ImageRef> imageRefs;
   public final OutputFormat outputFormat;
 
   public CliArgs(Command command, Path filePath, OutputFormat outputFormat) {
     this.command = command;
     this.filePath = filePath;
+    this.imageRefs = null;
+    this.outputFormat = outputFormat;
+  }
+
+  public CliArgs(Command command, Set<ImageRef> imageRefs, OutputFormat outputFormat) {
+    this.command = command;
+    this.filePath = null;
+    this.imageRefs = imageRefs;
     this.outputFormat = outputFormat;
   }
 }

src/main/java/io/github/guacsec/trustifyda/cli/Command.java

@@ -18,5 +18,6 @@
 
 public enum Command {
   STACK,
-  COMPONENT
+  COMPONENT,
+  IMAGE
 }

src/main/java/io/github/guacsec/trustifyda/image/ImageUtils.java

@@ -105,6 +105,45 @@ static String updatePATHEnv(String execPath) {
     }
   }
 
+  /**
+   * Parse an image reference string that may contain architecture specification using ^^ notation.
+   * Examples: - "docker.io/library/node:18" -> ImageRef with no specific platform -
+   * "docker.io/library/node:18^^amd64" -> ImageRef with amd64 platform -
+   * "httpd:2.4.49^^linux/amd64" -> ImageRef with linux/amd64 platform
+   *
+   * @param imageRefString the image reference string
+   * @return ImageRef object
+   * @throws IllegalArgumentException if the format is invalid
+   */
+  public static ImageRef parseImageRef(String imageRefString) {
+    if (imageRefString == null || imageRefString.trim().isEmpty()) {
+      throw new IllegalArgumentException("Image reference cannot be null or empty");
+    }
+
+    String[] parts = imageRefString.split("\\^\\^", 2);
+
+    if (parts.length == 1) {
+      // Simple case: "docker.io/library/node:18"
+      return new ImageRef(parts[0].trim(), null);
+    } else if (parts.length == 2) {
+      // Architecture case: "docker.io/library/node:18^^amd64"
+      String imageRef = parts[0].trim();
+      String platform = parts[1].trim();
+      if (imageRef.isEmpty()) {
+        throw new IllegalArgumentException("Image reference cannot be empty before ^^");
+      }
+      if (platform.isEmpty()) {
+        throw new IllegalArgumentException("Platform specification cannot be empty after ^^");
+      }
+      return new ImageRef(imageRef, platform);
+    } else {
+      throw new IllegalArgumentException(
+          "Invalid image reference format: "
+              + imageRefString
+              + ". Use 'image' or 'image^^platform'");
+    }
+  }
+
   public static JsonNode generateImageSBOM(ImageRef imageRef)
       throws IOException, MalformedPackageURLException {
     var output = execSyft(imageRef);

src/main/resources/cli_help.txt

@@ -1,7 +1,7 @@
 Dependency Analytics Java API CLI
 
 USAGE:
-  java -jar trustify-da-java-client-cli.jar <COMMAND> <FILE_PATH> [OPTIONS]
+  java -jar trustify-da-java-client-cli.jar <COMMAND> <ARGUMENTS> [OPTIONS]
 
 COMMANDS:
   stack <file_path> [--summary|--html]
@@ -17,6 +17,17 @@ COMMANDS:
       --summary    Output summary in JSON format
       (default)    Output full report in JSON format
 
+  image <image_ref> [<image_ref>...] [--summary|--html]
+    Perform security analysis on the specified container image(s)
+    Arguments:
+      <image_ref>  Container image reference (e.g., nginx:latest, registry.io/image:tag)
+                   Multiple images can be analyzed at once
+                   Optionally specify platform with ^^ notation (e.g., image:tag^^linux/amd64)
+    Options:
+      --summary    Output summary in JSON format
+      --html       Output full report in HTML format
+      (default)    Output full report in JSON format
+
 OPTIONS:
   -h, --help     Show this help message
 
@@ -26,7 +37,14 @@ ENVIRONMENT VARIABLES:
 EXAMPLES:
   export TRUSTIFY_DA_BACKEND_URL=https://your-backend.url
 
+  # File-based analysis
   java -jar trustify-da-java-client-cli.jar stack /path/to/pom.xml
   java -jar trustify-da-java-client-cli.jar stack /path/to/package.json --summary
   java -jar trustify-da-java-client-cli.jar stack /path/to/build.gradle --html
   java -jar trustify-da-java-client-cli.jar component /path/to/requirements.txt
+
+  # Container image analysis
+  java -jar trustify-da-java-client-cli.jar image nginx:latest
+  java -jar trustify-da-java-client-cli.jar image nginx:latest docker.io/library/node:18
+  java -jar trustify-da-java-client-cli.jar image nginx:latest^^linux/amd64 --summary
+  java -jar trustify-da-java-client-cli.jar image quay.io/redhat/ubi8:latest --html

src/test/java/io/github/guacsec/trustifyda/image/ImageUtilsTest.java

@@ -1109,4 +1109,42 @@ void test_get_single_image_digest_empty() throws JsonProcessingException {
       assertEquals(expectedDigests, digests);
     }
   }
+
+  @Test
+  void test_parseImageRef_withDigests() {
+    // Test simple case - image without platform specification
+    String imageWithDigest =
+        "nginx:1.21@sha256:abc123def456abc123def456abc123def456abc123def456abc123def456abc1";
+    ImageRef result = ImageUtils.parseImageRef(imageWithDigest);
+
+    assertEquals(
+        "nginx:1.21@sha256:abc123def456abc123def456abc123def456abc123def456abc123def456abc1",
+        result.getImage().getFullName());
+    assertNull(result.getPlatform());
+
+    // Test with platform specification using ^^ notation
+    String imageWithPlatform =
+        "alpine:3.14@sha256:def456abc123def456abc123def456abc123def456abc123def456abc123def4^^linux/amd64";
+    result = ImageUtils.parseImageRef(imageWithPlatform);
+
+    assertEquals(
+        "alpine:3.14@sha256:def456abc123def456abc123def456abc123def456abc123def456abc123def4",
+        result.getImage().getFullName());
+    assertEquals("linux/amd64", result.getPlatform().toString());
+
+    // Test with complex registry and platform
+    String complexImage =
+        "quay.io/redhat/ubi8:8.9@sha256:fedcba987654fedcba987654fedcba987654fedcba987654fedcba987654fedcba^^linux/arm64";
+    result = ImageUtils.parseImageRef(complexImage);
+
+    assertEquals(
+        "quay.io/redhat/ubi8:8.9@sha256:fedcba987654fedcba987654fedcba987654fedcba987654fedcba987654fedcba",
+        result.getImage().getFullName());
+
+    // Platform class may normalize arm64 to arm64/v8
+    String platform = result.getPlatform().toString();
+    assertTrue(
+        platform.equals("linux/arm64") || platform.equals("linux/arm64/v8"),
+        "Expected linux/arm64 or linux/arm64/v8, got: " + platform);
+  }
 }