HP Fortify CloudScan. Software Version Installation, Configuration, and Usage Guide

Transcription

1 HP Fortify CloudScan Software Version 4.00 Installation, Configuration, and Usage Guide Document Release Date: September 2013 Software Release Date: September 2013

2 Legal Notices Warranty The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice. Restricted Rights Legend Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR and , Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. Copyright Notice Copyright 2013 Hewlett-Packard Development Company, L.P. Documentation Updates The title page of this document contains the following identifying information: Software Version number Document Release Date, which changes each time the document is updated Software Release Date, which indicates the release date of this version of the software To check for recent updates or to verify that you are using the most recent edition of a document, go to: This site requires that you register for an HP Passport and sign in. To register for an HP Passport ID, go to: You will also receive updated or new editions if you subscribe to the appropriate product support service. Contact your HP sales representative for details. Part Number:

3 Contents Contents... iii Preface... v Contacting HP Fortify...v Technical Support...v Corporate Headquarters...v Website...v Change Log... vi Chapter 1: Introduction... 7 Intended Audience... 7 Related Documents... 7 Chapter 2: How CloudScan Works... 8 Chapter 3: Installing the CloudScan Components Secure Deployment of CloudScan Securing Access to Facilities Installing the Cloudera Hadoop Distributed Network Installing HP Fortify Static Code Analyzer Installing the CloudScan Controller To Install the CloudScan Controller on Windows Configuring the CloudScan Controller To Start and Stop the CloudScan Controller on Windows To Install the CloudScan Controller on Linux To Start and Stop the CloudScan Controller on Linux Securing the CloudScan Controller Self-Signed Certificates Certificates Signed by a Certificate Signing Authority Installing the CloudScan CLI Installation on Windows Installation on Unix-based Machines Installation on Mac To Set the Location of the CloudScan Controller Creating an SCA Mobile Build Session Chapter 4: Using the CloudScan CLI CloudScan CLI Command Syntax HP Fortify CloudScan Installation, Configuration, and Usage Guide iii

4 Global Options Commands Chapter 5: Issuing a Job Upload Request Start Command Scan Options Sample Job Upload Requests HP Fortify Software Security Center Upload Block upload Default upload Cancel Command Retrieve Command Issuing a Job Download Request Setting CLI Options in cloudscan.properties File CloudScan Log File Chapter 6: Monitoring CloudScan with HP Fortify Software Security Center Chapter 7: Upgrading CloudScan Updating the Controller Updating the CloudScan CLI Updating config.properties Initiating a Job Request using SCA Wizard HP Fortify CloudScan Installation, Configuration, and Usage Guide iv

5 Preface This guide provides instructions for installing, configuring, and using HP Fortify CloudScan. Contacting HP Fortify If you have questions or comments about any part of this guide, contact HP Fortify at: Technical Support Corporate Headquarters Moffett Towers 1140 Enterprise Way Sunnyvale, CA Website About the HP Fortify Software Security Center Documentation Set The HP Fortify Software Security Center (SSC) documentation set contains installation, user, and deployment guides for all HP Fortify Software Security Center products and components. It also includes technical notes and release notes that describe new features, known issues, and last-minute updates. The latest versions of these documents are available on the HP Software Product Manuals site: HP Fortify CloudScan Installation, Configuration, and Usage Guide v

6 Change Log The following table tracks changes made to the HP Fortify CloudScan Installation, Configuration, and Usage Guide. Software release-version Date Change /9/2013 No changes. HP Fortify CloudScan Installation, Configuration, and Usage Guide vi

7 Chapter 1: Introduction With HP Fortify CloudScan (CloudScan), users of HP Fortify Static Code Analysis can better manage their resources by offloading the processor-intensive scanning phase of the analysis from their build machines to a cloud of machines provided for this purpose. The translation phase, which is less processor and time intensive, is completed on the build machine. After translation is completed, an HP Fortify Static Code Analyzer (SCA) mobile build session is generated and moved to a distributed cloud of machines for scanning. In addition to freeing up the build machines, this process makes it easy to grow the system by adding more resources to the cloud as needed, without having to interrupt your build process. In addition, users of HP Fortify Software Security Center (SSC) can direct CloudScan to output FPR files directly to the server. This guide provides information on installing, configuring, and using CloudScan to streamline your static code analysis process. Intended Audience Anyone who intends to install, configure, or use CloudScan for offloading the scanning phase of their SCA process. Related Documents The following document provides additional information about HP Fortify CloudScan: HP Fortify Static Code Analyzer User Guide HP Fortify Static Code Analyzer (SCA) is a set of software security analyzers that search for violations of security-specific coding rules and guidelines in a variety of languages. The rich data provided by SCA language technology enables the analyzers to pinpoint and prioritize violations so that fixes can be fast and accurate. The analysis information produced by SCA helps you deliver more secure software, as well as making security code reviews more efficient, consistent, and complete. This is especially advantageous when large code bases are involved. The modular architecture of SCA allows you to quickly upload new third-party and customerspecific security rules. HP Fortify CloudScan Installation, Configuration, and Usage Guide 7

