Test Automation in AppScan® Enterprise using AppScan Proxy Server

The AppScan Proxy Server enables you to record traffic to use as Explore data in your AppScan Enterprise (ASE) job. The AppScan Proxy Server is a system for managing recording proxies. Proxy instances can be created on demand to record traffic that will later be used for a DAST scan. This document describes how to set up and use the proxy server.

Overview

In the world of DevOps it's increasingly important to be able to incorporate security scans in your CI/CD processes. 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.
  • Using the AppScan Proxy Server, you can automatically start a recording proxy. The requests from the automation framework to the web app are then recorded as they are sent through this recording proxy. The traffic is saved in HAR format in a .dast.config file, that you can later upload to be used by AppScan Enterprise (ASE) as Explore data for a scan.
  • You can also record traffic manually, through the proxy server, to create a .dast.config file.
  • You can also upload your own HAR file directly to ASE, without using the proxy server.

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


Automated scan flow with AppScan Enterprise

Typical Workflow

  1. Install Proxy Server
  2. Configure Proxy Server
  3. Start Proxy Server
  4. Using the Proxy Server
Note: The demo script for this workflow ProxyServerDemoScript.py can be found in the AppScan installation folder.

Install the AppScan Proxy Server

  1. Download one of the current versions of Node.js (v12 or later) and install it on your machine. If your service is FIPS compliant, you must use a FIPS compliant Node.js server.
  2. Unzip DastProxyServerStandalone.zip to a folder on your machine.
  3. To overwrite a default port for the Proxy Server to run on: Configure the port setting in Settings.json.

Configure the AppScan Proxy Server

After making any configuration changes, you must restart the server.
Note: Settings.json is a JSON file and so certain characters such as for example “ (double quote) and \ (backslash) need to be escaped, so “ becomes \” and \ becomes \\. Do not change the internalConfiguration settings in this file.

FIPS compliant mode

  1. Locate the file Settings.json in the root folder of the proxy server and open it in a text editor.
  2. Locate the setting requireFips and change its value from false to true.
  3. Save the file.

Proxy server connection

  1. To set a default port for the Proxy Server to run on: Configure the port setting in Settings.json.
  2. For a secure (SSL) connection to the Proxy Server: Configure your own PEM or PKCS12 certificate in Settings.json.
    • A PEM certificate requires two files (full paths) and a PKCS12 certificate requires one file (full path) and a password.
    • Do not forget to escape characters as needed both in file paths and password, for instance a password such as abc!”123 would become abc!\”123 (the “ is escaped).

      Example using openssl to create a PEM certificate:

      openssl req -newkey rsa:2048 -new -nodes -keyout key.pem -out csr.pem

      openssl x509 -req -days 365 -in csr.pem -signkey key.pem -out server.crt

      Example using openssl to convert the PEM certificate to PKCS12 certificate:

      openssl pkcs12 -export -out certificate.pfx -inkey key.pem -in server.crt

      Example using Java’s keygen tool to convert a JKS certificate to PKCS12 certificate:

      keytool -importkeystore -srckeystore certificate.jks -srcstoretype JKS -destkeystore certificate.p12 -deststoretype PKCS12

Root Certificate

If the application you are testing uses SSL (HTTPS), the AppScan recording proxy must act as a man-in-the-middle to record traffic. To do this it must have a root certificate that it can use to sign its communication with the app.

By default, the AppScan Proxy Server generates a unique root certificate, and no user intervention is needed. However, when browsing the app you will get SSL warnings. You can either ignore them, or do one of the following:
  1. Install the certificate generated by the AppScan Proxy Server 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).
  2. Import your own root certificate to the AppScan 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 the .\Java\jre\bin\java -jar DastProxy.jar command.

      Important: Since the certificate will be saved on the proxy server, it is recommended that you use a dedicated test certificate.

  3. Provide your own fixed server certificate (not a root certificate) in the StartProxy command.

Set Proxy Inactivity Timeout

If a recording proxy instance is not closed with a close command after use, it remains open and listening on the port. Recording proxy instances are closed automatically if they are idle for a predefined time.

