Configuring a scan to run with the CLI

You can use a configuration file to customize how a scan is run with the command line interface (using the scan command), wherein you can specify individual targets - or include or exclude targets. In addition, you can use the configuration file to specify additional information that would help to generate complete scan results.

Configuration file usage

A configuration file can be used for indicating which targets to include or exclude when you scan with the CLI. You can also specify directories that contain build artifacts - and you can specify build information that should be used during the scan (for example, you can use this setting to specify a particular JDK or JSP compiler).

Whenever you scan a folder with the Command Line Utility (CLI), the CLI automatically checks for an appscan-config.xml file in the current directory. If the file is found, it is automatically used.

Configuration file template and settings

When you prepare the configuration file, use this template:

<Configuration attributes="true/false">
  <Targets>
    <Target outputs-only="true/false" path="scan_target_path">
      <CustomBuildInfo build_info="info"/>
      <Include>string_pattern</Include>
      <Exclude>string_pattern</Exclude>
    </Target>
  </Targets>
</Configuration>
Use the optional configuration attributes to specify third-party and/or open source scanning as follows:
  • thirdParty="<true or false>" enables scanning of third-party artifacts. The default is false.
  • openSourceOnly="<true or false>" disables security scanning and only runs open source analysis. The default is false.
  • sourceCodeOnly="<true or false>" scans only source files and ignores other supported file types (.dll, .exe). The default is false.
  • staticAnalysisOnly="<true or false>" disables open source analysis and runs only static analysis. The default is false.

Use the Targets element to indicate which targets to scan. The target (Target) attributes and child elements are used as follows:

  • The Target element outputs-only attribute is only used when you want to scan a directory and force the CLI to find only the build output files (such as .jar, .war, and .class files). By default, this attribute is set to false. This means that the CLI searches the directory to determine if it is a target (such as an application server or an Eclipse workspace) - or if the directory contains items such as build scripts, Maven .pom files, and make files. If you want the scan target to be treated as a simple directory, and have located only the output files, specify outputs-only="true" in the Target element.

    For example, if you specify <Target outputs-only="false" path="C:\Tomcat">, the CLI assumes that the target is your Tomcat application server - and searches for its deployed .war files. However, if you specify <Target outputs-only="true" path="C:\Tomcat">, the CLI treats that location as a directory, and locates all build output files inside of it.

  • Use the Target element path attribute to specify the path to a scan target or a directory of scan targets (<scan_target_path>). When a directory is specified, all of its subdirectories are included during the scan.

    For example, if you specify <Target outputs-only="false" path="C:\WebSphere\AppServer85\profiles\AppSrv01">, the CLI locates all deployed .ear files in the AppSrv01 profile. If you specify <Target outputs-only="false" path="C:\WebSphere\AppServer85">, the CLI locates all deployed .ear files in all profiles.

  • You can also specify these optional Target subelements:
    • You can use the CustomBuildInfo element to set attributes. Using this part of the template,
      
      <CustomBuildInfo build_info="info"/>
      you can specify build information depending on the target language. For some languages, more than one attribute can be set - for example, you may set <CustomBuildInfo build_info_1="info_1" build_info_2="info_2" build_info_3="info_3"/>, depending on the target language.
      • For Java, you can set these attributes:
        <CustomBuildInfo additional_classpath="dependency_path"
          jdk_path="JDK_path" jsp_compiler="JSP_compiler_path" package_includes="namespaces" package_excludes="namespaces"/>
        • Specify more class paths by using the additional_classpath attribute. On Windows, separate multiple class paths with a semicolon. On Linux and macOS, separate multiple class paths with a colon.
        • Use the jdk_path attribute to specify the path to your JDK installation.
        • Use the jsp_compiler attribute to specify the path to your JSP compiler - for example:
          jsp_compiler="C:\Tomcat"
          jsp_compiler="C:\Program Files (x86)\IBM\WebSphere\AppServer"
          jsp_compiler="C:\Oracle"
        • Use the package_includes attribute to override the existing third-party exclusions and scan only those classes that are from the given namespace(s). Use semi-colons to delimit the namespaces list. For example:
          package_includes="com.hcl.example;com.hcl.sample"
        • Use the package_excludes attribute to append the specified namespaces to the existing list of third party exclusions. Use semi-colons to delimit the namespaces list.
        • Use the irx_minor_cache_home attribute in the <CustomBuildInfo> tag to set the Java parallel processing cache location. The value should point to the location used for the cache. For example:
          <CustomBuildInfo irx_minor_cache_home="X:/mycache"/>
      • For JSP under provided Tomcat, you can set these attributes:
        <CustomBuildInfo jsp_compiler_args="-ARGUMENTS"/>
        • Use the jsp_compiler_args attribute to specify JSP compiler command line arguments to set or override the JSP compiler.
      • For .NET (Windows only), you can set these attributes:
        <CustomBuildInfo references="assembly_references"
          configuration="build_configuration"/>
        • Add assembly references by using the references attribute. Separate multiple references with a semicolon.
        • Use the configuration attribute to include a build configuration for Visual Studio solution discovery.
        • Use the package_includes attribute to override the existing third-party exclusions and scan only those classes that are from the given namespace(s). Use semi-colons to delimit the namespaces list. For example:
          package_includes="com.hcl.example;com.hcl.sample"
        • Use the package_excludes attribute to append the specified namespaces to the existing list of third party exclusions. Use semi-colons to delimit the namespaces list.
      • For C/C++ (Windows only), you can set these attributes:
        <CustomBuildInfo configuration="build_configuration"
          include_paths="include_directories" macros="macros" compiler_opts=/>
        • Use the configuration attribute to include a build configuration.
        • Specify include paths by using the include_paths attribute. Separate multiple include paths with a semicolon.
        • Include macros by using the macros attribute. Separate multiple macros with a semicolon.
        • Specify compiler options with the compiler_opts attribute. Separate multiple options with a semicolon.
    Note: The values that are set by these attributes are inherited by subtargets. For example, if your target is an EAR file that includes WAR and JAR subtargets, it is assumed that the WAR and JAR have the same values that are set for the EAR file that uses these attributes.
  • Use the Include child element to specify file patterns (<string_pattern>) to include when you scan. Include behavior depends on the target type, as outlined in the Target include and exclude behavior section. To specify multiple include patterns, add each pattern in its own <Include></Include> tag. For example,
    <Include>string_pattern_1</Include>
    <Include>string_pattern_2</Include>
    Note: If you specify include and exclude patterns that conflict, the exclude patterns take precedence.
  • Use the Exclude child element to specify file patterns to exclude when you scan. Exclude behavior depends on the target type, as outlined in the Target include and exclude behavior section. To specify multiple exclude patterns, add each pattern in its own <Exclude></Exclude> tag.
    Note: If you specify include and exclude patterns that conflict, the exclude patterns take precedence.