8 Chapter 2: How CloudScan Works The following diagram illustrates a CloudScan environment. HP Fortify Software Security Server (optional) FPR Job Requisition FPR / log CloudScan CLI installed on build machines CloudScan Controller Subnet 1 Subnet 2 CloudScan Cloud Note: When setting up your CloudScan environment, you may use subnets to segment your build machines from the cloud infrastructure. The build machines need to communicate only with the CloudScan Controller that can communicate with the cloud. There are three main components to a CloudScan installation: CloudScan CLI: the interface for issuing CloudScan commands. It is installed on your build machines and used to create or identify an SCA mobile build session, set the parameters for the scan, and communicate your intentions with the CloudScan Controller. CloudScan Controller: the server that receives the SCA mobile build session and scan instructions from the CloudScan CLI. It routes the information to the CloudScan Cloud. CloudScan Cloud: a distributed network of computers that have been set up to receive SCA mobile build sessions and scan the code using SCA analyzers. Results are output as an FPR and/or log file that can be distributed via a download link, returned back to the command line of the initiating CloudScan CLI, or uploaded to HP Fortify Software Security Center. The process begins on the build machine, where you use SCA to translate your code and generate an SCA mobile build session. The CloudScan CLI is then used to initiate a remote scan. The translated source code (SCA mobile build session), along with optional and necessary data, such as custom rules and Fortify SCA CLI arguments, are uploaded to the CloudScan Controller. HP Fortify CloudScan Installation, Configuration, and Usage Guide 8

9 CloudScan CLI CloudScan Controller CloudScan Cloud (Hadoop) FPR / Log files SCA mobile build session is exported and a job request is uploaded to the CloudScan Controller CloudScan Controller submits job request to the Job Tracker in the CloudScan Cloud Job request is queued if an agent is not available When agent is available, job is scanned and FPR and/or log file created FPR and log files are distributed as a download link in , returned to the CloudScan CLI, or uploaded to Software Security Center The CloudScan Controller returns a job receipt token to the CloudScan CLI to allow a download of the result upon completion. The CloudScan Controller selects a CloudScan Agent to run the scan. The CloudScan Agent runs the scan and returns the FPR and other output files (for example, log file, process standard out/error log) to the CloudScan Controller. The CloudScan Controller notifies the user via that the result is available and includes a job receipt token. The CloudScan Controller provides a mechanism to return the output via manual download, via the CloudScan CLI, or by direct upload to HP Fortify Software Security Center. HP Fortify CloudScan Installation, Configuration, and Usage Guide 9

10 Chapter 3: Installing the CloudScan Components CloudScan requires the installation of three distinct components in addition to HP Fortify Static Code Analyzer. These components should be installed in the order listed in the table below. For information on hardware and software requirements, see the HP Fortify Software Security Center System Requirements document. Order of Installation # Component Where to go for more information 1 Cloudera Hadoop Distributed Network Documentation and software is available from Cloudera at 2 HP Fortify Static Code Analyzer (on Hadoop slave machines) See the HP Fortify Static Code Analyzer Installation Guide 3 CloudScan Controller See Installing the CloudScan Controller on page 11 4 CloudScan CLI See Installing the CloudScan CLI on page 16 Note: The minimum installation requires two machines; one machine for the CloudScan CLI and the other for the Cloudera Hadoop installation. CloudScan requires the installation of a Hadoop distribution for its sole use. Do not incorporate CloudScan into a pre-existing Hadoop network. Secure Deployment of CloudScan The HP Fortify family of products collects and displays information about an enterprise s applications. That information includes concise summaries about the security vulnerabilities of the source code. Just as you should apply security precautions to your applications, you should also secure access to the CloudScan components. Moreover, the concentrated summarization of security vulnerabilities provided by the HP Fortify family of products may mandate an even higher level of secure deployment. Securing Access to Facilities CloudScan works with your company s static code. Because this information offers various opportunities for mishandling or abuse, HP Fortify recommends that administrators deploy CloudScan in a secure operations facility. You should also secure the underlying access to the CloudScan installation directories. Installing the Cloudera Hadoop Distributed Network CloudScan moves the process-intensive SCA scan phase off your build machine and into the CloudScan cloud. To build out your cloud, you will need to set up a Hadoop distributed network specifically for this task. Hadoop is an open-source project administered by the Apache Software Foundation. It was designed to provide a scalable distributed computing environment. CloudScan requires you to create a Hadoop cloud using the Cloudera CDH3u0 distribution, which is available free of charge from Cloudera ( The illustration below shows a typical Hadoop installation. HP Fortify CloudScan Installation, Configuration, and Usage Guide 10

