Using the Native Scan Template

Fortify WebInspect and Fortify WebInspect Enterprise allow you to scan the back-end traffic generated by your Android or iOS app or service. Traffic can be generated by running your application on an Android, Windows, or iOS device, or by running the software through an Android or iOS emulator.

The Guided Scan wizard will step you through the necessary stages and steps required to scan your application back-end traffic. If you need to return to a previous step or stage, click the back navigation button, or click the step in the Guided Scan tree to be taken directly there.

Recommendation

Fortify recommends that you run only one scan at a time. When using SQL Express, in particular, depending on the size of the site, conducting concurrent (or parallel) scans might result in high usage of RAM, CPU, and disk resources on the Fortify WebInspect host.

Setting Up Your Mobile Device

Running a native scan requires that you configure the mobile device to work with a secure proxy. In order to do that, you will need to:

• Set up a Mobile Device/Emulator Proxy

• Install a Trusted Certificate

Guided Scan Stages

A Guided Scan using a mobile template consists of four or five stages, each of which has one or more steps. The stages are:

Native Mobile: where you choose a device or emulator, configure device/emulator proxy, and select the type of scan you want to run.

Login: where you define the type of authentication if back-end of your mobile application requires it.

Application: where you run your app, record Web traffic, and identify the hosts and RESTful endpoints to include in your scan.

Settings: where you review and validate your choices and run the scan.

Supported Devices

Fortify WebInspect and Fortify WebInspect Enterprise support scanning the back-end traffic on Android, Windows, and iOS devices.

Android Device Support

Any Android device, such as an Android-based phone or tablet.

Windows Device Support

Any Windows device, such as a Windows phone or Surface tablet.

iOS Device Support

Any iOS device, such as a iPhone or iPad, running the latest version of iOS.

Supported Development Emulators

In addition to support for Android and iOS devices, you can run your application through your Android or iOS emulator in your development environment. When scanning traffic generated via your device emulator, you must ensure that the development machine is on the same network as Fortify WebInspect or Fortify WebInspect Enterprise and that you have set up a proxy between Fortify WebInspect or Fortify WebInspect Enterprise and your development machine.

Launching a Native Scan

In order to launch a Native Scan, you will need to make sure your device or emulator is on the same network as Fortify WebInspect. In addition, you need to have authorization and access to the ports on the machine where you are running Fortify WebInspect in order to successfully create a proxy connection.

To launch a Native Scan:

1. Open Fortify WebInspect or Fortify WebInspect Enterprise.

2. Start a Guided Scan:

   • For Fortify WebInspect, click Start a Guided Scan on the Fortify WebInspect Start page.

   • For Fortify WebInspect Enterprise, click Guided Scan under Actions on the Web Console.

3. Select Native Scan from the Mobile Templates section.

   The Guided Scan wizard displays the first step in the Native Mobile stage: Choose Device/Emulator.

About the Native Mobile Stage

The first stage in the process is the Native Mobile stage. In this stage you will:

• Set up the device or emulator to use a proxy connection.

• Log the device or emulator on to the same network as your instance of Fortify WebInspect or Fortify WebInspect Enterprise.

• Install a client certificate on your device or emulator.

• Name the scan for future reference.

• Select a scan method.

• Select a scan policy.

• Select the crawl coverage amount.

Choose Device/Emulator Type Step

After launching the Guided Scan, you are provided with the options described in the following table.

Option	Description
Profile	The type of device or emulator you want to scan. Select a type from the drop-down menu. For more information, see Selecting a Profile.
Mobile Device/Emulator Proxy	The IP address and port number for the proxy that Fortify WebInspect or Fortify WebInspect Enterprise creates for listening to the traffic between your device or emulator and the Web service or application being tested. Unless the IP address and/or port are reserved for other activities, use the default settings. For more information, see Setting the Mobile Device Proxy Address.
Trusted Certificate	The port and URL to acquire a client certificate for your device or emulator. To download and install the certificate on your device or emulator, see Adding a Trusted Certificate.

Selecting a Profile

To set the device profile, select one of the following from the Profile drop-down textbox:

• iOS Device - An iPad or iPhone running the latest version of iOS.

• iOS Simulator - The iOS emulator that is part of the iOS SDK.

• Android Device - A phone or tablet running the Android operating system.

• Android Emulator - The Android emulator that is part of the Android SDK.

• Windows Device - A Windows phone or Surface tablet.

Setting the Mobile Device Proxy Address

The Mobile Device/Emulator Proxy section lists the Host IP address and the Port number that will be used to establish a proxy connection between your device or emulator and Fortify WebInspect or Fortify WebInspect Enterprise. Use the suggested settings unless the IP address or port number are unavailable on your system.

To set up a proxy on an iOS device:

1. Run the Settings application.

2. Select Wi-Fi.

3. Select the Wi-Fi network you are using to connect to Fortify WebInspect or Fortify WebInspect Enterprise.

4. Scroll down to the HTTP Proxy section and select Manual.

   The screen displays the network configuration options for the network your device is connected to.

5. Scroll down further and type in the Server IP address and the Port number provided by Fortify WebInspect or Fortify WebInspect Enterprise. If you don't have this information, see Choose Device/Emulator Type Step.

6. In Fortify WebInspect or Fortify WebInspect Enterprise, click the Verify button in the Trusted Certificate section to verify the connection is working properly.

   The Verify activity progress bar appears.

7. Launch the default browser on your device and visit any site to verify that Fortify WebInspect or Fortify WebInspect Enterprise is able to see the back-end traffic.

   If everything is configured properly, after a few moments, the Verify activity progress bar will state that the traffic has been successfully verified.

8. Click OK to dismiss the verification progress bar and then click Next to select a scan type.

To set up a proxy on an Android or Windows device, consult your operator’s instructions.

Adding a Trusted Certificate

If your site requires a secure connection, each time you run a scan, Fortify WebInspect or Fortify WebInspect Enterprise generates a unique client certificate for your device or emulator. You will need to install the certificate into the device’s (or emulator’s) certificate repository.

There are three ways to add a certificate:

• Scan the QR code from the Trusted Certificate section of Guided Scan (requires QR reader software).
• Type the address into the built-in browser on your device or device emulator.
• Copy the certificate to your system clipboard for applying later (used when scanning with a device emulator).

Choose the option that best suits your needs.

To Add a Certificate to an iOS device or emulator:

1. After scanning the QR code or typing the provided URL into your browser, the Install Profile page appears.

   Note: The WebInspect Root certificate status will display as Not Trusted until you add it to your root chain.

2. Tap the Install button.

   A warning screen will appear stating that the certificate is not trusted. Once you add the certificate to the certificate repository on your device or emulator, the warning will go away.

3. Tap Install on the Warning screen.

   The display changes to that of the current network your device or emulator is connected to. Make sure it is connected to the same network as Fortify WebInspect or Fortify WebInspect Enterprise.

Choose Scan Type Step

After setting up your device or emulator to work with Fortify WebInspect or Fortify WebInspect Enterprise during the first part of the Native Mobile stage, you will need to select the type of scan you would like to run.

Set the options as described in the following table.

Option	Description
Scan Name	Type a name for the scan so that later you can identify the scan on the Manage Scans page.
Scan Method	Choose the type of scan you want from the following list: Crawl Only: maps the attack surface of the specified workflow(s). Crawl and Audit: maps the attack surface of the specified workflow(s) and scans for vulnerabilities. Audit Only: only attack the specified workflows.
Policy	Select a policy for the scan from the drop-down menu. For more information on policies, see Fortify WebInspect Policies. For information on creating and editing policies, see the Policy Manager chapter in the Micro Focus Fortify WebInspect Tools Guide.
Crawl Coverage	Select the level of coverage you want using the Crawl Coverage slider.

About the Login Stage

If the application you intend to scan requires login credentials, you can use the login stage to either select a an existing login macro or record one for use with the scan.

If your application does not require login credentials, you can skip this section of the Guided Scan wizard by clicking through the options without assigning values, or clicking the next step in the Guided Scan tree to skip to the next stage.

In this stage you can:

• Configure network authorization
• Configure application authorization
• Create or assign a login macro

Network Authentication Step

If your application requires either network or application level authentication, you can assign it here.

Configuring Network Authentication

If your network requires user authentication, you can configure it here. If your network does not require user authentication, click the Next navigation button or the next appropriate step in the Guided Scan tree to continue on.

To configure network authentication:

1. Click the Network Authentication checkbox.

2. Select a Method from the drop-down list of authentication methods. The authentication methods are:

   • ADFS CBT

   • Automatic

   • Basic

   • Digest

   • Kerberos

   • Negotiate

   • NT LAN Manager (NTLM)

3. Type in the User Name and Password.

Configuring a Client Certificate

If your network is set up to accept a client certificate rather than a user name and password, you can configure Fortify WebInspect or Fortify WebInspect Enterprise to provide the client certificate upon request.

To configure a client certificate:

1. Select the Client Certificate check box.

2. Do one of the following:

   • To use a certificate that is local to the computer and is global to all users on the computer, select Local Machine.

   • To use a certificate that is local to a user account on the computer, select Current User.

   Note: Certificates used by a common access card (CAC) reader are user certificates and are stored under Current User.

3. Do one of the following:

   • To select a certificate from the "Personal" ("My") certificate store, select My from the drop-down list.

   • To select a trusted root certificate, select Root from the drop-down list.

4. Does the website use a common access card (CAC) reader?

   • If yes, do the following:

     1. Select a certificate that is prefixed with “(SmartCard)” from the Certificate list.

        Information about the selected certificate and a PIN field appear in the Certificate Information area.

     2. If a PIN is required, type the PIN for the CAC in the PIN field.

     Note: If a PIN is required and you do not enter the PIN at this point, you must enter the PIN in the Windows Security window each time it prompts you for it during the scan.

     3. Click Test.

        If you entered the correct PIN, a Success message appears.

   • If no, select a certificate from the Certificate list.

     Information about the selected certificate appears below the Certificate list.

Application Authentication Step

If your site requires authentication, you can use this step to create, select, or edit a login macro to automate the login process and increase the coverage of your site. A login macro is a recording of the activity that is required to access and log in to your application, typically by entering a user name and password and clicking a button such as Log In or Log On.

If Enable macro validation is selected in Scan Settings: Authentication for scans that use a login macro, Fortify WebInspect tests the login macro at the start of the scan to ensure that the log in is successful. If the macro is invalid and fails to log in to the application, the scan stops and an error message is written in the scan log file. For more information and troubleshooting tips, see Testing Login Macros.

The following options are available for login macros:

• Using a Login Macro without Privilege Escalation

• Using Login Macros for Privilege Escalation

• Using a Login Macro when Connected to Fortify WebInspect Enterprise

• Testing the Macro

Masked Values Supported

If the macro uses parameters for which values are masked in the Web Macro Recorder, then these values are also masked when configuring a Guided Scan in Fortify WebInspect.

Using a Login Macro without Privilege Escalation

To use a login macro:

1. Select the Use a login macro for this site check box.

2. Do one of the following:

   • To use a pre-recorded login macro, click the ellipsis button (...) to browse for a saved macro.

   • To edit an existing login macro shown in the Login Macro field, click Edit.

   • To record a new macro, click Create.

   For details about recording a new login macro or using an existing login macro, see the Web Macro Recorder chapters in the Micro Focus Fortify WebInspect Tools Guide.

3. Click the Next button.

   The Application Authentication Step is complete. Proceed to the Application Stage to run your application.

Using Login Macros for Privilege Escalation

If you selected the Privilege Escalation policy or another policy that includes enabled Privilege Escalation checks, at least one login macro for a high-privilege user account is required. For more information, see About Privilege Escalation Scans. To use login macros:

