Server Agent Options

Environment Variables and Config File Properties

Agent Versions

These agent versions support all of the environment variables and config file properties described in this document (Server Agent Options). Earlier agent versions may also support some variables and properties.

Details

See Configuration Conventions for the log and cache directory defaults, configuration file structure, configuration sources, configuration file path, and their priorities.

TCELL_AGENT_APP_ID

app_id

• Description - Identifies the tCell application.
• Type - string
• Required? - Y
• Example - exampleapp-L4Ihu

TCELL_AGENT_API_KEY

api_key

• Description - The Server Agent API Key, created through the tCell web UI, that grants permission to a specific tCell application.
• Type - string
• Required? - Y
• Example - abcd-efgh-hijk

TCELL_AGENT_API_URL

tcell_api_url

• Description - The URL prefix to poll for new configuration information. Should correspond to the AWS region where your tCell data is stored.
• Type - string
• Default - https://us.agent.tcell.insight.rapid7.com/api/v1
• Required - N
• Example - http://10.0.2.2:8000

All Collectors must be able to establish outbound connectivity on port 443 to *.endpoint.ingress.rapid7.com and communicate with the domains shown in the Data and Storage (S3) columns of the following table according to your geographic region. For example, for tCell subscribers that elect to store their data in Australia, Collectors must be able to communicate with the following endpoints using port 443:

• *.endpoint.ingress.rapid7.com
• au.data.insight.rapid7.com
• s3-ap-southeast-2.amazonaws.com

If you intend to deploy token-based Insight Agents through your Collectors, you also need to allow outbound connectivity from each Collector on port 443 to the endpoint that provides the agent's configuration files. Just like the Data and Storage endpoints in the previous table, you can configure your firewall rules to allow your Collectors to connect to a region-specific version of the Deployment endpoint to meet this requirement:

TCELL_AGENT_INPUT_URL

tcell_input_url

• Description - The URL prefix at which to send events.
• Type - string
• Default - https://us.input.tcell.insight.rapid7.com/api/v1
• Required - N
• Example - http://10.0.2.2:3000

TCELL_AGENT_ENABLED

enabled

• Description - When false, the agent does nothing for an application.
• Type - boolean
• Default - true
• Required - N
• Example - false

TCELL_AGENT_HOME

N/A

• Description - The absolute file path to the directory in which the agent will create log and cache directories by default, assuming no other configuration.
• Default
• Example - /etc/tcell
• Notes For the .NET, .NET Core, and IIS Web Server agents, the specified path will store the /logs and the /cache folder. It never looks for the tcell_agent.config file in this location."

TCELL_AGENT_INSTRUMENT

N/A

• Description - When false, the agent does not register instrumentation. It will still request policies.
• Type - boolean
• Default - true

TCELL_AGENT_LOG_DIR

log_dir

• Description - Directory for all logs
• Type - string
• Required - N
• Example - /var/log/tcell
• Default - $TCELL_HOME/logs

TCELL_AGENT_CONFIG

N/A

• Description - The absolute file path to the tCell agent config file
• Default
• Type - string
• Example - /etc/tcell

TCELL_AGENT_ENABLE_JSON_BODY_INSPECTION

inspect_json_posts

• Description - When true, the agent inspects request bodies for JSON and XML content
• Type - boolean
• Default - false

TCELL_AGENT_ALLOW_PAYLOADS

allow_payloads

• Description - When true, the agent includes inspected request payloads in events sent to the cloud. The payloads can match a regex (cmdi, xss, sqli, fpt, etc.) of up to 150 characters.
• Type - boolean
• Default - true
• Example - false

TCELL_AGENT_ALLOW_LOG_PAYLOADS

log_payloads

• Description - When true, the agent logs inspected request payloads in a tcell_agent_payloads.log file in the configured log directory.
• Type - boolean
• Default - true
• Required - N
• Example - true

TCELL_AGENT_HOST_IDENTIFIER

host_identifier

• Description - Agent host identifier to use. Each agent must have a different identifier. Defaults to hostname provided by the operating system.
• Type - string
• Required - N
• Default - (Defaults to OS hostname)
• Example - web-host-1

TCELL_AGENT_LOG_ENABLED

logging_options.enabled

• Description - Enables agent logging.
• Type - boolean
• Default - true

TCELL_AGENT_LOG_FILENAME

logging_options.filename

• Description - Sets the agent logging filename. By default, this is relative to the tcell directory. Can also pass an absolute path.
• Type - string
• Default - tcell.log

TCELL_AGENT_LOG_LEVEL

logging_options.level

• Description - Sets the agent logging level. Possible values are 'error', 'warn', 'info', 'debug', and 'trace'.
• Type - enumeration
• Default - info

TCELL_AGENT_LOG_DESTINATION

logging_options.destination

• Description - Specifies the type of log output.
• Type - Enumeration ('stdout', 'file', 'filenorolling'); filenorolling is the same as file, but the agent will not roll log files after they reach a certain size.
• Default - file

