Running static analysis for a Maven 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 Maven plugin is used to automate the scanning of jar, war, and ear projects in Maven. It generates an IRX file for Maven projects that have the "jar," "war," and "ear" packaging types. It can also submit the generated IRX file to the ASoC service for analysis automatically. If you want to scan a Maven project, follow these instructions for creating that file.

About this task

This task describes how to run static analysis for a Maven project using the HCL AppScan on Cloud Maven plugin:

Procedure

  1. At the command prompt, issue a command to change directory to the location that contains your Maven project (the folder that contains the pom.xml file).
  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: 
      mvn com.hcl.security:appscan-maven-plugin:prepare
      This command generates a single IRX file for all jar, war, and ear projects in the build. The IRX file is generated in the root project's target 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 
      mvn package com.hcl.security:appscan-maven-plugin:analyze
      This command generates an IRX file and submits it to the ASoC service for analysis. This task requires an application ID (appId), API key (appscanKey), and API secret (appscanSecret).
      Note: If your Maven project has compile-time dependencies on another project in the same reactor build, an existing Maven bug may cause the command to fail. To work around this issue, execute the package goal along with the prepare or analyze goal. For example: 
      mvn package com.hcl.security:appscan-maven-plugin:prepare
      or 
      mvn package com.hcl.security:appscan-maven-plugin:analyze
    Table 1. Configurable options for Maven plugin
    Option Default value Description
    output 
    <root project>/target/<root project name>.irx
    		 The name and/or location of the generated IRX file. If the selected path does not exist, the default path is applied (<root project>/target/<root project name>.irx)
    appId

    Null. Required for analyze.

    		 The id of the application in the cloud service.
    appscanKey

    Null. Required for analyze.

    		 The user's API key ID for identification.
    appscanSecret

    Null. Required for analyze.

    		 The user's API key secret for authentication.
    namespaces Null. Override automatic namespace detection. Set to "" to disable namespace detection.
    Tip: The Command Line Utility includes a Tomcat JSP compiler. This JSP compiler is used by default during IRX file generation. If you are generating an IRX file for a war or ear file and want to use a different JSP compiler, issue the command with a -DjspCompiler option. For example:
    mvn com.hcl.security:appscan-maven-plugin:prepare -DjspCompiler=<jsp_compiler>

    where <jsp_compiler> is the path to the JSP compiler that you want to use, specifying the root directory of the server.

    Tip: By default, third-party code is not scanned during IRX file generation. You can modify third-party code exclusion settings by following the instructions in Managing third-party Java and .NET exclusions. To include third-party code, issue the command with a -DthirdParty option.

    If you are a developer of third-party code that would normally be excluded in a scan, you should use the setting to include the third-party code.

    Tip: The above command can be shortened in one of two ways:
    • Add the following to the <plugins> section of your pom.xml file:
      <plugin>
  <groupId>com.hcl.security</groupId>
  <artifactId>appscan-maven-plugin</artifactId>
  <version>1.0.10</version>
</plugin>
      With this method you can edit your pom.xml file and then all other users get the change automatically. However, the version number must be specified, so the pom.xml file will need to be manually edited and updated when newer versions are made available.
    • Add our groupId (com.hcl.security) to the list of plugin groups in your Maven settings.xml. For example, add the following to ~/.m2/settings.xml or ${maven.home}/conf/settings.xml: 
      <pluginGroups>
  <pluginGroup>com.hcl.security</pluginGroup>
</pluginGroups>
      After making this edit, you can execute the prepare goal using the appscan prefix. For example: 
      mvn appscan:prepare

    For more information, see Configuring Maven To Search For Plugins.

    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 Maven plugin

About this task

Use the appscan-maven-plugin to encrypt your API secret. See tips and tricks for encrypting passwords in Maven here.

Procedure

  1. Run the following command to generate an encrypted master password: 
    mvn -emp myMasterPassword
  2. Copy the output to ~/.m2/settings-security.xml and put it into the value of the <master> tag: 
    <settingsSecurity>
  <master>{rsB56BJcqoEHZqEZ0R1VR4TIspmODx1Ln8/PVvsgaGw=}</master>
</settingsSecurity>
    Note: You can store the settings-security.xml file in a different location. If you do, you must specify the location at runtime using the option -Dsettings.security=path/to/security-settings.xml.
  3. Run the following command to generate an encrypted API secret: 
    mvn -ep apiSecret
  4. Copy the output from the command to ~/.m2/settings.xml and put into the value of the <password> tag. The <username> tag should contain the value of the user’s API key: 
    <settings>
  <servers>
    <server>
      <id>appscan</id>
                <username>MyapiKey</username>
<password>{uMrbEOEf/VQHnc0W2X49Qab75j9LSTwiM3mg2LCrOzI=}</password>
    </server>
  </servers>
  ...
</settings>
  5. Execute the analyze goal with the Maven plugin: 
    mvn com.hcl.security:appscan-maven-plugin:analyze -DappId=X49Qab75j9LSTwiM3mg2LCrO
    If you placed your settings-security.xml file in a non-default location, you must specify that location at runtime:
    mvn com.hcl.security:appscan-maven-plugin:analyze -DappId=X49Qab75j9LSTwiM3mg2LCrO -Dsettings.security=path/to/security-settings.xml