.NET

Supported Technologies

Confirm that the tCell agent supports your .NET configuration, as shown below:

Prerequisites

• A tCell account setup
• An application created (Admin>Applications)
• Local administrator rights on the server
• Allow outbound HTTPS connections to the tCell cloud: What IPs do tCell agents connect to?
• Integrated mode application

Installation

Get the Config File

1. Click on "tCell Admin" in top navigation bar.
2. Create a new API Key.
3. Click "Download Agent".
4. Select ".NET" agent.
5. Download either the zip or the msi file as desired.
6. Click "Download Config File" to download the agent's config file (which is pre-populated with the application and key information).

Install the agent

1. Run the installer (.msi) and follow the instructions. This will install the agent and put the required files in the directory you specify. (default C:\Program Files\Rapid7, Inc\tCell .NET Agent). Consider also whether to enable OS commands and Local Files.
2. Place the tcell_agent.config file in the root folder of your application.
3. If you have more than 1 application running on the same IIS, you only need to add a configuration file and place it in the root directory of the other applications. To be able to track different applications, you should create a new application in tCell.
4. Open a command prompt as administrator and run the command iisreset to restart the IIS. Your application is now protected by tCell!

Configure an ASP.Net website with web.config

Background

Web.config is the application configuration for an ASP.Net website for .NET Framework-based sites such as webforms or MVC 4 or 5. It typically resides in the root folder of a web application, though additional web.config files can be located in subdirectories which can provide specific settings to those folders. These configuration files are loaded in a hierarchical fashion, meaning the root level is applied first and settings can be overridden by files in subdirectories -- but not all settings. With the .NET agent, we use only the root-level web.config file when searching for settings.

tCell configuration additions

Agent configuration typically uses the tcell_agent.config file found in the root of the .NET web application. Alternatively, it can use the web.config file also found in the root. The settings in these files can co-exist in the root because libtcellagent uses specific override values or ConfigFilePath settings to determine which settings to use. The settings defined in tcell_agent.config and in a tCell config section of web.config use the same key names (for the most part). Here's an example of a tCell config section in web.config:

 
1
<configuration>
2
    <configSections>
3
         <section name="tcell" type="System.Configuration.AppSettingsSection, System.Configuration, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"/>
4
    </configSections>
5
    <tcell>
6
        <add key="tcell_api_url" value="https://us.agent.tcell.insight.rapid7.com/api/v1"/>
7
        <add key="tcell_input_url" value="https://us.input.tcell.insight.rapid7.com/api/v1"/>
8
        <add key="iis_url_rewrite" value="true"/>
9
        <add key="log_level" value="DEBUG"/>
10
        <add key="log_enabled" value="true"/>
11
        <add key="allow_log_payloads" value="true"/>
12
        <add key="allow_payloads" value="true"/>
13
        <add key="app_id" value="---app id here ---"/>
14
        <add key="api_key" value="--- api key here ---"/>
15
        <add key="inspect_json_posts" value="true"/>
16
        <add key="reverse_proxy" value="true"/>
17
        <add key="reverse_proxy_ip_address_header" value="--- header value ---"/>
18
    </tcell>
19
</configuration>

This flattened key/value pair structure is similar, but not identical, to the tcell_agent.config format. The logging options in particular have a different structure.

Each key is optional. If left out, the key won't be sent to the native library, though a missing entry such as api_key or app_id when reverse_proxy is set may cause the config to fail.

Note As is standard with ASP .NET websites, updating web.config triggers application recycling to load new settings. This allows dynamic-like behavior of the stored settings.

OS Commands and Local Files

.NET agent supports both OS Command and Local Files feature support. This is done using the .NET profiling API. There is a .NET Profiling API system limitation that only one profiler can profile a program at a time. You must therefore disable existing tools that use the .NET profiling API before you can enable it for tCell agent.

If using the .msi installer to install the .NET agent, select the Code Instrumentation option during the installation process.

If running the agent installation as part of your CI/CD pipeline, use CLI arguments to install the tCell .NET agent with Code Instrumentation as follows:

msiexec.exe /i tcell-dotnetagent-2.2.3.0.msi ADDLOCAL=ALL /qn

Prevent IIS recycling on IIS 7.5 or later

If you’re running IIS 7.5 or later, IIS will recycle your application if it's idle for 20 minutes or longer. When this happens, the agent will unload, stop running, and will show as offline in the tCell console. If a request comes in, the agent will start again.

If you don't want IIS to recycle the application when it's idle, you can change your application’s Start Mode and Idle Timeout for your application pool. Note that IIS will still recycle based on its regular recycle schedule. By default, this is set to 1740 minutes, or 29 hours.

To change your Start Mode and Idle Timeout:

1. Go to advanced settings for your application pool by right clicking on you application pool and selecting advanced settings
2. Set the Start Mode to AlwaysRunning, which is found under “General”
3. Set the Idle Timeout (in minutes) to 0. This can be found under Process Model.

Add multiple apps to the IIS Server

For each app that you add to run on the IIS Server, install the .NET agent, perform an IIS reset, and recycle the application pool.

Troubleshooting

Installer

For .Net agent version 2.2.3 and above, there is an installer log located at C:\ProgramData\Rapid7, inc\tCell .Net Agent\InstallLog\ that can be used for debugging.

Log directory

The default log directory for .Net Agent version 2.2.0 and lower is [ApplicationDirectory]\Tcell\Logs

The default log directory for .Net Agent version 2.2.1 and greater is C:\ProgramData\Rapid7, inc\tCell .NET Agent\[ApplicationName]\Logs , if that fails it will fallback to the 2.2.0 directory.

Startup errors

To enable startup error logging set the TCELL_AGENT_STARTUP_ERROR_LOGGING environment variable to true or specify a valid path. This flag will create a file called tcell_critical_error.log in the root folder of the application running or at the path specified if there's an error at startup.

Note: this will write all startup errors for all applications to this file, so if there are a large number of applications and large number of errors, one may have to scan throughout the file to find application specific error messages.

Log levels

Valid log levels are:

• ERROR
• WARN
• INFO (default)
• DEBUG
• TRACE

The preceding list indicates the precedence among the levels, from top to bottom. When you enable a log level, the higher log levels are also enabled. For example, if you enable WARN, then ERROR is also enabled.

When a log file becomes full, logging continues in a new log file.

Change log level

To change via environment variables, use the TCELL_AGENT_LOG_LEVEL and TCELL_AGENT_LOG_ENABLED environment variables.

Alternatively, you can specify the log level in the tcell_agent.config file by adding a block like:

server_agent.config snippet
1
"logging_options": {
2
        "enabled": true,            // Enable/Disable logging
3
        "level": "DEBUG"            // DEBUG, INFO, WARN, ERROR
4
 }

See tcell/tcell_agent.config.template for an example.

Event Viewer

If no logs appear in any directory, check the event viewer and look for Errors under application.