Summary
The .NET Framework and .NET Core agents ship with a diagnostic tool contrast-dotnet-diagnostic that can assist in troubleshooting common configuration issues and provides tools to gather diagnostic information that can be shared with support@contrastsecurity.com.
Locating the contrast-dotnet-diagnostic Tool
For the .NET Framework agent, contrast-dotnet-diagnostics.exe is located under the agent install directory. By default, this should be %PROGRAMFILES%\contrast\dotnet.
For the Windows .NET Core agent, contrast-dotnet-diagnostics.exe is located under <INSTALL_DIRECTORY>\diagnostics\win-x64 or <INSTALL_DIRECTORY>\sensors\diagnostics\win-x64.
For the *NIX .NET Core agent, contrast-dotnet-diagnostics.sh can be found under <INSTALL_DIRECTORY>\diagnostics\linux-x64 or <INSTALL_DIRECTORY>\sensors\diagnostics\linux-x64.
Running the contrast-dotnet-diagnostic Tool
The Contrast diagnostic tool can be run from the command line. Under Windows, some options may be required to be run in an Administrator command window.
For the Contrast diagnostic tool v1.0.2, the following (case-sensitive) options are available. Each option supports additional command line switches, which can be displayed via
contrast-dotnet-diagnostics OPTION --help
| zip-logs | Creates a .zip archive of the agent's logs directory. |
Additional Command-Specific Options:
-t, --target (optional): Sets the target directory; the directory's contents will be included in the archive. defaults to the logs directory.
-o, --output (optional): the output directory for the archive. Defaults to the current directory.
more options
| validate-yaml | Parses the agent configuration (YAML) file and checks that configuration keys are valid. |
Additional Command-Specific Options:
more options
| system-info | Inspects the current machine and produces a report with information on OS, runtimes, web server, etc. |
Additional Command-Specific Options:
-o, --output (optional): The directory to write the report. Defaults to the current directory.
-q, --quiet (optional): Prevents output of the report to the console
more options
| read-config | Reads the effective configuration of currently running agent(s) |
Additional Command-Specific Options:
-p, --pid (optional): Filter applications based on process with specified process ID.
-n, --app-name (optional): Filter applications based on specified application name (supports partial match). Takes precedence over pid.
-o, --output (optional): The directory where json report(s) will be written. Defaults to current directory.
-q, --quiet (optional): Prevents output of the report to the console.
-s, --skip-file (optional): When specified, json report will not be written to disk.
more options
| profile-perf |
Downloads and uses JetBrains' dotTrace to create a performance snapshot.
|
Additional Command-Specific Options:
-i, --iis (required unless -e, --exe is used): Restart IIS and create performance snapshot of next web application started (Windows only).
-o, --output (optional): Specify name of the performance snapshot file.
-e, --exe (required unless -i, --iis is used): Start specified executable and create performance snapshot. IIS flag takes precedence is both are used..
-r, --args (optional): Arguments to pass tp specified executable.
-t, --timeout (optional - Default:300000 - 5 minutes): Time in milliseconds allowed for performance profiling session.
-n, --download-timeout (optional - Default:120000 - 2 minutes): Time in milliseconds to wait for download of dotTrace.
-v, --verbose (optional): Enables verbose output.
more options
| memory-usage | Displays the memory usage that Contrast Sensors are responsible for. If inspecting a previously generated dump file created with the create-dump option (see below), that dump must be WithHeap or Full. |
Additional Command-Specific Options:
-p, --pid (if no dump-file/dac-file specified): ID of the process to inspect.
-d, --dump-file (if no pid specified): Path to the Memory Dump to inspect (must have been created using WithHeap or Full).
--dac-file (if no pid specified): Path to the DAC file that matches the memory dump (see https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-symbol).
-s, --summary (optional): Only calculate the high-level info (Heap sizes, Size of live/unreachable objects but not full/slower "retained Bytes" analysis).
-v, --verbose (optional): Enables verbose output during iunspection
more options
| list-agents | List all running agent instances |
Additional Command-Specific Options:
more options
| create-script | Generates a bash, PowerShell, or launch profile with agent environment variables set. |
Additional Command-Specific Options:
-t, --type (optional) The type of script to generate. Accepted values are: {PowerShell,Bash,LaunchProfile,WebConfig}. Defaults to PowerShell
-o, --output (optional) Specify the location where the generated script should be written. Defaults to current directory.
more options
| create-dump | Creates a dump file for the given process. |
Additional Command-Specific Options:
-t, --type (optional): The type of dump to create. Accepted values are: {Normal,WithHeap,Triage,Full}. Defaults to Normal.
-p, --pid (required): The process ID of the process to dump.
-o, --output (optional): The directory where the dump file should be written. Defaults to current directory.
more options
| connect | Tests the agent's connection to Contrast. |
Additional Command-Specific Options:
more options
| deep-connect | Tests the agent's connection to Contrast with low-level validations. |
Additional Command-Specific Options:
-u, --url (optional): Sets the test URL. Must be in the format of 'http(s)://host:port'.
-i, --ignoreFailedChecks (optional): Performs all checks rather than stopping after the first failure.
more options
| config-keys | Displays the configuration keys supported by the agent. This corresponds to the configuration options documented under https://docs.contrastsecurity.com/en/-net-framework-configuration.html. |
Additional Command-Specific Options:
-f, --filter (optional): Display information for only the requested configuration key. Performs a contains match, case insensitive.
more options
| check-process | Checks that the agent has been loaded by the specified x64 process. |
Additional Command-Specific Options:
-p, --pid (required): pid of process to inspect
-v, --verbose (optional): enables verbose output of inspection (environment variables, modules, app domains, etc.)
more options
| check-access | Checks that the specified user has access to agent binaries. |
Additional Command-Specific Options:
-p, --pid (optional): A running Process ID (pid) of a process's user to check access with. If no pid is specified, the current user is used.
-t, --target (optional): The target directory to validate access against. Defaults to the automatically detected installation directory.
-z, --anonymous (optional): If set, test access of anonymous user. Ignored if pid is specified.
more options
| cert-info | Retrieves certificate information from the Contrast UI. |
Additional Command-Specific Options:
-u, --url (optional): Specify the URL to retrieve the certificate from. Otherwise the value of 'api.url' from agent configuration will be used.
more options
Note: cert-info requires access to GoDaddy and SS2.us to verify the certificates in the chain. Without this direct access, the command may fail to validate.
| version | Display the version of the contrast-dotnet-diagnostic tool. |
| help | Display the help screen. Has the same effect as launching contrast-dotnet-diagnostics without any arguments and will display a list of available options. |
Additional Options
The following additional optional options are available with all verbs listed above:
-l, --log-level: (Default: warn) Sets diagnostic output log level. Supports: error, warn, info, debug, trace, off.
-c, --yaml-path: Set the path to contrast_security.yaml file containing the agent configuration.
-a, --agent: Override diagnostics detection of agent type. Acceptable values are: {core, framework}
--help: Display the help screen.
--version: Display version information.
Example:
root@705a2b97d60e:/app/contrast/diagnostics/linux-x64# ./contrast-dotnet-diagnostics connect
2022-03-08 22:20:59.9326|INFO|NLogManager|Applying new log level 'warn' (Warn).
Diagnostics running as '.NET Core' on Linux (x64), Non-Azure.
Testing connection to Contrast ('https://apptwo.contrastsecurity.com').
Received OK from Contrast for endpoint: /Contrast/s/api/dotnet/newer/1.0.0.0. (OK)
Diagnostic successfully connected to Contrast!