Fortify SCA Command Line Interface Section Objectives In

Fortify SCA Command Line Interface:

Section Objectives In this module, you will gain: The ability to use the SCA Command Line to generate clean, valid results

Course overview • Fortify SCA Command Line Interface – Interactive 3

Rationale • Extended Ability in Analyzing Source Code 4

Fortify SCA Command Line Interface • Getting started • Under the covers • Build integration 5

What is Fortify SCA? • The core of Fortify SCA is single executable: sourceanalyzer 6

What is Fortify SCA? (Windows) 7

What is Fortify SCA? (Unix) 8

Online help • Follow the on screen suggestion, and type sourceanalyzer -h for the compiled in help information: sourceanalyzer -h 9

Online help (Windows output) 10

Online help (Unix output) 11

Online help • A lot of information. Output to a text file. sourceanalyzer -h > SCAhelp. txt 12

The most simple invocation step 1: Preparation step 2: Invoking Fortify SCA 13

The most simple invocation • Create a simple Java class that contains a security vulnerability: public class Exploit { public static void main( String[] args ) throws Exception { Runtime. get. Runtime(). exec( args[0] ); } } Exploit. java 14

The most simple invocation: Exploit. java • Let's examine the vulnerability • Dataflow vulnerability – Information is received from the command line and it's written out to the system output stream. 15

The most simple invocation sourceanalyzer Exploit. java 16

Interpreting command line results • Our results • Results format • Interpretation walkthrough 17

Our three results: [337 DD 8 E 25412 C 3 E 5 B 44 CE 3 AFBA 50 DFF 2 : low : Unchecked Return Value : semantic ] Exploit. java(3) : Runtime. exec() [A 0 E 37 EE 40 D 5 DA 16 DD 9 B 96 EC 3 A 5 A 2 DCE 6 : high : Command Injection : dataflow ] Exploit. java(3) : ->Runtime. exec(0) Exploit. java(2) : ->Exploit. main(0) [0228 A 5 C 2 FD 841 D 36 BA 4 F 9 B 1 DCACE 80 F 3 : low : J 2 EE Bad Practices : Leftover Debug Code : structural ] Exploit. java(2) 18

Format [ Instance-ID : criticality : category : analyzer ] analysis trace 19

Instance ID • Unique identifier for this finding at this location in your code. • If the code base changes a bit, the instance ID will follow this point in the code (even if the line numbers change). 20

Criticality • High, medium or low, based on a default severity from the matched rule, and a multiplier based on SCA's confidence of a correct finding from the context. 21

Category • A vulnerability type from the Fortify taxonomy of security vulnerabilities • http: //www. fortify. com/vulncat – http: //www. fortify. com/vulncat/en/vulncat 22

Analyzer • The name of the Fortify SCA analyzer that detected this issue. 23

Analysis trace • This is a little different depending on which analyzer discovered the issue. • Describes the vulnerability pattern detected in the context of the source code. 24

Basic interpretation [0228 A 5 C 2 FD 841 D 36 BA 4 F 9 B 1 DCACE 80 F 3 : low : J 2 EE Bad Practices : Leftover Debug Code : structural ] Exploit. java(2) • Fortify SCA has provided this result on the assumption that the Java source is within a J 2 EE / web context. – In a web context, use of method main() is a bad practice. • This is an incorrect finding, since our command line utility is not actually part of a web application. 25

Basic interpretation [A 0 E 37 EE 40 D 5 DA 16 DD 9 B 96 EC 3 A 5 A 2 DCE 6 : high : Command Injection : dataflow ] Exploit. java(3) : ->Runtime. exec(0) Exploit. java(2) : ->Exploit. main(0) • This is a critical security finding. – Data is received from the command line parameters, and that data is pushed to a sink (The system executive on the host operating system) without being validated first. 26

Basic interpretation [337 DD 8 E 25412 C 3 E 5 B 44 CE 3 AFBA 50 DFF 2 : low : Unchecked Return Value : semantic ] Exploit. java(3) : Runtime. exec() • This is a code quality finding. – The exec() method returns a result code, but the program never captures this value. This makes it impossible for this program's exception handling to be complete. 27

Basic interpretation: done for now • Enough of thinking about the sample code… let's learn how to use the command line utility! 28

Preview SCA invocation forms preview: 1. sourceanalyzer <source file> 2. sourceanalyzer -help 3. sourceanalyzer -version 29