11 Hadoop Installation with CloudScan Installation CloudScan Controller Master Slave #1 Slave #2 Job spec DNS Job Tracker Task Tracker Task Tracker Name Node SCA Data Node SCA Data Node IP Address Hadoop was chosen as the CloudScan cloud backbone because it has proven to be both reliable and highly scalable, enabling you to easily expand your cloud as your resource requirements grow. Follow the instructions for the Cloudera distribution and create a cloud for the exclusive use of CloudScan. Because the scanning process is resource-intensive and because CloudScan uses Hadoop in a non-standard way, you should not point your CloudScan Controller at an existing Hadoop installation that you are using for other purposes. Installing HP Fortify Static Code Analyzer After creating a Cloudera Hadoop distributed network, install a licensed copy of HP Fortify Static Code Analyzer on each of the slave machines in your network. For more information on installing SCA, see the HP Fortify Static Code Analyzer Installation and Configuration Guide. Installing the CloudScan Controller The CloudScan Controller is a standalone server that sits between the CloudScan CLI and the CloudScan cloud. The CloudScan Controller accepts job requests issued by the CloudScan CLI and passes them on to an available agent. The agents return job results to the CloudScan Controller where they are stored temporarily. Jobs are deleted from the CloudScan Controller after seven days, unless the setting has been changed. The CloudScan Controller can be installed on a Windows or Linux machine. To Install the CloudScan Controller on Windows Before you begin the installation of your CloudScan Controller, make sure your Hadoop network is up and running. 1. Run the HP-Fortify-X.XX-Cloud-Scan-Controller.exe application. 2. Navigate to C:\Program Files (x86)\fortify Software\HP Fortify vx.xx Cloud Scan Ctrl\tomcat\webapps\cloud-ctrl\WEB-INF\classes. HP Fortify CloudScan Installation, Configuration, and Usage Guide 11

12 3. Navigate to C:\Program Files (x86)\fortify Software\HP Fortify vx.xx Cloud Scan Ctrl\tomcat\webapps\cloud-ctrl\WEB-INF\classes. 4. Edit the hadoop.properties file as follows: Option job_tracker name_node Value The DNS name of the Job Tracker and port number The DNS name of the Name Node file_system_root The Hadoop file system root (virtual file path) Note: hadoop.properties includes examples that you can follow. Note: The CloudScan Controller installation includes a copy of the CloudScan CLI, located at: C:\Program Files (x86)\fortify Software\HP Fortify vx.xx Cloud Scan Ctrl\cloudscan.zip. The CloudScan CLI is installed with HP Fortify Static Code Analyzer, and is included here for those cases in which you intend to update CloudScan but use an earlier supported version of HP Fortify Static Code Analyzer. Replace the CloudScan directory in apps and analyzer with this directory to update the CLI to the latest version. Configuring the CloudScan Controller After installing the CloudScan Controller and connecting it to the Hadoop cloud, you can edit global properties, such as the address to be used, the polling period for status updates, and the HP Fortify Software Security Center Server URL (if you plan to upload your FPRs to it). 1. Navigate to <Installation Directory>/tomcat/webapps/cloud-ctrl/WEB-INF/classes. 2. Edit the options you want to set in the config.properties file. Option db_dir job_file_dir max_upload_size smtp_host smtp_port from_ cloud_poll_period job_cleanup_period job_expiry_delay ssc_url this_url Value Location of the CloudScan Controller database Directory where jobs are to be stored Maximum size for submitted job; if a job exceeds the maximum size (in MB), the job is rejected and the CLI returns an error. Host, port number, and delivery address for messages from the CloudScan Controller Polling period (reported in seconds) for status updates Frequency of checks (calculated in hours) to see if any of the stored jobs should be deleted How long a job should be stored on the CloudScan Controller (calculated in hours) before it is deleted URL for HP Fortify Software Security Center (SSC) Server; all uploads will be sent to this server when using SSC Server Upload mode. URL for the CloudScan Controller; used in s to refer to this server for manual job result downloads. HP Fortify CloudScan Installation, Configuration, and Usage Guide 12

