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
Procedure
- 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).
-
Set the
APPSCAN_OPTS
environment variable to specify global options before running a scan.UseAPPSCAN_OPTS
to set scan speed, enable secrets scanning, enable debug logging, and more. -
Issue one of these commands:
- To generate the IRX file only, issue:
This command generates a single IRX file for allmvn com.hcl.security:appscan-maven-plugin:prepare
jar
,war
, andear
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
This command generates an IRX file and submits it to the ASoC service for analysis. This task requires an application ID (mvn package com.hcl.security:appscan-maven-plugin:analyze
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 thepackage
goal along with theprepare
oranalyze
goal. For example:
ormvn package com.hcl.security:appscan-maven-plugin:prepare
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 awar
orear
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:
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.<plugin> <groupId>com.hcl.security</groupId> <artifactId>appscan-maven-plugin</artifactId> <version>1.0.10</version> </plugin>
- 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:
After making this edit, you can execute the<pluginGroups> <pluginGroup>com.hcl.security</pluginGroup> </pluginGroups>
prepare
goal using theappscan
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. - To generate the IRX file only, issue:
Encrypting appscanSecret
using the Maven plugin
About this task
appscan-maven-plugin
to encrypt
your API secret. See tips and tricks for encrypting passwords in Maven here.Procedure
-
Run the following command to generate an encrypted master password:
mvn -emp myMasterPassword
-
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 thesettings-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
. -
Run the following command to generate an encrypted API secret:
mvn -ep apiSecret
-
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>
-
Execute the
analyze
goal with the Maven plugin:mvn com.hcl.security:appscan-maven-plugin:analyze -DappId=X49Qab75j9LSTwiM3mg2LCrO
If you placed yoursettings-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