Fortify SCA Command Line Interface • Getting started • Under the covers • Build integration 30

Under the covers What happened when we invoked sourceanalyzer <source file> ? Translate Fortify SCA read the source files and translated their logic into a language agnostic format called NST (normalized syntax tree). Analysis Fortify SCA loaded the NST model into memory and evaluated the model's patterns against a set of pattern definitions in the Fortify rules. Render Fortify SCA rounded up the identified vulnerabilities and placed them into an output format, in our case, the text output to the terminal. 31

Fortify SCA process flow summary The typical result format is "FPR", which we will learn about soon. 32

Translation Specifying the build ID • Usually, translation is complicated enough that it is performed as a separate step. • To do so, specify a Fortify SCA build ID with the -b argument. Try it now: sourceanalyzer -b exploit Exploit. java 33

Translation output: puzzler • You'll notice there is no output to the terminal this time. Why? • Refer to the previous few slides to support your supposition. 34

Translation output: solution When the build ID is specified with the -b parameter, only a translation is performed. In the next step we'll see what that means. 35

Build model maintenance • List the files built into the model sourceanalyzer -b exploit -show-files 36

Build model maintenance • Review actionable translation errors sourceanalyzer -b exploit -show-build-warnings 37

Build model maintenance • Remove the build model sourceanalyzer -b exploit -clean 38

System wide maintenance • List all build models sourceanalyzer -show-build-ids 39

System wide maintenance • Remove all build model sourceanalyzer -clean 40

Hands on • Delete the build model we created. • Using the up arrow key, consult your command history to repeat the commands needed to re-create the "exploit" build ID. • Check that the "exploit" build ID has no build warnings reported. 41

Under the covers • NST Location – The location is different depending on your operating system: • Microsoft Windows: C: Documents and Settings<user name> Local SettingsApplication DataFortify • Unix: ~/. fortify/ 42

Under the covers - Windows • Inside the Fortify directory, you will find an SCA directory with the version number. Inside that you will find the Fortify SCA build directory. 43

Under the covers - Unix • In Unix 44

Under the covers • What's interesting about the build directory? • In the build directory is a directory exploit for our exploit build ID. The directory name is the name of the build ID. • Inside the exploit directory is a full path replication to source files. • For each translated source file, you see an. nst file. • The entire Fortify directory is private to one logged in user. • You can take a moment to look at the NST file in a text editor. It contains an extract of the logic from our Java file. 45

Review Invocation review: Simple: sourceanalyzer <source file(s)> Translation: sourceanalyzer -b build. ID <source file(s)> Maintenance and query operators: sourceanalyzer -show-build-ids sourceanalyzer -clean sourceanalyzer -b <id> -show-files sourceanalyzer -b <id> -show-build-warnings sourceanalyzer -b <id> -clean 46

Scanning a build ID • Scanning a built model sourceanalyzer -b exploit -scan 47

Output format For any project more complicated than our Exploit file, the terminal output is no longer a useful format for reviewing Fortify SCA output. The solution is to always specify a FPR (Fortify Project Result) file whenever you specify the -scan parameter. sourceanalyzer -b exploit -scan -f exploit. fpr 48

Output format Note: Other output formats are supported by Fortify SCA. However, the only output format you will ever find useful is the FPR format. You may review the other output formats in the Fortify SCA Users' Guide: Output file format (as specified by file extension) Format description . fpr The only useful output format . fvdl An older Fortify output format . txt Text file equivalent to the terminal output seen previously 49

Compound translation • For many projects you will be specifying not only more than one source language. • For example: sourceanalyzer -b blah *. java sourceanalyzer -b blah "**/*. properties" • The second command adds properties files to the translated build model. 50

Compiler adaptation • Common format of invoking sourceanalyzer for translation sourceanalyzer <sca args> <compiler args> • In case of Java, including javac is optional sourceanalyzer -b blah javac Exploit. java sourceanalyzer -b blah [javac] Exploit. java sourceanalyzer -b blah Exploit. java 51

Compiler adaptation • Common format of invoking sourceanalyzer for translation sourceanalyzer <sca args> <compiler args> • In case of C and C++, including the compiler is required sourceanalyzer -b blah gcc -c hello. c 52