13 Option ssc_cloudctrl_secret Value 3. Restart the CloudScan Controller. A password that HP Fortify Software Security Center (SSC) uses when requesting data from the CloudScan Controller. This must be identical to the SSC and CloudScan Controller Shared Secret password set up SSC s ssc-configuration.jar file. For more information on setting up SSC to monitor and troubleshoot CloudScan, see HP Fortify Software Security Center User Guide. To Start and Stop the CloudScan Controller on Windows To start the CloudScan Controller: Click the Start button, go to All Programs/Fortify Software/HP Fortify CloudScan Controller vx.xx and select Start HP Fortify CloudScan Controller to start the server. To stop the CloudScan Controller: Click the Start button, go to All Programs/Fortify Software/HP Fortify CloudScan Controller vx.xx and select Stop HP Fortify CloudScan Controller to stop the server. To Install the CloudScan Controller on Linux Before you begin installing the CloudScan Controller, make sure your CloudScan Cloud is up and running. Unzip and untar the HP-Fortify-X.XX-Cloud-Scan-Controller-Unix.tar.gz package. Move the Tomcat folder to the directory of choice on your Linux machine 1. Navigate to <Installation Directory>/tomcat/webapps/cloud-ctrl/WEB-INF/classes 2. Edit the hadoop.properties file as follows: Option job_tracker Value The DNS name of the Job Tracker:port number name_node The DNS name of the Name Node file_system_root The Hadoop file system root (virtual file path) Note: The CloudScan Controller installation includes a copy of the CloudScan CLI, located at: c:\program Files (x86)\fortify Software\HP Fortify vx.xx Cloud Scan Ctrl\cloudscan.zip. The CloudScan CLI is installed with HP Fortify Static Code Analyzer, and is included here for those cases when you need to update CloudScan but intend to use an earlier supported version of HP Fortify Static Code Analyzer. Unzip the contents of this file into your Apps and Analyzers installation directory in order to update the CLI to the latest version. To Start and Stop the CloudScan Controller on Linux To start the CloudScan Controller: Run startup.sh from the <Install Directory>/CloudScan Controller/Tomcat/bin directory. To stop the CloudScan Controller: Run shutdown.sh from the <Install Directory>/CloudScan Controller/Tomcat/bin directory. HP Fortify CloudScan Installation, Configuration, and Usage Guide 13

14 Securing the CloudScan Controller The following instructions provide the necessary steps to create a secure connection (HTTPS) between the CloudScan Controller/Tomcat server and CloudScan CLI. It requires either a self-signed certificate or a certificate that has been signed by a certificate authority such as VeriSign. Self-Signed Certificates To enable SSL on Tomcat using a self-signed certificate: 1. Use the Java keytool to generate a new keystore containing a self-signed certificate: %JAVA_HOME%\bin\keytool -genkey -alias <aliasname> -keyalg RSA -keystore "<path to keystore> The keytool will prompt you for some information: Prompt Enter keystore password: Re-enter new password: What is your first and last name? What is the name of your organizational unit? What is the name of your organization? What is the name of your City or Locality? What is the name of your State or Province? What is the two-letter country code for this unit? Confirm you entries: Enter key password for <tomcat><return if same as keystore password>: Re-enter new password: Data Type in a secure password. Re-enter your secure password. Type your first and last names. Type a name to identify the group that will be using the cert. (This can be anything you want.) Type the name of your organization. (This can be anything you want.) Type in the city or locality. (This can be anything you want.) Type in the state or province. (This can be anything you want.) If your sever is located in the United States, type US. Type yes to confirm your entries. Type a password for your Tomcat server key or touch Return to use the same password you established for your keystore. (HP Fortify recommends that you create a new password here.) Re-type your key password. 2. Modify the server.xml file in the tomcat\config directory. Uncomment the connector and set the keystorefile path and the keystorepass. a. Add the following connector to server.xml <Connector port="8443" maxthreads="200 scheme="https" secure="true" SSLEnabled="true" keystorefile= mykeystore" keystorepass="<mypassword>" clientauth="false" sslprotocol="tls"/> Note: An example <Connector> element for an SSL connector should be included in the default server.xml file installed with Tomcat. b. Restart your Tomcat server. HP Fortify CloudScan Installation, Configuration, and Usage Guide 14

15 3. Add the certificate to the keystore on your client machines where you plan to run the CloudScan CLI. a. Open a command prompt and type: CD C:\Program Files\Fortify Software\HP Fortify vx.xx\jre\bin keytool -import -alias <nameforalias> -keystore..\lib\security\cacerts - file YourCertFile.cer -trustcacerts where YouCertFile.cer is the same certificate file that you imported on Tomcat. You will need to do this on each of the build machines that will be hosting the CloudScan CLI. If the certificate is not available, you can export it from the Tomcat keystore: <Java_Home> \jre\bin keytool -export -alias <nameforalias> -keystore <mykeystore> -file YourCertFile.cer Certificates Signed by a Certificate Signing Authority To enable SSL on Tomcat using a certificate signed by a certificate signing authority: 1. Use the Java keytool to generate a new keystore containing a self-signed certificate: %JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA -keystore <mykeystore>" The keytool will prompt you for some information. Answer as follows: Prompt Enter keystore password: Re-enter new password: What is your first and last name? Data Type in a secure password. Re-enter your secure password. Type in your first and last names. What is the name of your organizational unit? What is the name of your organization? What is the name of your City or Locality? What is the name of your State or Province? What is the two-letter country code for this unit? Confirm your entries: Enter key password for <tomcat><return if same as keystore password>: Re-enter new password: Type a name to identify the group that will be using the certificate. (This can be anything you want.) Type the name of your organization (This can be anything you want.) Type in the city or locality. (This can be anything you want.) Type in the state or province. (This can be anything you want.) If your server is located in the United States, type US. Type yes to confirm your entries. Type a password for your Tomcat server key, or type Return to use the same password you established for your keystore. HP Fortify recommends that you create a new password here. Re-type your key password. HP Fortify CloudScan Installation, Configuration, and Usage Guide 15

16 2. Generate a Certificate Signing Request (CSR). In order to obtain a certificate from a certificate signing authority, you must generate a Certificate Signing Request (CSR). The CSR will be used by the certificate authority to create the certificate. Create the CSR as follows: %JAVA_HOME%\bin\keytool -certreq -alias <aliasname> -keyalg RSA -file "yourcsrname.csr" -keystore "<mykeystore>" 3. Send the CSR file to the certificate signing authority you have chosen. 4. Import your signed certificate into the keystore. Once you receive your certificate from the certificate signing authority, import it into the keystore that you created. Note: If you purchased your certificate from VeriSign, you will first need to import the Chain Certificate. You can find the specific Chain Certificate on the VeriSign website or click the link for the Chain Certificate in the you received from VeriSign with your certificate. Import your signed certificate as follows: %JAVA_HOME%\bin\keytool -import -alias IntermediateCA -trustcacerts -file "chaincert.crt" -keystore "<mykeystore>" Note: The root CA should already in the cacerts file of your JDK, so you are just installing the intermediate CA for your certificate signing authority. %JAVA_HOME%\bin\keytool -import -alias <aliasname> -trustcacerts -file "YourVerisignCert.crt" -keystore "<mykeystore>" 5. Modify the server.xml file in the tomcat\config directory Add the following connector to server.xml <Connector port="8443" maxthreads="200" scheme="https" secure="true" SSLEnabled="true" keystorefile="<mykeystore>" keystorepass="<mypassword>" clientauth="false" sslprotocol="tls"/> Note: An example <Connector> element for an SSL connector should be included in the default server.xml file installed with Tomcat. Restart your Tomcat server. Installing the CloudScan CLI The CloudScan CLI can be installed on build machines running Windows, Macintosh, or Unix-based operating systems. The CloudScan CLI is installed when you install SCA on your computer. Installation on Windows Run the HP-Fortify-X.XX-Analyzers_and_Apps-Windows-x64.exe file for installation on a 64-bit system, or HP-Fortify-X.XX-Analyzers_and_Apps-Windows.exe if you are installing on a 32-bit system. Select the CloudScan CLI option in the application tree and complete the installation. After installation, you can run the CloudScan CLI (cloudscan.bat) from the bin directory of the installation directory. HP Fortify CloudScan Installation, Configuration, and Usage Guide 16

17 Installation on Unix-based Machines 1. Uncompress the Analyzers and Apps package for your OS. OS Linux HPUX AIX FREEBSD Solaris_SPARC Package HP-Fortify-X.XX-Analyzers_and_Apps-Linux-x86.tar (32-bit) HP-Fortify-X.XX-Analyzers_and_Apps-Linux-x64.tar (64-bit) HP-Fortify-X.XX-Analyzers-HPUX-PARISC.tar HP-Fortify-X.XX-Analyzers-AIX-PAP32.tar HP-Fortify-X.XX-Analyzers-FREEBSD-x86.tar HP-Fortify-X.XX-Analyzers-Solaris-SPARC.tar Solaris_x86 HP-Fortify-X.XX-Analyzers-Solaris-x86.tar 2. Move the CloudScan directory to a location on the build machine where you want to run it. 3. Change to the <Install Directory>CloudScan\bin directory. 4. Type./cloudscan to run the CloudScan CLI. Installation on Mac The CloudScan installer package for the Mac OS X platform is offered as a DMG file, also known as a disk image file. This mountable disk image is used for Mac OS software installers downloaded from the Internet. Opening the image file mounts a virtual disk on your system. To install CloudScan on a Mac OS X platform: 1. Navigate to the directory containing the downloaded software 2. Double-click the DMG file to create a virtual drive that contains the CloudScan folders. There are both 32-bit and 64-bit packages. Select the correct one for your platform Macintosh HP-Fortify-X.XX-Analyzers_and_Apps-Mac-x86.dmg (32-bit) HP-Fortify-X.XX-Analyzers_and_Apps-Max-x64.dmg (64-bit) 3. Copy the folders and paste them to the installation location of your choice, as in the following example: /Applications/HP Fortify Software/ 4. Open a terminal and CD to the /bin directory. 5. To run the CloudScan CLI, t ype./cloudscan. To Set the Location of the CloudScan Controller When issuing commands from the CloudScan CLI, you will need to identify the location of the CloudScan Controller you intend to use. You can do this directly, by identifying the CloudScan Controller s URL, or indirectly, by pointing to SSC. To Configure the HP Fortify Software Security Center with the location of the CloudScan Controller: 1. Run the ssc-configuration.jar file. 2. Select the Core tab. 3. Type the URL of the CloudScan Controller into the CloudScan Controller URL field. 4. Use the -sscurl parameter on the CLI to identify the CloudScan Controller via HP Fortify Software Security Center. HP Fortify CloudScan Installation, Configuration, and Usage Guide 17

