Skip to main content

Install PHP agent manually

To download, build, and install the PHP agent from a direct download, you can use the agent installer, or install manually for your distribution.

To install the PHP agent manually, install the agent package for your distribution from https://pkg.contrastsecurity.com.

For Debian

  1. Install the agent package from https://pkg.contrastsecurity.com to register it into your system:

    curl -fsSL https://pkg.contrastsecurity.com/api/gpg/key/public \
      | sudo gpg --dearmor -o /usr/share/keyrings/contrast-keyring.pgp
    
    echo "deb [signed-by=/usr/share/keyrings/contrast-keyring.pgp] https://pkg.contrastsecurity.com/debian-public/ all contrast" \
      | sudo tee -a /etc/apt/sources.list.d/contrast.list
  2. Install the agent:

    sudo apt-get update && sudo apt-get install -y contrast-php-agent

For Red Hat Package Manager (RPM)

  1. Install the agent package from https://pkg.contrastsecurity.com to register it into your system:

    sudo rpm --import https://pkg.contrastsecurity.com/api/gpg/key/public
    
    sudo tee /etc/yum.repos.d/contrast.repo <<-"EOF"
    [contrast]
    name=Contrast redhat-$releasever repo
    baseurl=https://pkg.contrastsecurity.com/rpm-public/redhat-$releasever/
    gpgcheck=0
    enabled=1
    gpgkey=https://pkg.contrastsecurity.com/api/gpg/key/public
    repo_gpgcheck=1
    EOF
  2. Install the agent:

    sudo yum install -y contrast-php-agent

    or

    sudo dnf install -y contrast-php-agent

For Amazon Linux 2023

  1. Install the agent package from https://pkg.contrastsecurity.com to register it into your system:

    sudo rpm --import https://pkg.contrastsecurity.com/api/gpg/key/public
    
    sudo tee /etc/yum.repos.d/contrast.repo <<-"EOF"
    [contrast]
    name=Contrast AL2023 repo
    baseurl=https://pkg.contrastsecurity.com/rpm-public/redhat-9/
    gpgcheck=0
    enabled=1
    gpgkey=https://pkg.contrastsecurity.com/api/gpg/key/public
    repo_gpgcheck=1
    EOF
  2. Install the agent:

    sudo yum install -y contrast-php-agent

    or

    sudo dnf install -y contrast-php-agent

For Alpine

  1. Install the agent package from https://pkg.contrastsecurity.com to register it into your system:

    wget -q -O /etc/apk/keys/contrast-security-alpinelinux.rsa.pub \
      https://pkg.contrastsecurity.com/artifactory/api/security/keypair/public/repositories/alpine-public
    
    echo "https://pkg.contrastsecurity.com/alpine-public/$(cut -d. -f1-2 /etc/alpine-release)/main" \
      | tee -a /etc/apk/repositories
  2. Install the agent:

    apk add --update contrast-php-agent

Configure PHP

The agent is a PHP extension, so PHP must load it at startup. Use one of the following methods, and then restart PHP-FPM or Apache:

  • To use contrast-php-util, run contrast-php-util enable-agent. This creates a contrast.ini file in the scan directory used by the PHP command found on your PATH.

  • To edit php.ini yourself, add the following line to the end of the php.ini file used by your application.

    extension=/usr/local/lib/contrast/php/contrast.so

    To find the file, run php-config --ini-path. If php-config is not available, run php -i | grep php.ini and read the Configuration File (php.ini) Path line. If no php.ini exists at that path, create one.

    On some systems, PHP on the command line reads a different ini file than PHP-FPM or Apache. For example, PHP-FPM on Debian and Ubuntu often reads files under /etc/php/{version}/fpm/. Make sure you change the ini file that the PHP running your application reads.

Configure the PHP agent

  1. Ensure that the necessary extensions are enabled.

    The PHP agent requires the mbstring and json extensions. Run php -m to confirm that both are listed.

    If mbstring is missing, enable it in php.ini, for example with extension=mbstring.

    The json extension is built into PHP 8.0 and later.

    extension=curl
    extension=mbstring
    extension=json
  2. Configure the PHP agent using the PHP YAML template or environment variables (if not already done).

  3. Start your application in the normal way.

Verify the agent deployment

Interact with your application as you normally would. For example, interact with your application's web interface or send API commands.

  1. In the Agent Wizard, select View agent activity to verify that your agent appears in the agents list.

  2. Verify that you see the name of your application in the applications list.

    • In Northstar, select Applications from the left navigation.

    • In Contrast, select Applications from the header.

  3. Verify that you see the name of your local server in the servers list.

    • In Northstar, select Servers from the left navigation.

    • In Contrast, select Servers from the header.

Notes

  • Library analysis and route discovery are currently performed on the first request to the application. For this reason, we expect the first request to be considerably slower than subsequent requests.

  • The agent has not been tested with third-party PHP extensions. The behavior of the agent with any other third-party extensions (including APMs, etc.) is undefined. The agent is known to be incompatible with xdebug and should not be used concurrently.

  • The agent may not work properly when preloading is enabled. Disabling preloading when using the agent is recommended.

  • By default, the agent uses the working directory of the PHP process as the top-level directory of your application. If that directory is /, the agent uses the web server's document root instead. If neither is the top-level directory of your application source, set the application.path setting.