TCELL_AGENT_LOG_FILE_MAX_SIZE_MB

logging_options.max_file_size_mb

Description - Sets the maximum size allowed for a tCell log file (in MBs). The initial and minimum size of a log file is 1 MB. There is no maximum size limit. The size limit applies to every log file in the log file folder, which can hold a maximum of 10 log files.\n\nThe location of a log file folder depends on the agent type. For the IIS and .NET agent types, the log file folder locations depend on the configuration and the IDs of the apps that run tCell:

• IIS \nC:\\ProgramData\\Rapid7, Inc\\tCell IIS Agent\\LM\\W3SVC\\2\\ROOT\\[sub app name]\n
• .NET \nC:\\ProgramData\\Rapid7, Inc\\tCell .NET Agent\\[web app name]\\[sub app name]
• For all other agent types, the log file folder location is\n\ntcell/logs\n

TCELL_AGENT_HMAC_KEY

hmac_key

• Description - The key to use for hashing sensitive values in tCell Agent events.
• Type - string
• Default - If customizing, set it to the same value for all agents within the same application.
• Required - N

TCELL_AGENT_PASSWORD_HMAC_KEY

password_hmac_key

• Description - Key to use for hashing password values for login events related to Account Takeover.
• Type - string
• Default - N

TCELL_AGENT_CACHE_DIR

N/A

• Description - The absolute file path to the directory that holds the policy cache.
• Type - string
• Default

TCELL_AGENT_PROXY_URL

• Description - The url of the proxy that you proxy your traffic through. It should include the protocol, host and port. The proxy port for the R7 Collector is 8037.
• Required - N
• Example - http://myr7collector:8037"

TCELL_AGENT_PROXY_USERNAME

• Description - If basic authentication is enabled for the proxy, enter the username for authentication.
• Required - N
• Example - jsmith

TCELL_AGENT_PROXY_PASSWORD

• Description - If basic authentication is enabled for the proxy, enter the password for authentication.
• Required - N
• Example - T3stP@ssword3

TCELL_AGENT_REVERSE_PROXY

reverse_proxy

• Description - When true, agent assumes there is a reverse proxy forwarding traffic to the application.
• Type - boolean
• Default - true, for Apache and Nginx false.
• Required - N

TCELL_AGENT_REVERSE_PROXY_IP_ADDRESS_HEADER

reverse_proxy_ip_address_header

• Description - Header to check for a request's originating IP
• Type - string
• Default - X-Forwarded-For
• Required - N
• Example - X-Real-IP

TCELL_AGENT_MAX_HEADER_SIZE

max_csp_header_bytes

• Description - The maximum size in bytes of a response header injected by the agent. If an agent-configured header exceeds this threshold, the header will not be set. Generally this affects Content-Security-Policy (CSP) related headers set by the agent.

• Notes

  • .NET/.NET Core agents - Default header size 10240 bytes. Header cannot exceed maximum size of 32768 bytes.
  • Node.js agent - Header cannot exceed maximum size of 16384 bytes.
  • Python agent - Header cannot exceed maximum size of 16384 bytes.
  • Ruby agent - Header cannot exceed maximum size of 16384 bytes.
  • IIS Web Server - No maximum header size limit
  • Java agent - No maximum header size limit
  • nApache install - Default header size 10240 bytes; no maximum header size limit

TCELL_AGENT_MAX_ROUTES

max_routes

• Description - Limits the maximum number of routes to detect and report to the tCell service. When running in a web server environment where the number of routes may be very large such as thousands or tens of thousands, it may be preferable to prevent the agent from using excessive resources identifying and transmitting route information to the service.\nIf not specified, defaults to 10000. Minimum value is 100.
• Type - integer
• Default - 10000
• Required - N
• Example - 1000

TCELL_AGENT_ENABLE_JS_AGENT_SRI

enable_js_agent_sri

• Description - Enables Subresource Integrity (SRI) for JS Agent injection. If JS Agent is self-hosted (js_agent_url is set to a custom domain) while SRI is enabled, the custom js_agent_url value is ignored and the default js_agent_url value is used instead. To use a custom js_agent_url value, set enable_js_agent_sri to false.
• Type - boolean
• Required - N
• Example - false
• Default - true

TCELL_AGENT_JS_AGENT_API_URL

js_agent_api_base_url

• Description - The URL prefix at which to send events from the injected JS agent
• Type - string
• Required - N
• Default - https://us.agent.tcell.insight.rapid7.com/api/v1, https://us2.agent.tcell.insight.rapid7.com/api/v1, https://us3.agent.tcell.insight.rapid7.com/api/v1 https://eu.agent.tcell.insight.rapid7.com/api/v1, https://au.agent.tcell.insight.rapid7.com/api/v1

TCELL_AGENT_JS_AGENT_URL

js_agent_url

• Description - The URL at which to retrieve the JS Agent. This value is ignored if enable_js_agent_sri is set to true.
• Type - string
• Default - https://us.jsagent.tcell.insight.rapid7.com/tcellagent.min.js

