.NET Core

Supported Technologies

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

Prerequisites

• A tCell account setup
• An application created (Admin>Applications)
• Allow outbound HTTPS connections to the tCell cloud: What IPs do tCell agents connect to?
• If you are running on Windows, Microsoft Visual C++ 2017 redistributable. Visual C++ 2017 redistributable can be found at https://aka.ms/vs/15/release/VC_redist.x64.exe .

.NET Core Agent can be deployed in a variety of ways, but this article describes the common case of deploying to Azure.

Step-by-step guide

• Download the tcell_agent.config configuration file

  1. Click on "tCell Admin" in top nav bar.
  2. Click "Download Agent".
  3. Select ".NET Core" agent.
  4. Select "Create New API Key" (default).
  5. Click "Download Config File" to download the agent's config file (which is pre-populated with the application and API key information).

• Install the .NET Core Agent in the existing project

  1. Navigate to the project folder in command line.
  2. Run:

  Command to install agent
  1
  dotnet add package Tcell.Agent

  3. Enable access to the tCell Agent namespace by adding using block to the class(normally in Program.cs).

     Sample Using Statements
     1
     using existingA;
     2
     using existingB;
     3
     using Tcell.Agent.AspNetCore;         // Add this in the top of the file before   
     4
                                           //class definition

  4. Enable the tCell Agent by adding UseTcellAgent to your CreateWebHostBuilder method.

Sample CreateWebHostBuilder
1
 public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
2
                WebHost.CreateDefaultBuilder(args)
3
                .UseTcellAgent(env => env.IsProduction())  // Add this line
4
                .UseStartup<Startup>();

Note: the "env => env.IsProduction" is optional but recommended. The agent does not operate in development environments.

After this, one should build and deploy in your standard way. However, make sure the tcell_agent.config is placed in the application root folder when publishing.

Configuration via environment variables

The steps above are the most common install path, providing the agent configuration data via a config file. Sometimes it is easier to configure the agent via environment variables. Note that to completely configure via environment variables one must at a minimum set TCELL_AGENT_APP_ID and TCELL_AGENT_API_KEY.

Configure an ASP.Net Core website with AppSettings.json

Background

You use the AppSettings.json file to configure an ASP.Net Core website for sites based on ASP.NET Core MVC. Though AppSettings.json files can be found in subdirectories at many levels, the .NET Core Agent uses only the AppSettings.json file in the root folder of a web application when searching for settings.

tCell configuration additions

Agent configuration typically uses the tcell_agent.config file, also located in the root of the .NET Core web application. The tcell_agent.config and AppSettings.json files can coexist there, with the AppSettings.json file serving as an alternative means for applying tCell settings.

The settings defined in tcell_agent.config can also be defined in AppSettings.json. The AppSettings.json settings have the same key names (for the most part) and are defined in a tcell config section. See the following AppSettings.json file example.

 
1
{
2
	"tcell": {
3
		"tcell_api_url": "https://us.agent.tcell.insight.rapid7.com/api/v1",
4
		"tcell_input_url": "https://us.input.tcell.insight.rapid7.com/api/v1",
5
		"js_agent_api_base_url": "https://us.agent.tcell.insight.rapid7.com/api/v1",
6
		"log_level": "DEBUG",
7
		"log_enabled": "true",
8
		"allow_log_payloads": "true",
9
		"allow_payloads": "true",
10
		"app_id": "--- app id here ---",
11
		"api_key": "--- api key here ---",
12
		"inspect_json_posts": "true",
13
		"reverse_proxy": "true",
14
		"reverse_proxy_ip_address_header": "--- header value ---"
15
	}
16
}

The settings in AppSettings.json override any other settings from the tcell_agent.config file. Any missing setting is excluded where defaults or values from other sources are used. The configuration is considered bad if app_id or api_key is left out and other application-specific configuration remains.

OS Command and Local Files support

OS Command and Local Files feature support in .NET Core agent utliize the .NET Profiling API. There is a .Net Profiling API system limitation that only one profiler can profile a program at a time. As such, if you want to enable OS Commands or Local Files feature support in .NET Core agent, first disable existing profiler based systems like New Relic for the application.

Enabling profiling for the .NET Core agent can be done either via Visual Studio or .NET Core Command Line tool.

Enabling .NET Core Extra Instrumentation via Visual Studio

Run the following command in the Visual Studio Package Manager Console.

Installation Using Visual Studio Package Manager Console
1
Install-Package Tcell.Agent.Instrumentation

Enabling .NET Core Extra Instrumentation via Command Line

Run the following command in the command line.

Installation via Command Line
1
dotnet add package Tcell.Agent.Instrumentation

The second step is to set the .NET Profiling environment variables.

.NET Core agent environment variables
1
CORECLR_ENABLE_PROFILING = 1
2
CORECLR_PROFILER = {06d0b220-00ff-45c6-9732-bfce91663987}
3
CORECLR_PROFILER_PATH = INSTRUMENTAITON_LIBRARY_FILENAME

The INSTRUMENTATION_LIBRARY_FILENAME is the name of the instrumentation library that is created during the "dotnet publish" or "dotnet build" command step. For example, if one runs dotnet publish -o /app/ -c release and this is a linux machine, the value will be "/app/Tcell.Agent.Instrumentation.so".

Troubleshooting

The best way to troubleshoot is by looking at the log files. Log files can be found in tcelllogs directory located in TCELL_AGENT_HOME path (default is your application root).

You can customize the log level in the tcell_agent.config file by adding a block such as the following:

json
1
"logging_options": {
2
    "enabled":true,
3
    "level":"INFO"
4
 }

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

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. See Log Rolling for more information.