| License Type | SaaS | On-Premise |
| Agent Mode | Assess | Protect |
| Main Product Category | .NET Agent |
| Sub Category | Troubleshooting |
Summary
The .NET Framework agent v20.8.3 and later, and the .NET Core agent v1.5.15 and later 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 required to be run in an Administrator command windows.
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:
--source (optional): Sets the source directory; the directory's contents will be included in the archive.
--dest (optional): Sets the destination directory for the archive.
--name (optional): Sets the name for the archive file.
more options
| validate-yaml | Parses the agent configuration (YAML) file and checks that configuration keys are valid. |
Additional Command-Specific Options:
--yaml-path (optional): Set the path to contrast_security.yaml file containing the agent configuration to be evaluated.
more options
| system-info | Inspects the current machine and produces a report with information on OS, runtimes, web server, etc. |
Additional Command-Specific Options:
--dest (optional): Sets the destination directory for the report.
--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:
--pid (optional): Filter applications based on process with specified process ID.
--app-id (optional): Filter applications based on specified application name (supports partial match). Takes precedence over pid.
--output (optional): The directory where json report(s) will be written. Defaults to current directory.
--quiet (optional): Prevents output of the report to the console.
--skip-file (optional): When specified, json report will not be written to disk.
more options
| memory-usage | Displays the memory usage that Contrast Sensors are responsible for by inspecting an existing dump file created with the create-dump option. |
Additional Command-Specific Options:
--dump-file (required) Path to the Memory Dump to inspect (must have been created using WithHeap or Full)
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:
--type (optional) The type of script to generate. Accepted values are: {PowerShell,Bash,LaunchProfile,WebConfig}. Defaults to PowerShell
--path (optional) Specify the location where the generated script should be written.
more options
| create-dump | Creates a dump file for the given process. |
Additional Command-Specific Options:
--type (optional) The type of dump to create. Accepted values are: {Normal,WithHeap,Triage,Full}. Defaults to Normal.
--pid (required) The process ID of the process to dump.
--path (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:
--url (optional) Sets the test URL. Must be in the format of 'http(s)://host:port'.
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:
--filter (optional): Display information for only the requested configuration key.
more options
| check-process | Checks that the agent has been loaded by specified x64 process. |
Additional Command-Specific Options:
--pid (required): pid of process to inspect
--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:
--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.
--target (optional): The target directory to validate access against. Defaults to the automatically detected installation directory.
more options
| cert-info | Retrieves certificate information from the Contrast UI. |
Additional Command-Specific Options:
--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 will display a list of available options. |
Additional Options
The following additional optional options are available with all verbs listed above:
--log-level: (Default: warn) Sets diagnostic output log level. Supports: error, warn, info, debug, trace, off.
--yaml-path: Set the path to contrast_security.yaml file containing the agent configuration.
--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!