.NET Core

Supported Technologies

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

VersionApp ServersWeb FrameworksOSArchitectureAuthentication Frameworks
2.x
3.x
5.0
6.0
Kestral
IIS
Windows Server 2012 R2 or later
* Windows Nanoserver
Ubuntu 14+
Debian 8+
Alpine 3.7.1+
32-bit
64-bit
Login hooks only

.NET Core Support Legend

* - Windows Nanoserver does not support instrumentation, .NET Profiler API (OS Commands, LFI)

Notes on .NET Core Support

  • The OS Commands and Local File Inclusion feature will conflict with monitoring tools like New Relic and App Dynamics, which use .NET Profiling API. If you're running any of these tools, uninstall or disable them before setting up the optional Profiler for the tCell Agent.

  • Deleting the .NET log file will stop the agent from logging. A restart of the application is required.

Prerequisites

.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
    1. 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
    2. 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.

Note

As is standard with ASP.NET Core websites, updating the AppSettings.json file will trigger application recycling to load new settings. This recycling allows dynamic-like behavior of settings stored in the AppSettings.json file.

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.