Running static analysis for a Gradle project

To initiate an analysis of your files, you must generate an IRX file that you submit to the cloud. The HCL AppScan on Cloud Gradle plugin is used to automate the scanning of Java and Java web projects in Gradle. It generates an IRX file for Gradle projects that have the "java" plugin and/or "war" plugins applied. It can also submit the generated IRX file to the ASoC service for analysis automatically. For information on applying the plugin and to determine the latest plugin version, see Gradle plugins.

Procedure

To generate the IRX file for a Gradle project:
  1. At the command prompt, issue a command to change directory to the location that contains your Gradle project.
  2. Set the APPSCAN_OPTS environment variable to specify global options before running a scan.
    Use APPSCAN_OPTS to set scan speed, enable secrets scanning, enable debug logging, and more.
  3. Issue one of these commands:
    • To generate the IRX file only, issue appscan-prepare.

      This command generates an IRX file for all Java and War projects in the build. The IRX file is generated in the root project's build directory by default. You can submit the IRX file to ASoC at a later time.

    • To generate the IRX file and send it to the ASoC service for analysis, issue appscan-analyze.

      This command generates an IRX file and submits it to the ASoC service for analysis. This task requires an API key, secret, and application ID.

    Configurable options

    The following options can be set through JVM parameters on the command line using the syntax -Doption=value or through an appscanSettings block in the build script.

    Table 1. Configurable options for Gradle plugin
    Option Default Value Description
    irxName The name of the root project. The name of the generated .irx file.
    irxDir The build directory of the root project. The location for the generated .irx file.
    appId Null. Required for appscan-analyze The id of the application in the ASoC service.
    appscanKey Null. Required for appscan-analyze The user’s API key for authentication.
    appscanSecret Null. Required for appscan-analyze The user’s API key secret for authentication.
    namespaces Null. Override automatic namespace detection. Set to "" to disable namespace detection.
    Example 1: Specifying options at the command line: 
    gradle appscan-prepare -DirxName=MyApp
    Example 2: Specifying options in the build script: 
    appscanSettings {
	irxName="MyApp"
	irxDir="/myApplication/sample"
}
    Note: The appscanKey and appscanSecret options can be specified in the user's gradle.properties file. This avoids the need to specify authentication information in the build script or command line. For example, add the following lines to ~/.gradle/gradle.properties (create the file if it doesn't exist): 
    appscanKey="2358cd02-3fs3-322c-62c9-b5cc63c61f2a"
    appscanSecret="qU939siTXgF7csk3jSig+Vza7ilWLu/Uy/ReWye5E/c="
    You can generate an API key/secret here. See Generating API Keys for additional information.
    Note: To override default namespaces behavior, use the -Dnamespaces="<semi-colon delimited list of namespaces to scan>" command line option. By default, ASoC detects the namespaces of source files for the given project and adds to the allowed list the classes scanned to only include those that exist in the same namespace. Setting that property to an empty string ("") disables whitelisting completely.
    Note: If you would like to make your own modifications to the plugin, you can find the source here.

Encrypting appscanSecret using the Gradle plugin

About this task

To encrypt your API secret, use the Gradle credentials plugin along with the appscan-gradle-plugin.
Note: The latest version credentials plugin requires Gradle 5.0 or newer. For additional information on the plugin, see gradle-credentials-plugin.

Procedure

  1. Apply the credentials plugin in your project along with the appscan-gradle-plugin: 
    plugins {
	id 'nu.studer.credentials' version '2.1'
	id ' com.hcl.security.appscan' version '1.0.2'
}
  2. Run the following command to encrypt your API secret: 
    gradle addCredentials --key appscanSecret --value Yq9M+iFHyhRU2eEx+XobXwhX9xoW4hEXWz2fJDI8I=1
    By default, the encrypted value will be stored and retrieved from ~/.gradle/ gradle.encrypted.properites. Specify a different location using the credentialsLocation property.
    gradle addCredentials --key appscanSecret --value Yq9M+iFHyhRU2eEx+XobXwhX9xoW4hEXWz2fJDI8I=1 -PcredentialsLocation=/some/directory
  3. Set the appscanKey value and the encrypted appscanSecret value using an appscanSettings block in the build script: 
    appscanSettings {
	appscanKey=22iFHyhRU2eEx+XobXwhX9xoW4hEXWz2fJDI8I=1
	appscanSecret=credentials.appscanSecret
appId=95e69f47-9547-4378-ab93-f5d48ada52cc1
}
    You can set the ASoC appId here, as well.
  4. Run appscan-analyze: 
    gradle appscan-analyze
    If you did not specify the appId in the build script, set it on the command line at runtime:
    gradle appscan-analyze -DappId=95e69f47-9547-4378-ab93-f5d48ada52cc1
    If you used the credentialsLocation property when encrypting the appscanSecret value, specify that property at runtime as well:
    gradle appscan-analyze -PcredentialsLocation=/some/directory