1. Select the High-Privilege User Account Login Macro check box. This login macro is for the higher-privilege user account, such as a Site Administrator or Moderator account.

2. Do one of the following:

   • To use a pre-recorded login macro, click the ellipsis button (...) to browse for a saved macro.

   • To edit an existing login macro shown in the Login Macro field, click Edit.

   • To record a new macro, click Create.

   For details about recording a new login macro or using an existing login macro, see the Web Macro Recorder chapters in the Micro Focus Fortify WebInspect Tools Guide.

   After recording or selecting the first macro and clicking the next arrow, a "Configure Low Privilege Login Macro" prompt appears.

3. Do one of the following:

   • To perform the scan in authenticated mode, click Yes. For more information, see About Privilege Escalation Scans.

     Guided Scan returns to the Select Login Macro window for you to create or select a low-privilege login macro. Continue to Step 4.

   • To perform the scan in unauthenticated mode, click No. For more information, see About Privilege Escalation Scans.

     The Application Authentication Step is complete. Proceed to the Application Stage.

4. Select the Low-Privilege User Account Login Macro check box. This login macro is for the lower-privilege user account, such as a viewer or consumer of the site content.

5. Do one of the following:

   • To use a pre-recorded login macro, click the ellipsis button (...) to browse for a saved macro.

   • To edit an existing login macro shown in the Login Macro field, click Edit.

   • To record a new macro, click Create.

   For details about recording a new login macro or using an existing login macro, see the Web Macro Recorder chapters in the Micro Focus Fortify WebInspect Tools Guide.

6. After recording or selecting the second macro, click the Next button.

   The Application Authentication Step is complete. Proceed to the Application Stage to run your application.

Using a Login Macro when Connected to Fortify WebInspect Enterprise

For a Fortify WebInspect that is connected to Fortify WebInspect Enterprise, you can download and use a login macro from the Fortify WebInspect Enterprise macro repository.

1. Select the Use a login macro for this site check box.

2. Click Download.

   The Download a Macro from Fortify WebInspect Enterprise window appears.

3. Select the Application and Version from the drop-down lists.

4. Select a repository macro from the Macro drop-down list.

5. Click OK.

Testing the Macro

Optionally, click Test to locate the login form and run macro validation tests before advancing to the next stage in the Guided Scan wizard. If you need to cancel the validation test prior to completion, click Cancel.

If the macro is invalid and fails to log in to the application, an error message appears. For more information and troubleshooting tips, see Testing Login Macros.

About the Application Stage

The Application Stage is where you run your application. During the application stage:

• Run the mobile application to generate and collect Web traffic.
• Identify the hosts and RESTful endpoints you want to include.

Run Application Step

To run the application and generate and collect Web traffic:

1. Click the Record button.
2. Exercise the application, navigating through the interface as your customers will.
3. When you have generated enough traffic, click the Stop button.
4. Click Play to verify your workflow.

Finalizing Allowed Hosts and RESTful Endpoints

After running the application and collecting Web traffic, a list will be generated of the Allowed Hosts and potential RESTful Endpoints.

To select the hosts to include in your audit, click the check boxes in the Enabled column of the Allowed Hosts table.

The list of RESTful endpoints is generated by listing every possible combination that could be a RESTful endpoint. Select the actual RESTful endpoints from the list by selecting their Enabled check boxes. To reduce the list to a more likely subset, click the Detect button. Heuristics are applied, filtering out some of the less likely results. Select the Enabled check boxes from the resultant list.

If Fortify WebInspect or Fortify WebInspect Enterprise didn’t find all of the RESTful endpoints, you can add them manually.

To set up a new RESTful endpoint rule:

1. Click the New Rule button.

   A new rule input box appears in the RESTful Endpoints table.

2. Following the sample format in the input box, type in a RESTful Endpoint.

To Import a List of RESTful Endpoints:

1. Click the Import button.

   A file selector appears.

2. Select a Web Application Description Language (.wadl) file.

3. Click OK.