18 Note: For more information on running the ssc-configuration.jar file, see the HP Fortify Software Security Center Installation and Configuration Guide. To directly identify the CloudScan Controller, use the -url parameter. For more information, see Global Options on page 19. Creating an SCA Mobile Build Session CloudScan requires that you use SCA mobile build sessions after the translation phase. SCA mobile build sessions allow a project to be translated on one machine and analyzed on another. During the process, all files used at analysis time are copied into the build session directory. Mobile build sessions may be enabled in one of two ways: During translation phase: Set the com.fortify.sca.mobilebuildsessions property to true. After completing the translation phase: Run sourceanalyzer -b <buildid> -make-mobile All source files and any files referenced by those source files will be copied into the build session directory. The build session directory and build session file may then be copied to another location and analyzed without the need for the original source files to be present and accessible. CloudScan requires that you create a mobile build session for use in processing your job request. HP Fortify CloudScan Installation, Configuration, and Usage Guide 18

19 Chapter 4: Using the CloudScan CLI The CloudScan CLI is run from the build machine and enables you to upload a job request to the CloudScan Controller for processing or retrieve job results from the CloudScan Controller. There are three types of job upload requests: HP Fortify Software Security Center Server upload: the resultant FPR is uploaded to the Software Security Center Server. Block upload: the FPR is returned to the CLI. Default upload: the default setting returns an with instructions if an address has been provided, or submits the job and exits. CloudScan CLI Command Syntax CloudScan CLI command syntax follows the pattern below: cloudscan [global options] command [command options] Global Options The global options affect the type of results the CLI returns. Global Option -version -help <command> Use Returns the CloudScan CLI version number. Returns help for the specified command. For the complete list of CloudScan commands and arguments, type all as the command. For a list of global options and commands, issue the command without an argument. -url <url> -sscurl <url> -ssctoken <token> Sets the URL of the CloudScan Controller that the CloudScan CLI communicates with. Sets the URL of the SSC Server that identifies the CloudScan Controller to be used. In order to use this option, you must configure the SSC server with the CloudScan Controller address. When using the -sscurl option, you also need to provide an -ssctoken. To generate an ssctoken: fortifyclient -url -user <username> -password <password> token -gettoken CloudCtrlToken HP Fortify CloudScan Installation, Configuration, and Usage Guide 19

20 Commands There are four commands that you can issue from the CloudScan CLI. Command start Use Initiates the CloudScan program and accepts options that direct the way CloudScan processes the job. Includes options for naming and locating the output files (FPR and/or log). For the list of start command options, see Start Command on page 21. status Returns the status of the job by specifying its token Example: Cloudscan -url status -token Returns the status of the Controller. Example 2: Cloudscan -url status -ctrl retrieve cancel Initiates a download request to the CloudScan Controller. For more information on using the -retrieve command, see Retrieve Command on page 24. Requests cancelation of a pending or running job in the CloudScan system. HP Fortify CloudScan Installation, Configuration, and Usage Guide 20

21 Chapter 5: Issuing a Job Upload Request The structure for uploading a job request is as follows: cloudscan [global options] start [ <address>] [-upload (-versionid <id> - project <name> -versionname <name>) -uptoken <token> -block [-o] -f <fprfile> -log <logfile>] (-mbs <file> -b <id> [-projroot <dir>]) -scan [-rules <file dir>][-filter <file>][-projtl <file>] <otherscaargs> [@file] When you upload a job request, the basic argument structure has two sections. The first section, the start command and its options, provides basic information for authenticating and running the job. The second section, the -scan command and its options, provides information SCA needs to perform the scan. Start Command The first section of the job request structure consists of the start command and options that define and customize the process. The start command structure includes options that define the files and data needed for the scan. cloudscan [global options] start [- <address>] [-upload (-pvid <id> -project <name> -versionname <name>) -uptoken <token> -block [-o] -f <fprfile> -log <logfile>] In this section of the argument, the start command initiates the upload to the CloudScan Controller. Options provided after start and before -scan (see Scan Option below) can be specified in either a cloudscan.properties file or on the command line. When an argument appears in both places, the command line value takes precedence. The start command options are identified in the following table. Option - <address> -upload, --upload-to-ssc -project <name>, --project-name <name> -versionname, --project-version-name -versionid <id>, --project-version-id <id> -uptoken <token>, --ssc-upload-token <token> Definition (Optional) address the CloudScan Controller will use to status and error messages. FPR file to be uploaded to HP Fortify Software Security Center on completion of job. The name of the SSC project that the FPR file should be sent to. Note: If the name contains a space, put double quotes around it. The project version of the SSC project. Note: If the name contains a space, put double quotation marks around it. Specify the SSC project version ID. The Software Security Center Server analysis upload token. HP Fortify CloudScan Installation, Configuration, and Usage Guide 21

