Downloading and deploying PHP IAST agents

Use this procedure to download the AppScan Enterprise PHP IAST agent and deploy it to your application server environment (Windows, Ubuntu, or Red Hat). The PHP IAST agent monitors your running web application during runtime testing (manual or automated) and reports vulnerabilities to AppScan Enterprise.

Before you begin

  • Ensure you have AppScan Enterprise access with permissions to manage applications and IAST agents.
  • Identify the target application in AppScan Enterprise.
  • Verify you have administrative privileges on the target PHP application server (Windows, Ubuntu, or Red Hat).
  • Verify your PHP version is 8.1.0 or later.

About this task

Unlike agents for Java or .NET, the PHP agent requires manual configuration using details from a ase-config.json file included in the download package. You must configure specific environment variables on your server for the agent to connect to AppScan Enterprise.

Part 1: Download the PHP agent

Procedure

  1. Log in to the AppScan Enterprise.
  2. From the application list, navigate to the target application.
  3. Select the Application tab, then click IAST Agents.
  4. Click Create a new Agent.
  5. From the Agent type list, select the option that matches your PHP application's deployment environment:
    • PHP - Windows
    • PHP - Ubuntu
    • PHP - Red Hat
  6. In the Agent name box, enter a descriptive name for this agent instance.
  7. Click Download agent.
    The agent ZIP package downloads automatically.

Part 2: Understand the downloaded package

Procedure

  1. Locate the downloaded ZIP file.
  2. Understand its contents:
    • Agent binary:
      • Windows: hcl_agent.dll
      • Ubuntu: hcl_agent.deb
      • Red Hat: hcl_agent.rpm
    • ase-config.json: A file containing configuration details specific to this agent instance, including the accessToken and host values needed for manual server configuration.
    • License File: Contains license agreement information (e.g., HCL Master License Agreement).

Part 3: Deploy the agent (select the section for your OS)

Deploying on Windows:

Procedure

  1. Extract the contents of the downloaded agent ZIP file to a temporary location on the server.
  2. Configure PHP to load the agent extension:
    1. Find your PHP extension directory. Open a command prompt and run: php -i | findstr "extension_dir".
    2. Copy the hcl_agent.dll file (from the extracted files) into the PHP extension directory found in step 2a.
    3. Find your active php.ini configuration file. In the command prompt, run: php --ini | findstr "Loaded Configuration File".
    4. Edit the php.ini file found in step 2c using a text editor.
    5. Add the following line at the end of the file: extension=hcl_agent.dll.
    6. Save and close the php.ini file.
  3. Configure environment variables. Retrieve the accessToken and host values from the ase-config.json file.
    Note:
    • The IAST_ACCESS_TOKEN and IAST_HOST can be set locally on the server. For example, on an XAMPP server, they can be set in the httpd.conf file.
    • If other agents (Java, .NET, Node.js) are installed on the same machine, you must set the variables at the server level (Method B) instead of the system level.

    Method A: System level (default)

    Open a command prompt as Administrator and run the following commands:
    setx IAST_ACCESS_TOKEN "your_accessToken_from_ase-config.json" /M
setx IAST_HOST "your_host_from_ase-config.json" /M

    Method B: Server level (XAMPP example)

    Edit your XAMPP server's httpd.conf file and add the following lines, typically within the <Directory> section for your web root:
    SetEnv IAST_HOST "your_host_from_ase-config.json"
SetEnv IAST_ACCESS_TOKEN "your_accessToken_from_ase-config.json"
  4. Restart your web server (e.g., Apache service, IIS) to apply the changes.

Deploying on Ubuntu:

Procedure

  1. Extract the contents of the downloaded agent ZIP file to a temporary location on the server.
  2. Install the agent package:
    1. Open a terminal window.
    2. Ensure dpkg is available. If not, install it (e.g., sudo apt-get update && sudo apt-get install dpkg).
    3. Navigate (cd) to the directory containing the extracted hcl_agent.deb file.
    4. Run the installation command: sudo dpkg -i hcl_agent.deb.
      Note:
      If prompted about dependencies, you might need to run sudo apt-get install -f afterwards.
  3. Configure environment variables. Retrieve the accessToken and host values from the ase-config.json file.
    Note:
    • For the agent to function correctly with the web server service, the environment variables must be set persistently for that service. Using export in a terminal will only set them for the current session.
    • A recommended method is to add the SetEnv directives to your Apache configuration file (e.g., httpd.conf or a virtual host configuration file).

    Edit your Apache configuration file and add the following lines:

    SetEnv IAST_HOST "your_host_from_ase-config.json"
SetEnv IAST_ACCESS_TOKEN "your_accessToken_from_ase-config.json"
  4. Restart your web server (e.g., sudo service apache2 restart or sudo service nginx restart) to apply the changes.

Deploying on Red Hat:

Procedure

  1. Extract the contents of the downloaded agent ZIP file to a temporary location on the server.
  2. Install the agent package:
    1. Open a terminal window.
    2. Ensure rpm is available. If not, install it (e.g., sudo yum install rpm).
    3. Navigate (cd) to the directory containing the extracted hcl_agent.rpm file.
    4. Run the installation command: sudo rpm -ivh hcl_agent.rpm.
  3. Configure environment variables. Retrieve the accessToken and host values from the ase-config.json file.
    Note:
    • For the agent to function correctly with the web server service, the environment variables must be set persistently for that service. Using export in a terminal will only set them for the current session.
    • A recommended method is to add the SetEnv directives to your Apache configuration file (e.g., httpd.conf or a virtual host configuration file).

    Edit your Apache configuration file and add the following lines:

    SetEnv IAST_HOST "your_host_from_ase-config.json"
SetEnv IAST_ACCESS_TOKEN "your_accessToken_from_ase-config.json"
  4. Restart your web server (e.g., sudo systemctl restart httpd or sudo systemctl restart nginx) to apply the changes.

Results

The PHP IAST agent is installed and configured on your application server. After the web server restarts, the agent attempts to connect to AppScan Enterprise using the provided environment variables.

Next Steps:

Procedure

  1. In AppScan Enterprise, navigate to Application > IAST Agents and confirm the new agent shows a "Connected" status.
  2. Run tests against your application (e.g., functional tests, manual exploration, DAST scan). The IAST agent monitors this traffic.
  3. View reported vulnerabilities in the AppScan Enterprise as the agent finds them.