Configuring the HCL AppScan Traffic Recorder

Changes you can make in the configuration file Settings.json for use with HCL AppScan Traffic Recorder

After making any changes to the settings file, you must restart the server.
Important: When upgrading, if you already have a PKCS12 certificate set in Settings.json, you must reset it.

FIPS Compliant mode

To set FIPS Compliant mode:
  1. Locate the file Settings.json in the root folder of the HCL AppScan Traffic Recorder and open it in a text editor.
  2. Locate the setting requireFips property and change its value from false to true.
  3. Save the file.

Traffic Recorder connection

  1. Configure a default port for the Traffic Recorder to Settings.json.
  2. Configure a secure (SSL) connection to the traffic recorder. You can do this using your own certificate (Method A) or a self-signed certificate (Method B).
    Method A: Configure your own PEM or PKCS12 certificate, in Settings.json:
    • A PEM certificate requires two file paths (to private.key and certificate.pem).
      • Insert the file paths to the PEM section of Settings.json.
        Note: Escaping is required for the \ character. or example, C:\\Users\\admin\\private.key.

    You must escape characters as needed both in file paths and password. For instance, a password such as abc!”123 becomes abc!\”123 (the symbol is escaped).

    1. In the command line, run:
      .\Java\bin\java.exe -jar .\DastProxy.jar -sc "C:\Path\to\certificate.pfx"
    2. When prompted, enter the certificate’s password and click 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
    Method B: If you don’t have a certificate, you must create and use a self-signed certificate. This method is less secure.
    Option A:Using OpenSSL
    OpenSSL is not included and is not required except for creating the self-signed certificate.
    1. Create the key and PEM files using the OpenSSL command:
      openssl req -new -newkey rsa:2048 -nodes -keyout private.key -x509 -days 365 -out certificate.pem
    2. Insert the file paths to the PEM section of Settings.json.
      Note: Escaping is required for the \ character. For example:
    Option B: Using Java keytool
    For NodeJS 17 and above you must use --openssl-legacy-provider node flag due to keytool limitation, see
    1. In the command line, open the Traffic Recorder root folder.
    2. Create a PKCS12 certificate file using this command:
      .\Java\bin\keytool -genkey -keyalg RSA -alias selfsigned -keystore keystore-new.p12 -storetype PKCS12 -validity 365 -keysize 2048
    3. Complete the certificate details and protect it with a password.

      The password needed in the next step.

    4. Use the generated certificate in the HCL AppScan Traffic Recorder using the command:
      .\Java\bin\java.exe -jar .\DastProxy.jar -sc "keystore-new.p12"

Root certificate

If the application you are testing uses SSL (HTTPS), the HCL AppScan Traffic Recorder 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 application.

By default, the HCL AppScan Traffic Recorder generates a unique root certificate, and no user intervention is needed. However, when browsing the application you will get SSL warnings. You can either ignore them, or do one of the following:
  • Install the certificate generated by the HCL AppScan Traffic Recorder on your machine(s):
    1. Use the REST API to download the self-signed Root Certificate Authority, used by the HCL AppScan Traffic Recorder, 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 HCL AppScan Traffic Recorder:
    1. Open a command line window and navigate to the installation folder on the traffic recorder machine.
    2. Run the following command:
      .\Java\bin\java -jar DastProxy.jar -irc [path to certificate file] -ircp [password]
      To see the complete command usage, run:
      .\Java\bin\java -jar DastProxy.jar
      Important: Since the certificate will be saved on the traffic recorder, it is recommended that you use a dedicated test certificate.
      Note: Supported certificate formats are PKCS12 (.P12, .PFX), JKS.
  • Provide your own fixed server certificate (not a root certificate) in the StartProxy command.

Set inactivity timeout

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

The default inactivity timeout for traffic recorder instances is 60 minutes. Change this value in “inactivityTimeoutInMinutes” in the Settings.json file, found 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.