22 Option -block -o, --overwrite Definition When you are not using the HP Fortify Software Security Center Server, -block can be used to initiate a request that blocks the CLI until the job is completed. Results of the job can be downloaded from the CloudScan Controller. Tells CloudScan that existing jobs and logs can be overwritten upon result download. If this option is not set, your job will fail if files already exist in the directory. -f <file>, --output-file <file> Request an FPR file be output. -log <file>, --log-file <file> -mbs <file> Note: You must request an FPR, a log file, or both. Request that a log file be output. Note: You must request an FPR, a log file, or both. The SCA mobile build session to use. Note: If you do not have an SCA mobile build session, you can use the build ID instead. -b <id>, --build-id <id> Build id used to export a session from sourceanalyzer. -projroot <dir>, --project-root <dir> The project working directory SCA used during an SCA mobile build session export. You only need to specify this if you used -D com.fortify.sca.projectroot during translation. Scan Options There are two types of scan options used by CloudScan: Options that are supported by the CloudScan CLI Options that are passed on to SCA for processing The first group of options include -rule, -filter, and -projtl. These options must be entered on the command line prior to the -scan command. Other SCA arguments, which are not supported by the CloudScan CLI, must be entered after the -scan command and are passed on to SCA for processing. The -scan option should be included even if you do not have additional parameters that you want to send to SCA. The -scan option (and optional SCA-specific parameters) must be the last option in the command string. (-mbs <file> -b <id> [-projroot <dir>]) [-rules <file dir>]* [-filter <file>]* [- projtl/-project-template <file>] -scan <otherscaargs> [@file] The options identified in the following table are those that the CloudScan CLI understands (-rules, - filter, and -projtl) followed by information on how to use the -scan command and its options to provide SCA-specific options. HP Fortify CloudScan Installation, Configuration, and Usage Guide 22

23 Options -rules <file/dir> -filter <file> -projtl, --project-template <file> Definition (Optional) Name of a custom rules file to include or the directory and subdirectories where the custom rules files are located. Because you may have custom rules with the same name but residing in different directories/subdirectories, the rules files will be numbered as discovered. So rules.xml might become rules.xml.0 and so on. You can identify more than one file or directory by repeating this command. (Optional) A filter file to be used during the scan. You can identify more than one filter file by repeating this command. (Optional) A project template to use during the scan. (Optional) SCA arguments you want to pass on to sourceanalyzer that are not supported by the CloudScan CLI. (Optional) An SCA argument file. The SCA argument file contains a list of arguments that are expanded for use with sourceanalyzer. SCA argument files must appear at the end of the command line or your command may fail. Note: When adding SCA options that are not recognized by the CloudScan (that is, not included in the list above), they must be added to the end of your command line string. When the first SCA option is encountered, all remaining options are ignored by CloudScan and passed on to SCA. Sample Job Upload Requests There are three supported methods for submitting a job request to the CloudScan Controller: HP Fortify Software Security Center upload Block upload Default upload HP Fortify CloudScan Installation, Configuration, and Usage Guide 23

24 HP Fortify Software Security Center Upload An HP Fortify Software Security Center upload generates a job request where the resultant FPR is uploaded to HP Fortify Software Security Center. An SSC upload requires the -upload option, an upload token, and a project version ID or project name and project version name. Only one predefined SSC server may be the upload target. It is configurable using config.properties on the CloudScan Controller. The following is an example of a Software Security Center Server upload request: cloudscan -sscurl start - build@example.com -upload -project My Project -versionname 1.0 -uptoken mbs proj1_0.mbs -rules rule0.xml -scan <sca args> Block upload A block upload includes a -block option, an FPR file name, and/or a log file name. It causes the CLI to block after job submission and wait for the job to complete. When the job is complete, the resulting FPR and/or log file will be downloaded to the specified paths. If a file exists at the specified location, it will fail unless the -o (overwrite) option was included on the command line. The following is an example block upload request: cloudscan -url start - build@example.com -block -f /buildout/proj1_0.fpr -log /buildout/proj1_0.log -mbs proj1_0.mbs -rules rule0.xml -scan <sca args> Note: -block [-o] - returns an FPR and/or log file and overwrites any existing copies. This behavior differs from Fortify SCA where the [-o] argument merges FPRs and logs rather than destroying the preexisting copy. Default upload If you do not include -block or -ssc options, your upload will use default settings and the CLI will exit after submitting the job. The following is an example of a default upload request: cloudscan -url start - build@example.com -mbs proj1_0.mbs -rules rule0.xml -scan <sca args> Cancel Command The cancel command is used to cancel a remote scan job. To issue a cancel command: cloudscan url cancel -token <token> or cloudscan url cancel --job token <token> Retrieve Command The retrieve command is used to download your job results from the CloudScan Controller. The job must be complete for this command to succeed. The CLI can be set to wait for the job to complete before issuing the command by using the -block option. This is specified similarly to the block upload mode. HP Fortify CloudScan Installation, Configuration, and Usage Guide 24

