Skip to main content

Running the Generic Scan-Agent Plugin

The generic scan-agent plugin can scan any file system of your choice, without your being limited to a specific build system as you are with the standard scan-agent plugins.

The scan returns the results back to Code Insight, where the discovered inventory items for your project can be reviewed automatically via policies or manually reviewed by various stakeholders. Security alerts with corresponding email notifications will be generated for any inventory items with new security vulnerabilities.

note

The first time a scan is performed using the generic scan-agent plugin, a data snapshot is downloaded from the National Vulnerability Database (NVD) to generate an index of the latest security vulnerabilities.

To run the generic scan-agent plugin, do the following:

  1. Download and extract the contents of the CodeInsightversionPlugins.zip file, as described in the previous section, Downloading Plugins.
  2. Locate the code-insight-agent-sdk-generic/generic-plugin-binary folder and copy it to your hard drive.
  3. Execute the required command from the command line as a Java application to perform the scan and report download operations using the plugin.
  4. To execute a scan using the plugin, run the following command:

java -Dflx.agent.logLevel=info -jar codeinsight-generic-<VERSION>.jar -server "<CODEINSIGHT_SERVER_HOSTNAME>:<PORT>/<CODEINSIGHT_SERVER_PATH>" -token "Bearer <JWT_TOKEN>" -proj "<CODEINSIGHT_PROJECT_NAME>" -root "</path/to/the/codebase>" -scandirs "</path/to/the/codebase/PROJECT>" -alias “<SCAN_AGENT_ALIAS>” -host “<SCAN_AGENT_HOST>”
-Djavax.net.ssl.trustStore="<JAVA_HOME>”\lib\security\cacerts

  1. To download a report using the plugin, run the following command:

java -Dflx.agent.logLevel=info -jar codeinsight-generic-<VERSION>.jar -server "<CODEINSIGHT_SERVER_HOSTNAME>:<PORT>/<CODEINSIGHT_SERVER_PATH>" -token "Bearer <JWT_TOKEN>" -proj "<CODEINSIGHT_PROJECT_NAME>" -root "</path/to/the/codebase>" -scandirs "</path/to/the/codebase/PROJECT>" -alias “<SCAN_AGENT_ALIAS>” -host “<SCAN_AGENT_HOST>”
-Djavax.net.ssl.trustStore="<JAVA_HOME>”\lib\security\cacerts -reportType "<REPORT_TYPE>"
-reportDownloadLocation "<REPORT_DOWNLOAD_LOCATION>" -reportOptions "<REPORT_OPTION_FILE>"

  • Replace the following variables with the appropriate information:

  • <VERSION>—The build version of the .jar file used to run the scan agent. The version is shown in the name of .jar file, which is located in the code-insight-agent-sdk-generic/generic-plugin-binary folder.

  • <CODEINSIGHT_SERVER_HOSTNAME>:<PORT>/<CODEINSIGHT_SERVER_PATH>—The URL for the Code Insight Core Server (for example, http://1.1.1.1:8888/codeinsight).

  • <JWT_TOKEN>—Your 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 in this field. For more information, see Providing an Authorization Token.

    • <CODEINSIGHT_PROJECT NAME>—The project you created in Code Insight to capture the inventory.

    • <path/to/the/codebase>—The root path for the codebase to be scanned.

    • </path/to/the/codebase/PROJECT>—The specific directories to be scanned.

    • <SCAN_AGENT_ALIAS>—A name that you define for the scan-agent plugin. The alias is used to represent 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. This name must be unique within the project.

  • <SCAN_AGENT_HOST>—(Optional) A user-defined name for the instance where the scan-agent plugin is configured to run scans. This property along with the alias property will remain unchanged for each subsequent rescan.

  • The -host property (for which you need to enter this variable) is required only if you are running the scan in a dynamic host environment. See Note About Rescans Performed by v2.0 and Later Plugins

  • <JAVA_HOME>—(Optional) The path defined for your JAVA_HOME environmental variable on the instance running the Code Insight Core Server. The -Djavax.net.ssl.trustStore property (for which you need to enter this variable) is required only if SSL is configured on the instance.

  • <REPORT_TYPE>—(Optional) The name of a Code Insight report that you want to be generated as a part of the scan build process once the scan completes.

  • <REPORT_DOWNLOAD_LOCATION>—(Optional) The directory where you want the report to be downloaded.

  • <REPORT_OPTION_FILE>—(Optional) The directory to the JSON file that includes additional parameters for custom reports. Specifying the JSON file directory using the -reportOptions property allows the generic scan-agent plugin to apply the parameters from that file to customize the report generation process.

note

The -reportOptions property is required only when generating customized reports and is not needed for standard report generation.

  • Alternatively, you run a scan using one of two scripts, run_scan.bat or run_scan.sh, provided with the generic scan-agent plugin. The scripts located in the generic-plugin-binary folder.