About the Settings Stage

During the final stage, you can set a number of options that affect how the collected traffic is audited. The available options vary, based on the selections you have made.

Final Review Step

Configure Detailed Options

The Configure Detailed Options step allows you to set detailed options. These options will change from scan to scan, as they are dependent on the choices made in the Guided Scan wizard. Some of the options include:

Reuse Identified False Positives. Select a previous scan to identify vulnerabilities that have already been identified as false positives.

Traffic Analysis. You can use a self-contained proxy server on your desktop. With it you can monitor traffic from a scanner, a browser, or any other tool that submits HTTP requests and received responses from a server. You can also enable the Traffic Monitor and display the hierarchical structure of the Web site or Web service in a Fortify WebInspect navigation pane. It allows you to display and review every HTTP request sent by Fortify WebInspect and the associated HTTP response received from the server.

Scan Mode. A crawl-only feature. Allows you to set Discovery (Path Truncation) Path truncation  allows you to make requests for known directories without file names. This can cause directory listings to be displayed. You can also select the Passive Analysis (Keyword Search) option to examine every response from the Web server for (error messages, directory listings, credit card numbers, etc. ) not properly protected by the Web site.

Validate Settings and Start Scan

Options on this page allow you to save the current scan settings and, if WebInspect is integrated with WebInspect Enterprise, to interact with WebInspect Enterprise.

1. To save your scan settings as an XML file, select Click here to save settings. Use the standard Save as window to name and save the file.

2. If WebInspect is integrated with WebInspect Enterprise, a Templates section appears in the toolbar. Continue according to the following table.

   If you want to…	Then…
   Save the current scan settings as a template in the WebInspect Enterprise database Note: When editing an existing template, the Save is actually an update. You can save any edits to settings and change the Template Name. However, you cannot change the Application, Version, or Global Template settings.	Do one of the following: Click Save in the Templates section of the toolbar. Select Click here to save template. The Save Template window appears. Select an application from the Application drop-down list. Select an application version from the Version drop-down list. Type a name in the Template field.
   Load scan settings from a template	Click Load in the Templates section of the toolbar. A confirmation message appears advising that your current scan settings will be lost. Click Yes. The Load Template window appears. Select an application from the Application drop-down list. Select an application version from the Version drop-down list. Select the template from the Template drop-down list. Click Load. Guided Scan returns to the Site Stage for you to verify the Web site and step through the settings from the template.

3. If WebInspect is integrated with WebInspect Enterprise, the WebInspect Enterprise section appears on this page. You can interact with WebInspect Enterprise as follows:

   1. Select an application from the Application drop-down list.

   2. Select an application version from the Version drop-down list.

   3. Continue according to the following table.

      To run the scan…	Then…
      With a sensor in WebInspect Enterprise	Select Run in WebInspect Enterprise. Select a sensor from the Sensor drop-down list. Select a Priority for the scan.
      In WebInspect	Select Run in WebInspect. If you want to automatically upload the scan results to the specified application and version in WebInspect Enterprise, select Auto Upload to WebInspect Enterprise. Note: If the scan does not complete successfully, it will not be uploaded to WebInspect Enterprise.

4. In the Scan Now area, review your scan settings, and then click Start Scan to begin the scan.

Post Scan Steps

After you have completed your scan and run Fortify WebInspect or Fortify WebInspect Enterprise, you will need to reset your Android, Windows, or iOS device or emulator to its former state. The following steps show how to reset your iOS device to the way it was before you began. Steps for other devices and emulators are similar, but depend on the version of the OS you are running.

To remove the Fortify Certificate on an iOS device:

Run the Settings application.

1. Select General from the Settings column.

2. Scroll down to the bottom of the list and select Profile WebInspect Root.

3. Tap the Remove button.

To Remove the Proxy Settings on an iOS device:

1. Run the Settings application.

2. Select Wi-Fi from the Settings column.

3. Tap the Network name.

Delete the Server IP address and the Port number.

See Also

Guided Scan Overview