TCELL_AGENT_UPDATE_POLICY

fetch_policies_from_tcell

• Description - When false, the agent does not update its policy.
• Type -- boolean
• Default - true

TCELL_AGENT_USE_NATIVE_CERTS

use_native_certs

• Description - Causes the agent to use the system TLS certificates to validate connections to the tCell API endpoints.
• Type - boolean
• Required - N
• Default - false
• Example - true

TCELL_AGENT_SERVER_HEADER_OFF

(NGINX Only)

server_header_off

• Description - When true, the agent removes any 'Server' header entries from responses to avoid leaking information.
• Type - boolean
• Default - N
• Required - N
• Example - false

TCELL_AGENT_INSPECT_MULTIPART_POSTS

(NGINX and Apache)

inspect_multipart_posts

• Description - Enables the parsing and inspection of multipart posts for webserver agents. This is all the fields of POST requests with a multipart/form-data content type, excluding file uploads. The maximum added latency per request and maximum memory allocated per request can be specified with the multipart_parser_time_budget_ms and multipart_parser_space_budget_bytes config variables respectively.
• Default - false
• Required - N
• Example - true

TCELL_AGENT_MULTIPART_PARSER_TIME_BUDGET_MS

(NGINX and Apache)

multipart_parser_time_budget_ms

• Description - The maximum amount of time in milliseconds the parser will spend processing each new post request.
• Default - 25
• Required - N
• Example - 10

TCELL_AGENT_MULTIPART_PARSER_SPACE_BUDGET_BYTES

(NGINX and Apache)

multipart_parser_space_budget_bytes

• Description - The maximum number of bytes the multipart parser will allocate per request when parsing each request.
• Default - 10000000
• Required - N
• Example - 6400

TCELL_AGENT_IIS_URL_REWRITE

(.NET Only)

iis_url_rewrite

• Description - Set this to true, if running Application Request Routing (ARR).\nWith default agent behavior, the agent could interfere with requests containing a body that are intended to be routed to another server. When true, we work around the problem by re-writing the body to the request after reading it.
• Type - boolean
• Default - false
• Required - N
• Example - true

TCELL_AGENT_BLOCK_LOG4SHELL_ENABLED

(JVM Only)

block_log4shell_enabled

• Description - If true, block all Log4J JNDI lookups.
• Type - boolean
• Default - true

TCELL_AGENT_LOG_FILE_ACCESS

(JVM Only)

log_file_access

• Description - When true, the agent logs file access to two files in the configured log directory:

  • opened_for_read.csv\
  • opened_for_write.csv

• Type - boolean

• Default - false

• Required - N

• Example - "this is a local secret"

• Notes - Should only be used for debugging as application performance may suffer.

TCELL_AGENT_PACKAGE_TRACKER_INTERVAL_MS

(JVM Only)

N/A

• Description - How often the Package Tracker should check for newly seen code sources, in milliseconds.
• Type - Number
• Default - 30000

TCELL_AGENT_TOMCAT_SPECIFIC_REDIRECTS

(JVM Only)

tomcat_specific_redirects

• Description - When true, the agent registers additional redirect instrumentation that is specific to Tomcat. Usually this is not necessary, even when using Tomcat.
• Type - boolean
• Default - false

Deprecated/Removed Environment Variables and Equivalents

Config File Properties Without Environment Variables

session_identifiers

• Description - 'Cookie', 'Header', or 'QueryString' parameters that hold a session value
• Type - SessionIdentifier Array SessionIdentifier: { \"type\": \"?\", \"name\": \"?\" }
• Default - <use the one provided by the framework>
• Required - N
• Example - [{\"type\":\"cookie\",\"name\":\"mycustomsesscookie\"}]

do_not_instrument

(JVM Only)

• Description - A list of fully qualified Java class names to exclude from instrumentation.
• Type - string array
• Default - N
• Required - N
• Example - [\"java.lang.String\", \"java.util.Map\"]

enabled_instrumentations

(Ruby and Python Only)

As of Python 1.7.2, you can disable Local File and OS Commands implementations. For more information, see Disable the Local File and OS Commands feature.

• Type - json object (hash)
• Description - Enable/Disable specific library instrumentation. This is meant to avoid conflicts when using tcell-hooks.
• Default - NULL
• Required - N
• Example - {\"enabled_instrumentations\": { \"doorkeeper\":true, \"devise\":true, \"authlogic\":true}}

Sub Option - doorkeeper

• Type - boolean
• Description - Enable/Disable doorkeeper library instrumentation.
• Default - true
• Required - N
• Example - false

Sub Option - devise

• Type - boolean
• Description - Enable/Disable devise library instrumentation.
• Default - true
• Required - N
• Example - false

Sub Option - authlogic

• Type - boolean
• Description - Enable/Disable authlogic library instrumentation.
• Default - true
• Required - N
• Example - false

Sub Option - django_auth

• Type - boolean
• Description - Enable/Disable django_auth library instrumentation.
• Default - true
• Required - N
• Example - false