25 Issuing a Job Download Request The following is an example of a job download request to the CloudScan Controller. Your job result can be downloaded from the Controller using the -retrieve command. The basic structure is the same as the structure for the upload job request: cloudscan -url retrieve -token f /buildout/proj1_0.fpr -log /buildout/proj1_0.log Setting CLI Options in cloudscan.properties File CloudScan options that do not change from job request to job request can be set up in the <install directory>/core/config/cloudscan.propeties file. The file contains property keys and must be written in the following format: com.fortify.cloud.cli.<argument> You can use either the short or long form of the argument, without any preceding dashes. A cloudscan.properties setting can be overridden on the command line. The argument order of precedence is: Command line Short argument name in cloudscan.properties file Long argument name in cloudscan.properties file Examples of CloudScan properties: com.fortify.cloud.cli.url= com.fortify.cloud.cli. =build@example.com Note: The cloudscan.properties is optional and not included in the installation. CloudScan Log File The CloudScan log file is located in the following directory: Windows %FORTIFY_HOME%/cloudscan/log where %FORTIFY_HOME% is ${win32.localappdata}/fortify On Window 7, for example, it is C:\Users\<user>\AppData\Local\Fortify Linux ~/.fortify/cloudscan/log/cloudscan.log HP Fortify CloudScan Installation, Configuration, and Usage Guide 25

26 Chapter 6: Monitoring CloudScan with HP Fortify Software Security Center You can configure CloudScan and HP Fortify Software Security Center so that you can monitor and troubleshoot CloudScan from within Software Security Center. From the CloudScan tab in Software Security Center, you can: View the results of a scan Troubleshoot CloudScan Controller issues View running scans and scans completed within the last seven days To configure Software Security Center to monitor CloudScan, you will need to create a secret password that both systems use to authenticate each other. In CloudScan, set the ssc_cloudctrl_secret password in the config.properties file. On the SSC server, you will need to open the ssc-configuration.jar and update the CloudScan tab. For more information on setting up HP Fortify Software Security Center, see the HP Fortify Software Security Center User Guide. HP Fortify CloudScan Installation, Configuration, and Usage Guide 26

27 Chapter 7: Upgrading CloudScan When upgrading from a previous version of CloudScan, you may want to preserve your database from the previous installation. Updating the Controller If you need to preserve your Cloud Controller database, stop the controller and copy the cloudctrldb and jobfiles directories to a location outside the install directory. After uninstalling the old Cloud Controller and installing the new one, copy the cloudctrldb and the jobfiles into the install directory. Note: The Windows uninstaller will leave the database and jobfiles on the machine, so copying them to a different directory before uninstalling the old version of CloudScan is not necessary. If you do not want to preserve data from the previous version, you should delete the stored data before installing the new version of the CloudScan Controller. Updating the CloudScan CLI If you are updating CloudScan but not updating HP Fortify Static Code Analyzer, the CloudScan Controller installation includes a copy of the CloudScan CLI: C:\Program Files (x86)\fortify Software\HP Fortify vx.xx Cloud Scan Ctrl\cloudscan.zip. The CloudScan CLI should not be run from this directory. The CloudScan CLI is installed when you install HP Fortify Static Code Analyzer, so the copy included here is for those cases when you intend to update CloudScan but continue to use an earlier, supported version of HP Fortify Static Code Analyzer. Replace the old CloudScan directory with the latest version to update the CLI. Updating config.properties Because a few parameters have been altered, you should use the updated config.properties file with your new installation. You may need to edit it to match any customizations you made to the previous version. Initiating a Job Request using SCA Wizard If you are using HP Fortify Scan Wizard to simplify launching HP Fortify Static Code Analyzer scans, you can elect to use CloudScan to process your request. For more information on Scan Wizard, see the HP Fortify Scan Wizard Technical Note. HP Fortify CloudScan Installation, Configuration, and Usage Guide 27