Advanced configuration and functionality

Agent instrumentation settings

In order to protect applications, the agent instrument hooks into the application. By default, the hooks are inserted whether the protection settings are enabled or disabled. There are optional configuration settings for disabling hooks or to enable hooks that are disabled by default.

These settings should not be changed from their default values, unless instructed by Trend Micro technical support.

Configuration key Environment variable Description
agent_enabled TREND_AP_AGENT_ENABLED Enables or disables the agent. Possible values are: true or false. Default value: true.
plugins_enabled TREND_AP_PLUGINS_ENABLED Activates the listed plugins with the existing list of plugins.
plugins_disabled TREND_AP_PLUGINS_DISABLED Deactivates the listed plugin, preventing the hooking from taking place. For example "sqli".

The PHP Agent includes a plugin for disabling the Illegal File Access security control on the PHP include expression. The include expression accesses, loads and evaluates the specified file. When the file is accessed, the Illegal File Access security control is applied. In some PHP applications, there can be a large number of files being included, triggering many security checks and adding latency on the request. In the case where the include is not an attack vector, the Illegal File Access security control can be disabled for the include expression. The plugin name is: file_io_include

Network proxy and connectivity

The agent supports outbound connection to the Application Security backend to be routed through a proxy. The configuration setting can be used when connections from the agent needs to be tunneled through an outbound proxy, for example on-premise from a data center.

Configuration key Environment variable Description
http_proxy_host TREND_AP_HTTP_PROXY_HOST Proxy host name or IP address through which the agent needs to connect.
http_proxy_port TREND_AP_HTTP_PROXY_PORT Proxy port through which the agent needs to connect. The default value is 3128.
http_proxy_user TREND_AP_HTTP_PROXY_USER Proxy user name, if authentication is required.
http_proxy_password TREND_AP_HTTP_PROXY_PASSWORD Proxy password, if authentication is required.
ready_timeout TREND_AP_READY_TIMEOUT The amount of time for the agent to wait, in seconds, before accepting requests. The default value is 0.
transaction_finish_timeout TREND_AP_TRANSACTION_FINISH_TIMEOUT The amount of time the agent can wait, in seconds, for completing the transaction processing. The default value is 0.
hello_url TREND_AP_HELLO_URL The endpoint where the agent connects to get its configuration, updates and sends security events. By default, the agents connect to the us-1 region's servers. For accounts in the us-1 region this key doesn't need to be set. For accounts in other regions, the hello_url needs to be set to the region's agent url. Note also that multi-region aware agents will be released, i.e. for those agents, the hello_url doesn't need to be set, the agents can discover automatically which region to connect to. Refer to Configuration for Multi-Regions for more details, including which versions of agents are multi-region aware.

Application Security also supports accessing the X-Forwarded-For header. This header contains a list of IP addresses in the proxy chain that was traversed by a request. (See Note below.) To select which IP address to use in the header's list of IPs, use the x_forwarded_for_lb_count configuration key. This key counts from the end of the list.

Configuration key Environment variable Description
x_forwarded_for_lb_count TREND_AP_X_FORWARDED_FOR_LB_COUNT Selects which IP to use in the X-Forwarded-For list, starting the count from the last item in the list. The default value is 1.

If you set the key's value to 1, you are specifying the last IP address in the list--from the sample list below, 112.114.120.50.

If you set the key's value to 2, you are specifying the second-last IP address in the list--from the sample list below, 112.114.120.49.

X-Forwarded-For: 82.101.97.108, 112.114.120.49, 112.114.120.50

If no value is specified, the default value is 1 (to handle the common case for a Platform as a Service [PaaS] environment).

In a one-proxy configuration, the single proxy will put the real client's IP address in the `X-Forwarded-For` header:
X-Forwarded-For: real_client_IP
If a two-proxy configuration, the IP for the first proxy will appear at the end of the header's list:
X-Forwarded-For: real_client_IP, first_proxy_IP

Security events tags

