top of page

Installation Guide for ThreatView in Magento/Adobe Commerce Cloud Environments

  • Benjamin Hosack
  • May 6
  • 8 min read

Overview


This guide provides step-by-step instructions for installing the ThreatView agent (threatviewd) in Magento/Adobe Commerce Cloud environments via the command line. The guide also includes configuring cron jobs to run the agent as a daemon in non-root environments.


The ThreatView agent plays a critical role in ensuring the security of your Magento environment by performing essential tasks such as:


  • File Integrity Monitoring (FIM)

  • Malware Scanning

  • Database Scanning

  • Payment Card Data Monitoring

  • Login Monitoring



By default, the agent conducts a daily File Integrity Monitoring scan. If a threat is detected, and the user opts to quarantine the affected file, the agent will move it into quarantine to prevent further compromise. The installation and configuration steps outlined ensure the agent runs smoothly, providing continuous protection for your environment.


Steps for Installation


1. Set Up Environment Variables


Begin by setting up the necessary environment variables for the installation process:


mkdir -p /mnt/shared/$LOGNAME

This command creates a directory under /mnt/shared/ for the user’s environment. Replace $LOGNAME with your username. Next, configure the environment variables:


export HOME=/mnt/shared/$LOGNAME
export NONROOT_INSTALL=1

HOME sets the environment variable to the directory /mnt/shared/$LOGNAME. This essentially means the agent will treat this directory as the "home" for the user running the process.


NONROOT_INSTALL=1 signals that the installation will be done by a non-root user, which is standard for cloud environments with restricted root access.



2. Create an Agent. Run the Agent Installation Command



a. Create an agent.


  • Navigate to the “AGENT ADMINISTRATION” section.

  • Then on the Agent Administration page, you’ll find a blue + New Agent button on the top right corner.

  • Once you click on it, the Agent Configuration wizard will appear, then select the options that most closely match your current application setup.

  • Click Register Agent.


A command line will be generated to run on the backend server for the new Agent deployment. This will show a small black window with the original installation command displayed. There will be a small button to the lower right labelled “Copy”. Clicking on that “Copy” button will copy the installation command to your browser’s clipboard. 



b. Obtain the installation command line after the agent has been created.



  • Under Agent Configuration, click "Edit". 

  • Then select “Review Agent Installation Command”.  

  • This will open a small black window displaying the installation command. 

  • Clicking on the “Copy” button will copy the command to your browser’s clipboard.

Here is it may look like for common Linux servers:



3. Run the Agent Installation Command



At this stage you would need to log into your website, with a terminal emulator - most people use Secure Shell (ssh), if you’re on a Windows machine, you may know the command as “Putty”. From that point you should be able to paste the command you’ve copied into your clipboard, into this normal terminal window to deploy the new agent. 


This command will download the agent configured for your application. Once running, the agent will communicate with the ThreatView portal and will be responsible for executing internal assessments on the backend server.


During the installation, the agent will automatically detect the environment and install the necessary dependencies. The installation process will output a log with real-time updates, which is essential for troubleshooting any issues.



Important: If the installation fails at any point, review the log carefully. Capture a screenshot or save the log file to help diagnose any issues.




4. Capture the Cron Job Command



If the installation process fails to automatically add the cron job, you will see the following error and warning messages:


[ - ] Error: It appears that crontab cannot be used by the current user on this system.
[ - ] Warning: ThreatView installation is complete but could not be configured to run automatically as the current user does not appear to be able to add a cron entry.

This typically occurs when the user does not have permission to add cron jobs. If this happens, you will need to manually add the cron job as instructed on the following installation log message:


Please ask your hosting provider or server administrator to add the following crontab entry:
/2 *** /mnt/shared/$LOGNAME/.threatview/bin/threatviewd -f /mnt/shared/$LOGNAME/.threatview/etc/config.toml -l /mnt/shared/$LOGNAME/.threatview/run/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.lock

5. Configure the Cron Job


a. Add Cron Command to .magento.app.yaml


By default, Magento sets cron jobs to run every minute (* ). For example, setting /2 * will execute the cron job every 2 minutes. Adjusting this schedule may impact task timing. It’s generally recommended to keep default settings. If needed, you can modify it with crontab -r or set it up with bin/magento cron:run.


To configure the cron job, you must modify the .magento.app.yaml file to include the cron job command.


  • Open the .magento.app.yaml file in your preferred text editor.

  • Add the cron job command that was generated during installation to the file.


Crons:
- /2 *** /mnt/shared/$LOGNAME/.threatview/bin/threatviewd -f /mnt/shared/$LOGNAME/.threatview/etc/config.toml -l /mnt/shared/$LOGNAME/.threatview/run/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.lock

