Configuring a scan to run with the CLI

• Configuration file usage
• Configuration file template and settings
• Target include and exclude behavior
• Configuration file example

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

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>