Target include and exclude behavior

Table 1. Target include and exclude behavior

This table outlines the behavior of include and exclude settings, by target type.

Target type Behavior Examples
.dll If your target is a .dll file, including or excluding targets has no impact on the scan, since these files cannot contain targets.
.jar If your target is a .jar file you can exclude .class files inside the .jar. *MyClass.class
.war If your target is a .war file, you can exclude .class, .jsp, and JavaScript file types and .jar files in WEB-INF/lib.
Note: By default, .jar files are treated as third-party code and added to the class path of the .war file (and excluded by default).
com.ibm.*.jar
.ear If your target is a .ear, you can include or exclude .jar and .war files.
  • com.ibm.*.jar
  • JSPWiki.war
directory If your target is a directory, you can include or exclude the path or file name of any target, target type, or scan file.
Note: The trailing slash is required when specifying directories.
  • com.ibm.*.jar
  • test/: Includes or excludes everything in the test/ directory and its subdirectories.
  • test/*.jar: Includes or excludes all .jar files in the test/ directory, but not its subdirectories.
  • myFile.js
web server (see the System requirements to learn about supported web servers) If your target is a web server, you can include or exclude the file name of any applications that are deployed on the server.
  • JSPWiki.war
  • MyApp.ear
  • *.war (When the target is a Tomcat server)
.sln (.NET) If your target is a Visual Studio solution file that contains .NET projects, you can include or exclude the file name of any .NET assembly produced by a project in the solution.
  • *\MyLib.dll
  • *\MyApp.exe
.sln (C/C++) If your target is a Visual Studio solution file containing unmanaged C/C++ projects, you can include or exclude the file name of any project.
  • *\myProject.vcxproj

Configuration file example

<Configuration>
  <Targets>
    <Target path="C:\test\MyApplication.ear">
      <CustomBuildInfo additional_classpath="C:\java\lib;C:\java2\lib"
        jdk_path="C:\Program Files\Java\jdk1.7" jsp_compiler="C:\Tomcat"/>
      <Include>ShoppingCart.war</Include>
      <Include>*Account.jar</Include>
      <Exclude>thirdPartyJars/</Exclude>
      <Exclude>*test*</Exclude>
    </Target>
  </Targets>
</Configuration>
In this configuration file:
  • C:\test\MyApplication.ear is the target.
  • C:\java\lib and C:\java2\lib is searched for any class file dependencies that are necessary for compilation.
  • C:\Program Files\Java\jdk1.7 is used for locating dependencies.
  • The C:\Tomcat compiler is used for JSP compilation instead of the Apache Tomcat Version 7 application that is included with the CLI.
  • When you scan with the CLI, the ShoppingCart.war file is included, as are all files that end in *Account.jar. Everything in the EAR file's thirdPartyJars/ is excluded, as are any files that have the string test in their file name. If there are conflicts, the exclude patterns take precedence. For example, if the EAR file contains a testCustomerAccount.jar file, it is excluded because the test exclude pattern takes precedence over the *Account.jar include pattern.