Configuring IRX file generation with the CLI
Use a configuration file for IRX file generation, 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 a complete IRX file.
Configuration file usage
Whenever you issue the appscan
prepare
(Windows™) or appscan.sh prepare
(Linux™ and
macOS) command to generate an IRX file, the Static Analyzer Command Line Utility automatically checks for an appscan-config.xml
file in the current
directory. If the file is found, it is used automatically.
If you have a configuration file in a different directory or with a different file name,
you can use the file by including the -c
option when you issue the appscan
prepare
or appscan.sh prepare
command. In this
case, issue appscan prepare -c
<configuration_file>
on (Windows™) or appscan.sh prepare -c <configuration_file>
on (Linux™ and
macOS), where
<configuration_file>
is the full path and file name of the
configuration file.
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>
thirdParty="<true or false>"
enables scanning of third-party artifacts. The default isfalse
.openSourceOnly="<true or false>"
disables security scanning and only runs open source analysis. The default isfalse
.sourceCodeOnly="<true or false>"
scans only source files and ignores other supported file types (.dll
,.exe
). The default isfalse
.staticAnalysisOnly="<true or false>"
disables open source analysis and runs only static analysis. The default isfalse
.
Use the Targets
element to indicate which targets to scan when you
generate the IRX file. The target
(Target
) attributes and child elements are used as follows:
- The
Target
elementoutputs-only
attribute is only used when you want to scan a directory and force the Command Line Utility to find only the build output files (such as.jar
,.war
, and.class
files). By default, this attribute is set tofalse
. This means that the Command Line Utility 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, andmake
files. If you want the scan target to be treated as a simple directory, and have located only the output files, specifyoutputs-only="true"
in theTarget
element.For example, if you specify
<Target outputs-only="false" path="C:\Tomcat">
, the Command Line Utility 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 Command Line Utility treats that location as a directory, and locates all build output files inside of it. - Use the
Target
elementpath
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 Command Line Utility locates all deployed.ear
files in theAppSrv01
profile. If you specify<Target outputs-only="false" path="C:\WebSphere\AppServer85">
, the Command Line Utility 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,
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="info"/>
<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"/>
- Specify more class paths by using the
- 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.
- Use the
- 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.
- Add assembly references by using the
- 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.
- Use the
- For Java, you can set these attributes:
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. - You can use the
- Use the
Include
child element to specify file patterns (<string_pattern>
) to include when you generate the IRX file.Include
behavior depends on the target type, as outlined in the Target include and exclude behavior section. To specify multipleinclude
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 specifyinclude
andexclude
patterns that conflict, theexclude
patterns take precedence. - Use the
Exclude
child element to specify file patterns to exclude when you generate the IRX file.Exclude
behavior depends on the target type, as outlined in the Target include and exclude behavior section. To specify multipleexclude
patterns, add each pattern in its own<Exclude></Exclude>
tag.Note: If you specifyinclude
andexclude
patterns that conflict, theexclude
patterns take precedence.
Target include and exclude behavior
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. |
|
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. |
|
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. |
|
.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. |
|
.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. |
|
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>
- 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 Static Analyzer Command Line Utility.
- When the IRX file is generated, the
ShoppingCart.war file is included, as will 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 testexclude
pattern takes precedence over the *Account.jarinclude
pattern.