Section 7. Integrating with an Automated Build Process

7. Integrating with an Automated Build Process

This exercise demonstrates how to integrate the Source Code Analysis Engine with an existing build process.

• For C and C++ code, build processes typically use some form of the make utility, such as gmake or nmake, and a project-specific Makefile to build the project.

• For Java code, projects are typically built using the ant utility and a build.xml file.

The SCA Engine mirrors the way the compiler processes the source code of an application. This means that source code that is excluded due to conditional compilation (#ifdef) and code that is not included in the build is automatically excluded by the SCA Engine. Thus, extraneous and misleading results that are not part of the actual application are avoided.^[2]

^[2] And problems not found in one build path but found in another can slip by auditors.

Integrating with a Makefile

1. Edit a Makefile to invoke the SCA Engine during the build process. An easy way to cause a Makefile to invoke the SCA Engine is to locate the CC variable in the Makefile and insert the sourceanalyzer command and any options before the actual compiler name. Consider the following Makefile segment:

   6:  #### Tools 7: 8:  CC = gcc 9:  AR = ar sr 10: LINK = ld 11: 12: #### Options

   The following shows the addition of the SCA Engine to the Makefile:

   5:  #### Tools: introduced sourceanalyzer command and 6:  #### buildid/projectid=345 7: 8:  CC = sourceanalyzer -b 345 -c gcc 9:  AR = sourceanalyzer -b 345 -c ar sr 10: LINK = sourceanalyzer -b 345 -c ld 11: 12: #### Options

   The command line options specify the following:

   • -b specifies the build ID, in this case 345.

   • -c specifies that the SCA Engine runs the compiler as well as performs the translation.

   This modified Makefile causes the SCA Engine to generate an intermediate security representation of the source files and the dependencies of the build process. It also invokes the compiler and build commands so that there is no interference with the regular build output. However, actual security analysis is performed as a separate step.

2. Run the build as you normally would, but follow it with a command to perform the security analysis with a reference to the build ID:

   make; sourceanalyzer -scan -b 345 -f /bld/results.fvdl -format fvdl

   The command line options specify the following:

   • -scan specifies that the SCA Engine should perform an analysis on the provided build ID.

   • -b specifies the build ID, in this case 345.

   • -f specifies the file to which the results are written.

   • -format controls the output format (fvdl, fvld-zip, or text).

   The output file is specified as an absolute path because most make projects enter and exit various directories during the build, and compilations that occur in each directory create their own output files. If you specify an absolute path for the output file, all results for the make are generated in one FVDL file.

   If an output file with the same name already exists and the -append option is specified, the output is appended to the existing file. If the -append option is not included, the existing results are overwritten. To keep data from different analysis runs separately identifiable, rename or delete the output file before running each make.

3. To see the details, including resolution suggestions, open the results.fvdl file in Audit Workbench.

Integrating with an ant Build File

1. Ensure that the Install_Directory is included in the PATH environment variable.

2. Add the following to either ant's lib directory or to your CLASSPATH:

   Install_Directory/Core/lib/sourceanalyzer.jar

   Note: In ant 1.6 and above, it is also possible to pass the path to sourceanalyzer.jar on the command line through the -lib parameter.

   • Set the build.compiler property using either the command line or the property tag.

   The command line syntax is:

   >$ant -Dbuild.compiler="com.fortify.dev.ant.SCACompiler" -Dsourceanalyzer.buildid=Build_ID

   The property tag syntax is:

   <property name="build.compiler" value="com.fortify.dev.ant.SCACompiler"/> <property name="sourceanalyzer.buildid" value="Build_ID"/>

   Tip: When build files are used on systems without the SCA Engine, use the ant <available> task to define build.compiler:

   <available classname="com.fortify.dev.ant.SCACompiler" property="build.compiler" value="com.fortify.dev.ant.SCACompiler"/>

3. Perform the following steps to use the sourceanalyzer task to select files to be scanned or to run analysis. Include a typedef for the task in the build file as follows:

   <typedef name="sourceanalyzer" classname="com.fortify.dev.ant.SourceanalyzerTask"/>

   You can now include the sourceanalyzer task in any target.

4. Specify parameters, or define attributes in nested elements for the sourceanalyzer task. Valid parameters are listed in the Source Code Analysis Engine User's Guide.

The following is an example of running ant from the command line:

>$ ant -Dcom.fortify.dev.ant.SCACompiler.args=" \ -f resultsFile.fvdl        -format fvdl"

The following is an example of modifying the build.xml sourceanalyzer task:

<sourceanalyzer build            scan="true"            resultsfile="results_file.fvdl"            format="fvdl"            rules="rules_file.xml"            filter="filter_file.xml" />

Advanced Command Line Syntax for Java

Using the command line syntax for Java makes it easy to scan Java and J2EE code bases. In many cases, a J2EE project can be accurately analyzed without integrating with the build process. The syntax is:

sourceanalyzer -cp classpath [options] srcfile-specifier1 srcfile-specifier2 ...

For example, the following command invokes the analysis of the source code of a typical Web-based J2EE application:

sourceanalyzer -cp "app_directory\WEB-INF\lib\*.jar;app_directory\WEB-INF\classes"                -f results.fvdl -format fvdl .

Note: The dot at the end of the statement specifies the current directory.

Run the preceding command from the directory where the build.xml file is located. In this case it is assumed that the source files are located in a directory that is below the current directory. If the source files are located in a different location, use that as the srcfile-specifier instead of the current directory.

If there are multiple jar file directories under WEB-INF, you can also specify the following as part of the classpath: "app_directory\WEB-INF\**\*.jar"

Exercises for the Reader

1. How often do you do a build? How often do you perform system tests? What are the benefits of doing a security analysis with every build?

2. Assuming you cannot review the results from sourceanalyzer every time you build, how can you use the information that comes from sourceanalyzer in each build?