| 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.
For the *NIX .NET Core agent, contrast-dotnet-diagnostics.sh can be found under <INSTALL_DIRECTORY>\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 require to be run in an Administrator command windows.
For the Contrast diagnostic tool v1.0.0, 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.
| 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.
| 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
| read-environment | Reports environment variables for specified x64 process(es). |
Additional Command-Specific Options:
--pid (Group: read-environment) pid of process to read environment variables
--name (Group: read-environment) name of process(es) to read environment variables
| connect | Tests the agent's connection to the Contrast UI. |
Additional Command-Specific Options:
--authenticated (optional): Sends an authenticated request to Contrast. Useful for testing validity of keys. This will create a server within the Contrast UI.
| 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.
| 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.)
| 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.
--dialog (optional): Display an OS-specific dialog with certificate information, in addition to console output. Default: false
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. |
Example:
C:\Contrast\diagnostics\win-x64>contrast-dotnet-diagnostics.exe connect --authenticated
>>> INFO Applying new log level 'Warning'.
Diagnostics running as '.NET Core' on Windows (x64), Non-Azure.
>>> ALWAYS Using yaml config file from 'C:\ProgramData\contrast\dotnet-core\contrast_security.yaml'.
Testing connection to Contrast ('https://app.contrastsecurity.com').
NOTE: This diagnostic will create a server on Contrast with the following details if one does not already exist:
Name: 'DESKTOP-19K09HA'
Path: 'C:\Contrast\diagnostics\win-x64\contrast-dotnet-diagnostics.exe'
Type: 'dotnet-core'
Version: '1.7.2.0'