Test Automation in AppScan Enterprise Using AppScan Proxy Server

The AppScan Proxy Server enables you to record your own traffic, and use it as Explore data in your ASE job.

Overview

This section describes about incorporating dynamic scanning in your functional testing. In the world of DevOps it's increasingly important to be able to incorporate security scans in the functional testing process for web applications. If you use an automation framework (such as Selenium), you can take advantage of the scripts that are already written to create tailor-made scans. The requests from the automation framework to the web applications are sent through the Proxy Server proxy. The server records the traffic and saves it as a DAST configuration file. You can then upload the file to be used by ASE as Explore data for a scan. You can also send traffic through the automation server proxy manually to create a DAST configuration file.

This diagram depicts the automated scan flow with AppScan® Enterprise.

Typical Workflow

Initialization (once per server):
1. Install Proxy Server
2. [Optional] Configure Proxy Server
  1. Handle SSL warning (root certificate)
  2. Inactivity timeout
  3. Chained proxy
3. Start Proxy Server
Running Scans:
1. Start proxy instance listening on specified or randomly selected port, as configured (see Using the proxy server).
2. Run your Selenium script (or other functional test) through the selected proxy.
  Or
  Browse your web app manually using a web browser configured to work through the selected proxy.
3. Stop the proxy and save the traffic recording.
4. Update the Explore data of an existing ASE job, using the ASE REST API.
  For more information, refer to documentation https://%3C%3Case_server%3E%3E:9443/ase/api/pages/apidocs.html

Note: The demo script for this workflow, ProxyServerDemoScript.py, is available in the Installation folder.

Install Proxy Server

Download one of the current versions of Node.js and install it on your machine.
Copy the AppscanProxyServer.zip from <Installation_dir>\WebApp\downloads\ directory and unzip it to a folder on your machine.
Note: AppscanProxyServer api related documentation is available at <Unzipped folder of AppscanProxyServer.zip>/apidocs/index.html

Configure Proxy Server

Root Certificate

If your application uses SSL (HTTPS), the proxy must act as a man-in-the-middle to record traffic. For this the proxy server must have a root certificate that it can use to sign its communication with the application.

By default, the proxy server generates a unique root certificate, without any user intervention. However, while browsing the application an SSL warnings is displayed, when you can do one of the following:

Ignore the warnings.
Install the certificate generated by the proxy on your machine(s):
1. Use the REST API to download the self-signed Root Certificate Authority, used by the AppScan Proxy Server, as a PEM file.
2. Install it on the browser used for the Explore, or wherever needed (depending on where the traffic is sent from).
Import your own root certificate to the proxy server. Supported certificate formats are PKCS12 (.P12, .PFX), JKS:
1. Open a command line window and navigate to the installation folder on the Proxy Server machine.
2. Run the following command:
```
.\Java\jre\bin\java -jar DastProxy.jar -irc [path to certificate file] -ircp [password]
```
  Note: To see the complete command usage, run:
```
.\Java\jre\bin\java -jar DastProxy.jar
```
Important: It is recommended to use a dedicated test certificate, as the certificate is saved on the proxy server.

Proxy Server Inactivity Timeout

If a proxy instance is not closed with a close command after use, it remains open and listening on the port. Proxy instances are closed automatically if they are idle for a predefined time. The default inactivity timeout for proxy instances is 60 minutes. You can change this value in the Settings.json file saved in the installation folder.

Important: Do not make changes to any other settings in this file.

Chained Proxy

If you need to define more than one chained proxy, or exceptions to the proxy, use the chained proxy rules file (proxy.chain) found in the installation folder. The file includes instructions for use.

Start Proxy Server

To start the AppScan Proxy Server, run the command:

node app.js [port]

where, *port = the port on which the AppScan Proxy Server responds for REST API requests.

Note: If you do not define the port, by default, the port 8383 is used.

Note: It is advisable to run the AppScan Proxy Server permanently, and not necessary to stop it.

Use the Proxy Server

After starting the Proxy Server, you can start a proxy instance and send your traffic to the application.

To view the REST API documentation, type in a browser: http://localhost:<port>.
Note: To view from a different machine, type: http://<IP>:<port>
where, *port = the port on which the AppScan Proxy Server listens.
*IP = the IP address of the machine on which the AppScan Proxy Server is installed.
If the site is secured (HTTPS), avoid SSL warnings by performing the following:
1. Use the REST API to download the self-signed Root Certificate Authority, used by the AppScan Proxy Server, as a PEM file.
2. Install the certificate on the browser used for the Explore, or wherever required (depending on where the traffic is sent from).
To start a proxy instance, use the REST API request: StartProxy, and define the recording port (to which you want to send the traffic).
Note: If the proxy server does not have direct access to the site, you can also define an upstream (chained) proxy with this REST API.
Note: If you need to define more than one chained proxy, or exceptions to the proxy, use the chained proxy rules file (proxy.chain) found in the installation folder.
Send your traffic via the defined recording port.
When done, send the REST API request: StopProxy.
Download the DAST configuration file(.dast.config), which contains the recorded traffic, by sending REST API request: Traffic.
The file is a ZIP file containing one or more .har (HTTP Archive) files.
Note: When you download the DAST configuration file, this data is deleted from AppScan Proxy Server.
You can use the DAST configuration file to update the Explore data of an existing job, using the ASE REST API. For more information, refer https://%3Case_server%3E:9443/ase/api/pages/apidocs.html.