The default inactivity timeout for recording proxy instances is 60 minutes. You can change this value by changing the value of inactivityTimeoutInMinutes in the Settings.json file saved in the installation folder.

Encrypt Traffic

By default, the traffic (.dast.config) file is not encrypted. To configure the server to encrypt all traffic, change the "encryptDastConfig" value to “true” in the Settings.json file, found in the installation folder.

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 the Proxy Server

You can simply start the Proxy Server, or run it as a service (below). Note that you can’t do both in parallel.

To start the Proxy Server:
  • Run the command: node app.js [port]

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

Note:
  • If you do not define the port when starting the Proxy Server, the port set in the Settings.json file is used, if none is defined there, port 8383 is used.
  • There is no need to stop the Proxy Server, you can leave it running permanently.

Start as a Service

You can run the Proxy Server as a Service, using the service.js executable found in the Service folder. Service uses Local System privileges.
Note: All service commands must be run with administrator privileges (Run as administrator).

To start the service, run the command:

node service.js --install

node service.js --start

Additional Service Commands

You can print this list by running the command node service.js --help

Service commands Description
--start Start the service
--stop Stop the service
--install Install the service
--uninstall Stop and uninstall the service
--h | --help Output usage information

Using the Proxy Server

Once the Proxy Server has started, you can start new recording proxy instances, to record the traffic of your application.

  1. To start a proxy instance, use the REST API request: StartProxy
  2. Send your traffic to the application you are testing, via the defined recording proxy port.
  3. When done, send the REST API request: StopProxy.
  4. Download the .dast.config file, 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. When you download this file, the data is deleted from the AppScan Proxy Server.
  5. You can use the .dast.config file to update the Explore data of an existing job, using the ASE REST API. See the documentation link: https://<domain>:9443/ase/api/pages/apidocs.html. For more details, see Proxy Server API commands section.

Proxy Server API commands

Once the Proxy Server has started, you can start a recording proxy instance, and send your traffic to your application.

Documentation

To view the complete REST API documentation in Swagger, type in a browser: http(s)://<server>:<port>

All commands point to an endpoint that looks like this:

http(s)://[server]:[port]/automation/

server = IP address of the machine on which the Proxy Server is installed (default is localhost)

port = port on which the Proxy Server listens

"StartProxy"

Start a proxy that listens on the specified port.
  • URL: http://[server]:[port]/automation/StartProxy/<recordingPort>
  • Request type: POST or GET (if using chainedProxy, proxyCertificate, and clientCertificate the request is POST; otherwise it is GET)

"StopProxy"

Stop the recording proxy that is listening on the specified port.
  • URL: http://[server]:[port]/automation/StopProxy/<recordingPort>
  • Request type: GET
Note: Setting the port to 0 does not stop all open proxies. Use StopAllProxies to do this.

"StopAllProxies"

Stop all running recording proxies. This command stops all recording proxies on all ports, including those started by other users.

  • URL: http://[server]:[port]/automation/StopAllProxies
  • Request type: POST

"EncryptDastConfig"

Upload DAST.CONFIG file for encryption.
  • URL: http://[server]:[port]/automation/EncryptDastConfig
  • Request type: POST

"DownloadEncryptedDast"

Download encrypted .dast.config file (that was uploaded using the EncryptDastConfig API).
Note: When the file is downloaded, both encrypted and unencrypted .dast.config files are deleted from the proxy server.
  • URL: http://[server]:[port]/automation/DownloadEncryptedDastConfig/<uuid>
  • Request type: GET

"Traffic"

Download recorded data from the recording proxy identified by its port, as a .dast.config file.
  • URL: http://[server]:[port]/automation/Traffic/<recordingPort>
  • Request type: GET

"Certificate"

Download the self-signed Root Certificate Authority, used by the Recording Proxy, as a PEM file.
  • URL: http://[server]:[port]/automation/Certificate
  • Request type: GET

Updating the AppScan Proxy Server

Before dropping the AppScan Proxy Server and moving to a newer version, make sure to copy any configuration files you may have modified into the new folder.

If you installed the Proxy Server as a service, you must uninstall the service before updating (see Additional Service Commands), and reinstall it after wards.