Skip to main content

Running a Docker Images Plugin Scan with a Properties File

You can run a Docker Images plugin scan in conjunction with a properties file that you manually update before the executing scan.

You initiate the scan by executing the provided shell script or the plugin’s jar file. The execute command supports an optional -tmpdir parameter, enabling you to specify a temporary folder of your choice for storing and processing the Docker image during the scan (instead of the using default /tmp directory).

Manually Updating the Properties File for the Docker Images Plugin​

Use the following steps manually update the properties file used to configure the Docker Images plugin for scans.

To configure the Docker Images plugin, do the following:

  1. Navigate to the Docker Images plugin folder that you copied to the Docker server (as described in Obtaining the Docker Images Plugin).

  2. Open the code-insight.docker.props file within a text editor. The following shows the file contents that are shipped with the plugin. You’ll need to update the property values for your site.

    //required
    codeinsight.server=http://127.0.0.1:8888/codeinsight
    codeinsight.auth.token=Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInVzZXJJZCI6MSwiaWF0IjoxNTExNDM1MTk4fQ.dHItJjJ2c89Dg5cVLvfGR3fwJcR3yAlVE6k98dRZTdp3h6McDgv_PloVVE88eJ2GOG0tNDOnhU0ShDLUzdu3Pg
    codeinsight.project.name=Docker
    plugin.alias.name=dockerRemote
    plugin.root.path=/Users/ranimathur/Work/Scratch/
    plugin.name=Docker
     
    //optional
    plugin.project.name=plugin project name
    plugin.project.description=plugin project description
    plugin.path.prefix=$demo_workspace/

  3. Edit the code-insight.docker.props file to specify the following information, replacing current values with values appropriate for your site:

    • codeinsight.server (required)—The URL path to the Code Insight server in the following format:

      <codeInsight_server_hostname><>:port>/<codeInsight_server_path>

      An example URL might be http://1.1.1.1:8888/codeinsight.

    • codeinsight.auth.token (required)—The JSON Web Token (JWT) used to authorize user access to the Code Insight functionality. Generate this token using the Code Insight Web UI and then copy and paste it here. Be sure to include the command “Bearer” followed by the token value, as in the example:

      Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInVzZXJJZCI6MSwia

      For information about generating this token, see Providing an Authorization Token.

    • codeinsight.project.name (required)—The name of the project created in Code Insight to capture the scan results.

    • plugin.alias.name (required)—A custom name that you want to give to the scan-agent plugin. This alias is then used as the name of the “container” (scan root) under which all the files scanned in this instance will be listed in the API output and in the file tree in the Analysis Workbench. The name must be unique within the project.

    • plugin.root.path (required)—The root path where the Docker Images plugin will be executing. This path must have writable privileges for the user executing the plugin.

    • plugin.name—The name of the Docker Images plugin. This value must be Docker.

    • plugin.project.name (optional)—A descriptive name of the project being scanned. This can be different from the name specified for the project on the Code Insight server. This text will appear on the Summary tab for the project in the Code Insight web UI.

    • plugin.project.description (optional)—A description of the project being scanned. This text will appear on the Summary tab for the project in the Code Insight web UI.

    • plugin.path.prefix (optional)—The path prefix of the image being scanned. This prefix will be used to reference the codebase file paths on the Project Inventory page in the Code Insight web UI.

  4. Save the file.

Initiating a Docker Images Plugin Scan When Using the Properties File​

To initiate a Docker Images plugin scan that uses the properties file that you configured, you can execute either the shell script or the Java jar file provided with the plugin.

The launch process automatically stores the Docker image in the /tmp directory on the machine where the Docker Images plugin is installed. The image contents are then extracted and scanned in this directory and, once the scan completes, the artifacts are deleted from the directory. Alternatively, you can specify a directory of your choice to store and process the image.

The following sections describe how to launch the plugin and scan an image.

note

The Docker Images plugin must be launched whenever the Docker image is updated. The Docker Images plugin can be included in a script, so the image is scanned regularly.

Using the Shell Script to Launch the Plugin​

Use this procedure to launch the Docker Images plugin using the shell script provided with the plugin.

Issue one of these command options (where <Docker_image_name> is the name for the Docker image that the plugin is to scan).

  • Option 1: sh code-insight-docker-plugin.sh -image <Docker_image_name>
  • Option 2: sh code-insight-docker-plugin.sh -image <Docker_image_name> -tmpdir <custom_path>
  • Option 3: ./code-insight-docker-plugin.sh -image <Docker_image_name>
  • Option 4: ./code-insight-docker-plugin.sh -image <Docker_image_name> -tmpdir <custom_path>

Note that -tmpdir <custom_path> used in Option 2 and Option 4 designates the desired path for storing and processing the image (instead of using the default /tmp directory). For more information about this optional parameter, see Specifying a Temporary Directory of Your Choice.

Also, issues can occur if the Docker image name contains a forward slash (/). See Important Note About an Image Name Containing a “/” in the Command.

Using the Java jar File to Launch the Plugin​

Use this procedure to launch the Docker Images plugin using the Java .jar file provided with the plugin.

Issue one of these command options (where <Docker_image_name> is the name for the Docker image that the plugin is to scan):

  • Option 1: java -jar code-insight-docker-plugin.jar -image <Docker_image_name>
  • Option 2: java -jar code-insight-docker-plugin.jar -image <Docker_image_name> -tmpdir <custom_path>

Note that -tmpdir <custom_path> used in Option 2 designates the desired path for storing and processing the image (instead of using the default /tmp directory). For more information about this optional parameter, see Specifying a Temporary Directory of Your Choice.

Also, issues can occur if the Docker image name contains a forward slash (/). See Important Note About an Image Name Containing a “/” in the Command.