In some cases, you might like to add contextual information or metadata to security events generated by an agent. For example, a group of applications or Lambda functions might share a set of security properties, however you might like to identify which specific application generated the security events. For that purpose, an agent configuration setting can be used to set key value pair "tags" that are included in the event details that are displayed in the dashboard.

Configuration key Environment variable Description
tags TREND_AP_TAGS List of comma separated key value pairs. For example: tags="tag1=value1, tag2=value2"

Fail Closed behaviour

The agent's default behaviour on failure is to Fail Open. The Fail Open default behaviour means that when the agent encounters a failure to process a request, the agent lets the request continue being processed by the application. The agent fails open to avoid affecting the application's request processing, when it cannot execute the security processing on requests. For example, if the agent is not initialized and ready to execute the security algorithms, by default the agent would let the request continue being processed by the application.

In some cases though, it is desirable for the agent to report when it cannot execute the security algorithms on a request, rather than letting the request continue being processed. If the agent is not yet initialized and ready and a request is received by the application, the agent generates an AgentError when running in Fail Closed mode, essentially halting the request processing but allowing the application to catch the AgentError and perform recovery actions as necessary.

In order to enable the Fail Closed behaviour, the following configuration must be set in the agent configuration:

Configuration key Environment variable Description
fail_closed TREND_AP_FAIL_CLOSED true or false, with default value false. When set to true, the agent raises the error AgentError when it is unabled to execute security algorithms on a request

In order for the application to get the error from the agent, the application needs to catch catch the error AgentError.

Catching the error AgentError with Java Agent:

In the context of the Java agent, the AgentError class can be found in package: com.trend.app_protect.

For the Java Agent, the agent jar file needs to be in the application classpath in order to import the AgentError Java class.

The AgentError can be raised at the agent initialization, when Fail Closed is enabled. The AgentError should be caught at an early stage of the application. For example for a Java application built on Tomcat, it can be achieved by implementing a custom Valve to handle the AgentError.

package com.sample.failclosed;

import com.trend.app_protect.AgentError;
import org.apache.catalina.Valve;
import org.apache.catalina.connector.Request;
import org.apache.catalina.connector.Response;
import org.apache.catalina.valves.ValveBase;
import javax.servlet.ServletException;
import java.io.IOException;


public class AgentHandlerValve extends ValveBase {
    @Override
    public void invoke(Request request, Response response) throws IOException, ServletException {
        Valve next = getNext();
        if (null == next) {
            return;
        }
        try {
            next.invoke(request, response);
        } catch (AgentError e) {
            // Add application specific error handling  when the AgentError is raised
            // For example it could be to get the headers and body
            // from the request and complete a fallback action
            // Or perhaps redirect to a given destination
            ...
        }
    }
}

Catching the error AgentError with Python Agent:

In the context of the Python agent, the AgentError class can be found in package trend_app_protect.exceptions.

When the configuration option fail_closed is enabled, the AgentError can be raised at the agent initialization. The AgentError should be caught at an early stage of the application. For example:

from flask import Flask
from trend_app_protect.exceptions import AgentError
from werkzeug.wsgi import LimitedStream

def fail_closed_middleware(original_app):

    def wsgi_app(environ, start_response):
        stream = LimitedStream(environ["wsgi.input"],
                               int(environ.get("CONTENT_LENGTH") or 0))
        environ["wsgi.input"] = stream

        try:
            return original_app(environ, start_response)
        except AgentError as e:
            stream.exhaust()
            start_response(str(403), [])
            return([repr(e).encode("utf-8")])

    return wsgi_app

def create_app(name = __name__):
    app = Flask(name)

    ... # Add application initilization code here

    app.wsgi_app = fail_closed_middleware(app.wsgi_app)

    return app

if __name__ == '__main__':
    create_app(__name__).run()

The setting has no effect on agent versions that don't support the Fail Closed functionality. Fail Closed is currently supported on the following agents:

Agent Platform Agent Version
Java Agent 4.3.5 and above
Python Agent 4.6.2 and above