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.

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.

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.

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).

X-Forwarded-For: real_client_IP

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.

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:

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

Catch 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
            ...
        }
    }
}

Catch 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: