Best practices for Java scanning

When scanning Java projects in AppScan on Cloud, if you use Maven or Gradle for your builds (and most Java apps use one of these), you should use the respective ASoC Maven or Gradle plug-in.

However, if you are not using one of those tools, we recommend using appscan-config.xml to limit the scan to just your code, and to provide a classpath so all dependencies are found.

The major steps for setting up limited scanning using appscan-config.xml are:

  1. Perform a dry run of the IRGen process and examine results to identify packages to include and exclude.
  2. Configure appscan-config.xml to include and exclude packages accordingly.
  3. Perform another dry run to confirm the correct packages are to be scanned.
  4. If all is well, run appscan prepare to generate the IRX file.

Perform a dry run and examine results

A dry run examines files that would be included in a scan and returns two pieces of information:
  • The packages that would be included in the scan.
  • The package names for any dependencies that couldn't be found.
To perform a dry run, run appscan prepare -dr on the target directory. For example:
  • On Windows:
    appscan.bat prepare -dr
  • On Linux:
    appscan.sh prepare -dr
Sample output:
Validating classes...
100%
Validation complete.
__ 

The following packages/namespaces will be analyzed:
                com.ibm.security
__ 

The following problems were found:
                Missing required reference com.ibm.security.appscan.*
                Missing required reference javax.servlet.*
                Missing required reference javax.servlet.http.*
                Missing required reference javax.ws.rs.*
                Missing required reference javax.ws.rs.core.*
                Missing required reference org.apache.commons.codec.binary.*
                Missing required reference org.apache.commons.lang.*
                Missing required reference org.apache.wink.json4j.*
Examine the list of packages to be analyzed in the scan to ensure that only intended code will be analyzed.

Configure appscan-config.xml

After performing a dry run and evaluating results, configure appscan-config.xml:

  1. If there are package names that should not be scanned (for example, third-party dependencies or internal dependencies from other teams) there are two ways to scope the scan to just the intended code:
    • In appscan-config.xml, specify package_includes attribute to whitelist the scan to just the packages to analyze. The value is a semi-colon delimited list of one or more package names.
      For example: 
      package_includes="com.hcl.appscan.client;com.hcl.appscan.server"
    • In appscan-config.xml, use <Exclude> tags to exclude third party files and/or directories. The contents of the <Exclude> tag are a pattern and the * character can be used as a wild card.
      For example, 
      <Exclude>myDependency-.jar</Exclude>
      Note: Either or both of these approaches can be used.
  2. After specifying the scope of the scan, review the list of missing packages and identify the .jar files that contain those packages. Use the additional_classpath attribute in the appscan-config.xml to specify the locations of each missing .jar file. The value of the additional_classpath attribute is a delimited list of the path to each .jar file. On Linux/Mac, the delimiter is the colon character ( : ) and on Windows it’s the semi-colon character ( ; ).
    For example:
    additional_classpath=”C:\myDependencies\lib\xyz.jar;C:\myDependencies\lib\sample.jar”/
The following sample appscan-config.xml includes the modification noted above.
Note: appscan-config.xml should be placed in the directory where the appscan prepare command will be run. Any relative paths in appscan-config.xml should be relative to that directory. Learn more about appscan-config.xml here.
<Configuration>
 <Targets>
 <Target path="./myApp">
 <CustomBuildInfo package_includes=”com.hcl.appscan.client;com.hcl.appscan.server” additional_classpath=”C:\myDependencies\lib\xyz.jar;C:\myDependencies\lib\sample.jar”/>
 <Exclude>myDependency-.jar</Exclude>*
 <Exclude>abc.jar</Exclude>
 </Target>
 </Targets>
</Configuration>

After saving appscan-config.xml to the appropriate location, run appscan prepare -dr again to confirm that the list of packages to be analyzed is as expected, and that there are no missing references. Assuming all looks good, use appscan prepare to generate the IRX file