Make sure to:


  • Use correct formatting in the YAML file. Be cautious of line breaks or automatic text wrapping in some text editors.


  • Use standard quotes (" and ') rather than typographic quotes (“ and ”), which may be introduced by certain text editors.



Logs for Magento's cron jobs can be checked within your environment or by looking at the Magento Cloud logs. Ensure the agent is running correctly by monitoring its logs or output. For example, if your agent generates logs, check those for any issues.


tail -f /var/log/cron.log

b. Workaround for Cron Execution in Restricted Environments

If your environment restricts the execution of binary files via cron jobs (common in certain hosting platforms), create a wrapper script (e.g., cron_wrapper.sh) that contains the cron job command:

Create a new shell script:

nano /mnt/shared/$LOGNAME/cron_wrapper.sh

Add the cron command to the script:


#!/bin/bash
/mnt/shared/$LOGNAME/.threatview/bin/threatviewd -f /mnt/shared/$LOGNAME/.threatview/etc/config.toml -l /mnt/shared/$LOGNAME/.threatview/run/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.lock

Make the script executable:


chmod +x /mnt/shared/$LOGNAME/cron_wrapper.sh

Modify the .magento.app.yaml file to reference the new script:


  crons:
- "*/2   /mnt/shared/$LOGNAME/cron_wrapper.sh"

6. Reference Official Documentation



For more details about configuring cron jobs within Magento Commerce Cloud environments, refer to the official Adobe documentation on the Cron Property in .magento.app.yaml.




7. Agent Document Root Update


  • Navigate to the “AGENT ADMINISTRATION” section.

  • On the Agent Administration page, click “Edit”.

  • Then select “View - Set Document Root”

  • Click on “Detect”.



The agent will attempt to automatically retrieve the document root for your site, which in some cases multiple document roots. Please choose the most appropriate one.



If the agent is unable to retrieve the document root, an error message will appear in red, as shown below:



Then it is required to update it Manually:


In order to operate effectively, the ThreatView Agent needs to understand the location of the website document root. The document root is the location on a web server where the web sites pages (documents) are stored and served from. 




8. Agent Troubleshoot when Offline



For installations with non-root privileges


We recommend reviewing the crontab file to check if the agent is scheduled there. The cron job is configured to run every two minutes and can help prevent issues caused by hosting providers' "reaper" services, which may terminate long-running processes.



For installations with root privileges


Use the following commands to check the status of the agent service:


systemctl status threatviewd

If the service is running but encounters errors, try stopping and restarting the service.


systemctl restart threatviewd

Whitelisting ThreatView IP addresses


If the agent remains offline after running the commands or reviewing the crontab files, whitelisting our IP addresses on your web server may help resolve the issue. You can find the list of our IP addresses here.


9. Database Monitoring Setup


To enable Database Monitoring on the portal, follow these steps:

  • Navigate to the “Database Monitoring” section.

  • Click on the “Databse Icon”.

  • In the Configuration section, toggle the switch to “Enable Database Monitoring” on the selected site.

  • Once enabled, click on “Connect”.

  • ThreatView will attempt to automatically configure the database access.


If the message below appears, a form will be provided to manually enter the database access details. Once entered, click the "Connect" button to test the configuration.




Once a new database connection is established, a green dot will appear, and when hovered over, it will display the message “Connection is enabled and active”. To view the available databases for each connection, click on the database icon. From there, you can set the monitoring settings by toggling the “Monitored” option on or off.



10. Uptime Monitoring Setup


To enable Uptime Monitoring on the portal, follow these steps:

  • Navigate to the “Uptime Monitoring” section.

  • Click on the “world icon” to activate the available options..


Available Monitoring Options:


  • Ping: With the PING option, the target site is resolved from the domain name and an ICMP ping probe is sent by ThreatView. If the probe is unsuccessful it is repeated a maximum of 3 times before a failure status is reported.


  • DNS: The target site is resolved and the address returned is checked against an optional list of acceptable IP address ranges. The check is successful if the resolution succeedes and the returned IP is valid, not private and is in the list of allowed ranges (if configured).


  • HTTP: The target site is issued a HTTP GET request to the root page. If the request returns success code the site is considered up and the operation successful. 3xx redirect status responses are followed up to a maximum of 10 redirects. The client can optionally configure a regular expression (regex) to be used to validate that the page contents is returned as expected (this may be necessary to deal with sites tha return 4xx or 5xx response pages with a 200 HTTP status code).


By selecting the appropriate monitoring option, you can keep track of your website's uptime with precision and reliability.

Additionally, if the site is blocked from access outside the country, it may impact both Uptime Monitoring results and the external assessment, as indicated by the "Blocked" status. Whitelisting our IP addresses on your backend server or Cloudflare will likely resolve the issue. You can find the list of our IP addresses here.



11. Checkout Monitoring Setup


To enable Checkout Monitoring on the portal, follow these steps:

  • Navigate to the “Checkout Monitoring” section.

  • Click on the “Trolley Icon”.

  • Switch on the “Enable Checkout Monitoring on the selected site”.

Once Checkout Monitoring is enabled, you will need to configure the CSP report-only policy on the response header. You’ll see examples of configurations, choose one that best suits your infrastructure. 

If you've already implemented CSP or CSP report-only policy, you can include the following report-uri directive:

Setting the Content-Security-Policy-Report-Only Header


You can configure the Content-Security-Policy-Report-Only header on both Nginx and Apache servers.

  • For Apache: You can set the header in either the .htaccess file or directly in the Apache configuration file (typically httpd.conf or the relevant site configuration file).


  • For Nginx: You can set the header by modifying the server block configuration in the Nginx configuration file, usually located at /etc/nginx/nginx.conf.



Recommend policy:  default-src * 'unsafe-inline' 'unsafe-eval';  style-src 'unsafe-inline';  script-src 'none' 'report-sample';  connect-src 'none';  form-action 'none';  frame-src 'none';  worker-src 'none';  frame-ancestors 'none';  upgrade-insecure-requests;  block-all-mixed-content; report-uri https://csp.threatview.app/report;



Once you've added the necessary header to either server, make sure to test the header using browser developer tools to ensure that the policy is being sent correctly and that your reports are being captured at the designated endpoint.


_____________________________________________________________________



By following these steps, you should be able to successfully install and configure the ThreatView agent in your Magento/Adobe Commerce Cloud environment. Ensure that cron jobs are properly scheduled to maintain the agent's operation and allow for scheduled scans to run as expected.

 
 
 

Comments

bottom of page