File specifiers • In case of non compiled languages (Java. Script, classic ASP and PHP), there is no compiler argument because it is not meaningful. • Single file argument sourceanalyzer -b blah file. js • Multiple file arguments sourceanalyzer -b blah file 1. js file 2. js file 3. js sourceanalyzer -b blah *. js • Shell expansion is equivalent to the file list above sourceanalyzer -b blah "**/*. js" 53

File specifiers • Recursive expansion with the ** operator is a Fortify SCA feature sourceanalyzer -b blah "**/*. js" • To avoid confusion of the shell, wrap these expressions in double quotes. 54

Fortify SCA Command Line Interface • Getting started • Under the covers • Build integration 55

Build tool integration • There a few commonly used build tools that are supported as if they were “compilers” – ant – make – devenv • The syntax is the similar to calling compilers. – Example for ant sourceanalyzer <sca args> ant <ant args> 56

Ant integration • Try the webgoat project • First see if it builds without Fortify SCA cd Samples/advanced/webgoat/Web. Goat 5. 0 ant • Note: if it fails, you probably need to copy a Tomcat installation into the Web. Goat 5. 0 directory. Name it “tomcat” 57

Ant integration • Next, translate the Web. Goat java sources: sourceanalyzer -b webgoat ant • Webgoat ant call doesn’t require any arguments. If it did, you would simply add them at the end of the command after ant. 58

Ant integration • Previous command didn’t translate any files other than the java files that ant would compile. • Web. Goat also contains some XML and properties files with vulnerabilities. – Add them into the build model with these commands: sourceanalyzer -b webgoat "**/*. xml" sourceanalyzer -b webgoat "**/*. properties" 59

Make build integration • The syntax for make integration sourceanalyzer <sca args> make <make args> 60

Visual Studio command line integration • The syntax for Visual Studio integration sourceanalyzer <sca args> devenv <devenv args> 61

Visual Studio command line integration • Invoke the command against a Visual Studio solution file, with the /REBUILD command. – On a Visual Studio command prompt invoke the command devenv <your-solution file. sln> /REBUILD Debug • If build is successful, add sourceanalyzer and its arguments before the devenv call sourceanalyzer -b my. Project devenv my. Project. sln /REBUILD Debug 62

JSP translation • Translating JSP files could be challenging to understand because up to this point, there has been an implicit assumption: Assumption: code to be translated must be buildable. • JSP files source files are compiled by the web server into Java source files, then compiled further into Java classes. – There are many variants on this first compilation from JSP to Java. • There are numerous dependencies including the JSP specification, standard tag libraries, custom tag libraries and framework support like Struts and Spring. 63

JSP translation • JSP compilation generally happens only when a page is first requested. – Fortify SCA need all information available to the deployment server to deconstruct the logic. • Important extension onto the assumption: Assumption: code to be translated must be buildable. Addition: JSP files must be in a deployable format and configuration. • Standard format for deployable JSP files is in a Web Archive (. war or. ear file) • Running SCA against JSP files – Explode the archive file, the JSPs are ready to be translated. 64

JSP example • Web. Goat. Its ant script can build the war file cd Samples/advanced/webgoat/Web. Goat 5. 0 ant Build. Windows. War (or on Unix) ant Build. Unix. War 65

JSP example • Extract the war file: cd dist unzip Web. Goat-5. 0. war • Translate the JSPs sourceanalyzer -cp WEB-INF/classes "**/*. jsp" • -cp argument specifies the Java class path that JSP translator needs to resolve some classes in the JSP files. – Usually the compilation needs some jars from the WEB-INF/lib directory as well. 66

Review Simple: sourceanalyzer <source file(s)> Translation: (There can be other SCA args, but -b is required) sourceanalyzer -b build. ID <source file(s)> sourceanalyzer -b build. ID compiler <compiler args> sourceanalyzer -b build. ID build tool <args> Maintenance and query operators: sourceanalyzer -show-build-ids sourceanalyzer -clean sourceanalyzer -b <id> -show-files sourceanalyzer -b <id> -show-build-warnings sourceanalyzer -b <id> -clean Scan: sourceanalyzer -b <id> -scan -f <output. fpr> 67

Fortify SCA Command Line Interface Section Summary In this section, you have learned: • How make best use of the online help • What simple invocation does under the covers • How to translate source files • How to administer the build model(s) • How to interpret command line results rendering • How to render results to a useful format • How to carry out build tool integration • The nuts and bolts of JSP translation