feat: migrate inspect to direct API call (#679)

Migrate docker inspect calls to be direct API calls to the docker daemon
instead of subprocess calls that use the docker CLI. This is a cleaner
approach and mitigates various potential failure scenarios that arise from
the subprocess call.

Author: bgardiner

lib/analyzer/image-inspector.ts

@@ -23,7 +23,7 @@ async function getInspectResult(
   targetImage: string,
 ): Promise<DockerInspectOutput> {
   const info = await docker.inspectImage(targetImage);
-  return JSON.parse(info.stdout)[0];
+  return info;
 }
 
 function cleanupCallback(imageFolderPath: string, imageName: string) {

lib/analyzer/types.ts

@@ -22,12 +22,7 @@ export interface AnalyzedPackageWithVersion extends AnalyzedPackage {
 }
 
 export interface DockerInspectOutput {
-  Id: string;
   Architecture: string;
-  RootFS: {
-    Type: string;
-    Layers: string[];
-  };
 }
 
 export interface ImageAnalysis {

lib/docker.ts

@@ -8,6 +8,7 @@ import * as Debug from "debug";
 import * as Modem from "docker-modem";
 import { createWriteStream } from "fs";
 import { Stream } from "stream";
+import { DockerInspectOutput } from "./analyzer/types";
 import * as subProcess from "./sub-process";
 
 export { Docker, DockerOptions };
@@ -24,6 +25,18 @@ interface DockerOptions {
 
 const debug = Debug("snyk");
 
+/**
+ * Type guard to validate that an object conforms to the DockerInspectOutput interface
+ */
+function isValidDockerInspectOutput(data: any): data is DockerInspectOutput {
+  return (
+    data &&
+    typeof data === "object" &&
+    !Array.isArray(data) &&
+    typeof data.Architecture === "string"
+  );
+}
+
 class Docker {
   public static async binaryExists(): Promise<boolean> {
     try {
@@ -135,7 +148,38 @@ class Docker {
     });
   }
 
-  public async inspectImage(targetImage: string) {
-    return subProcess.execute("docker", ["inspect", targetImage]);
+  public async inspectImage(targetImage: string): Promise<DockerInspectOutput> {
+    const request = {
+      path: `/images/${targetImage}/json`,
+      method: "GET",
+      statusCodes: {
+        200: true,
+        404: "not found",
+        500: "server error",
+      },
+    };
+
+    debug(`Docker.inspectImage: targetImage: ${targetImage}`);
+
+    const modem = new Modem();
+
+    return new Promise<DockerInspectOutput>((resolve, reject) => {
+      modem.dial(request, (err, data) => {
+        if (err) {
+          return reject(err);
+        }
+
+        // Validate that the response conforms to DockerInspectOutput interface
+        if (!isValidDockerInspectOutput(data)) {
+          return reject(
+            new Error(
+              `Invalid Docker inspect response for image ${targetImage}: expected DockerInspectOutput format`,
+            ),
+          );
+        }
+
+        resolve(data);
+      });
+    });
   }
 }

lib/scan.ts

@@ -12,6 +12,7 @@ import { getArchivePath, getImageType } from "./image-type";
 import { isNumber, isTrue } from "./option-utils";
 import * as staticModule from "./static";
 import { ImageType, PluginOptions, PluginResponse } from "./types";
+import { isValidDockerImageReference } from "./utils";
 
 // Registry credentials may also be provided by env vars. When both are set, flags take precedence.
 export function mergeEnvVarsIntoCredentials(
@@ -174,6 +175,13 @@ async function imageIdentifierAnalysis(
   dockerfileAnalysis: DockerFileAnalysis | undefined,
   options: Partial<PluginOptions>,
 ): Promise<PluginResponse> {
+  // Validate Docker image reference format to catch malformed references early. We implement initial validation here
+  // in lieu of simply sending to the docker daemon since some invalid references can result in unknown or invalid API
+  // paths to the Docker daemon, sometimes producing confusing error results (like redirects) instead of the not found response.
+  if (!isValidDockerImageReference(targetImage)) {
+    throw new Error(`invalid image reference format: ${targetImage}`);
+  }
+
   const globToFind = {
     include: options.globsToFind?.include || [],
     exclude: options.globsToFind?.exclude || [],

lib/utils.ts

@@ -0,0 +1,15 @@
+/**
+ * Validates a Docker image reference format using the official Docker reference regex.
+ * @param imageReference The Docker image reference to validate
+ * @returns true if valid, false if invalid
+ */
+export function isValidDockerImageReference(imageReference: string): boolean {
+  // Docker image reference validation regex from the official Docker packages:
+  // https://github.com/distribution/reference/blob/ff14fafe2236e51c2894ac07d4bdfc778e96d682/regexp.go#L9
+  // Original regex: ^((?:(?:(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])(?:\.(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]))*|\[(?:[a-fA-F0-9:]+)\])(?::[0-9]+)?/)?[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*(?:/[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*)*)(?::([\w][\w.-]{0,127}))?(?:@([A-Za-z][A-Za-z0-9]*(?:[-_+.][A-Za-z][A-Za-z0-9]*)*[:][[:xdigit:]]{32,}))?$
+  // Note: Converted [[:xdigit:]] to [a-fA-F0-9] and escaped the forward slashes for JavaScript compatibility.
+  const dockerImageRegex =
+    /^((?:(?:(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])(?:\.(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]))*|\[(?:[a-fA-F0-9:]+)\])(?::[0-9]+)?\/)?[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*)*)(?::([\w][\w.-]{0,127}))?(?:@([A-Za-z][A-Za-z0-9]*(?:[-_+.][A-Za-z][A-Za-z0-9]*)*[:][a-fA-F0-9]{32,}))?$/;
+
+  return dockerImageRegex.test(imageReference);
+}

test/lib/analyzer/image-inspector.spec.ts

@@ -98,7 +98,7 @@ describe("extractImageDetails", () => {
          path: imageNameAndTag,
        }),
      ).rejects.toEqual(
-       new Error("invalid image format"),
+       new Error(`invalid image reference format: ${imageNameAndTag}`),
      );
    });
 });

test/lib/utils.spec.ts

@@ -0,0 +1,87 @@
+import { isValidDockerImageReference } from "../../lib/utils";
+
+describe("isValidDockerImageReference", () => {
+  describe("valid image references", () => {
+    const validImages = [
+      "nginx",
+      "ubuntu",
+      "alpine",
+      "nginx:latest",
+      "ubuntu:20.04",
+      "alpine:3.14",
+      "library/nginx",
+      "library/ubuntu:20.04",
+      "docker.io/nginx",
+      "docker.io/library/nginx:latest",
+      "gcr.io/project-id/image-name",
+      "gcr.io/project-id/image-name:tag",
+      "registry.hub.docker.com/library/nginx",
+      "localhost:5000/myimage",
+      "localhost:5000/myimage:latest",
+      "registry.example.com/path/to/image",
+      "registry.example.com:8080/path/to/image:v1.0",
+      "my-registry.com/my-namespace/my-image",
+      "my-registry.com/my-namespace/my-image:v2.1.0",
+      "nginx@sha256:abcd1234567890abcd1234567890abcd1234567890abcd1234567890abcd1234",
+      "ubuntu:20.04@sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12",
+      "image_name",
+      "image.name",
+      "image-name",
+      "namespace/image_name.with-dots",
+      "registry.com/namespace/image__double_underscore",
+      "127.0.0.1:5000/test",
+      "[::1]:5000/test",
+      "registry.com/a/b/c/d/e/f/image",
+      "a.b.c/namespace/image:tag",
+    ];
+
+    it.each(validImages)(
+      "should return true for valid image reference: %s",
+      (imageName) => {
+        expect(isValidDockerImageReference(imageName)).toBe(true);
+      },
+    );
+  });
+
+  describe("invalid image references", () => {
+    const invalidImages = [
+      "/test:unknown",
+      "//invalid",
+      "invalid//path",
+      "UPPERCASE",
+      "Invalid:Tag",
+      "registry.com/UPPERCASE/image",
+      "registry.com/namespace/UPPERCASE",
+      "",
+      "image:",
+      ":tag",
+      "image::",
+      "registry.com:",
+      "registry.com:/image",
+      "image@",
+      "image@sha256:",
+      "image@invalid:digest",
+      "registry.com//namespace/image",
+      "registry.com/namespace//image",
+      ".image",
+      "image.",
+      "-image",
+      "image-",
+      "_image",
+      "image_",
+      "registry-.com/image",
+      "registry.com-/image",
+      "image:tag@",
+      "image:tag@sha256",
+      "registry.com:abc/image",
+      "registry.com:-1/image",
+    ];
+
+    it.each(invalidImages)(
+      "should return false for invalid image reference: %s",
+      (imageName) => {
+        expect(isValidDockerImageReference(imageName)).toBe(false);
+      },
+    );
+  });
+});