Configuring and Using the Proxy Server

Configuring the proxy server connection

About this task

After making any changes to the settings file, you must restart the server.

Note: Settings.json is a JSON file and so certain characters such as for example “ (double quotes) and \ (backslash) must be "escaped," so “ becomes \” and \ becomes \\

Important: Do not change the internalConfiguration settings in this file.

Procedure

For a secure (SSL) connection to the Proxy Server: Configure your own PEM or PKCS12 certificate:

PEM:
- A PEM certificate requires two files (full paths)
- 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 “ symbol is escaped)
PKCS12:
1. In the command line, run:
```
.\Java\jre\bin\java.exe -jar .\DastProxy.jar -sc "C:\Path\to\certificate.pfx"
```
2. When prompted, enter the certificate’s password and press Enter.

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

Using the proxy server

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

Procedure

If the site is secured (HTTPS), you can avoid SSL warnings by doing this:
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 needed (depending on where the traffic is sent from).
For more details see Configure the Root Certificate, below.
To start a proxy, 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.
Note: If traffic is not encrypted (see sub-section below), you can encrypt the traffic file (DAST.CONFIG) for an individual recording using:
```
Query param Example:
/StartProxy/<recordingPort>?encrypted=true
```
Send your traffic via the defined recording port.
When done, send the REST API request: StopProxy (note that StopProxy/0 is not allowed).
Download the recorded traffic file by sending the REST API request: Traffic

The traffic file has extension .dast.config
Note: When you download the traffic file, the traffic data is deleted from the Proxy Server.

You can use the DAST.CONFIG file to update the Explore data of an existing job, using the ASoC REST API. You can

Encrypt DAST.CONFIG file

You can use the Proxy Sever REST API to upload a DAST.CONFIG file for encryption, and then download the encrypted file.

To upload your file for encryption, use: EncryptDastConfig
To download the encrypted file, use: DownloadEncryptedDastConfig

See Proxy Server API commands for details.

Encrypt traffic

By default, traffic (DAST.CONFIG) files are not encrypted. To configure the server to encrypt all traffic, change the "encryptDastConfig" key in the Settings.json file, found in the installation folder, to true.

Set proxy inactivity timeout

If a 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 in the Settings.json file, saved in the installation folder.

Chained proxy

If a 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 in the Settings.json file, saved in the installation folder.

Configure the Root Certificate

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

By default, the 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 do one of the following:

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 of the Proxy Server on the AppScan Presence machine. Default location:
```
<AppScanPresenceInstallFolder>\Automation
```
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: Since the certificate will be saved on the proxy server, it is recommended that you use a dedicated test certificate.

Note: Our demo script for this workflow, ProxyServerDemoScript.py, can be found in (default location);

<AppScanPresenceInstallFolder>\Automation