.NET Agent fails to connect to Contrast UI

  • Updated


You're experiencing one or more of the following symptoms:

  • The .NET agent doesn't start successfully.
  • The Contrast Tray and/or .NET agent logs report errors when connecting to the Contrast application:

    .NET Agent Windows Service failed to start. The agent cannot connect to TeamServer at: https://app.contrastsecurity.com. 
  • Data from a server with the installed agent doesn't appear in the Contrast interface.


There can be several causes for this error but the end result is that the agent is unable to successfully communicate with the Contrast UI and is therefore unable to continue. 

If the error states:

System.Security.Authentication.AuthenticationException: The remote certificate is invalid according to the validation procedure.


System.Security.Authentication.AuthenticationException: The remote certificate is invalid because of errors in the certificate chain: PartialChain

then there is some issue with the certificate that the agent is receiving from the Contrast UI.

If the error states one of the following:

System.Net.WebException: The remote name could not be resolved
Response Code: Unauthorized
Response Code: PreconditionFailed

then there is likely a credential error in the agent's configuration file.


The following error transitioning app domains may be experienced if your application targets a .NET Framework version prior to 4.7:

Exception communicating with Contrast. Error: Error communicating with Contrast for request URL:'/Contrast/api/ng/servers/'. Exception: System.Net.Http.HttpRequestException: An error occurred while sending the request. ---> System.Exception: HttpRequestException cannot transition between app domains. Exception data was truncated at the boundary.

In the .NET Agent Sensor logs, search for TargetFramework: to confirm the version of the .NET Framework being targeted.



Certificate Issues

You can inspect the certificate by navigating to https://app.contrastsecurity.com (or the corresponding URL for your SaaS or EOP instance of the Contrast UI Server) in a browser, or by using the following PowerShell commands to write the certificate to a file named contrast.cer:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$webRequest = [Net.WebRequest]::Create("https://app.contrastsecurity.com")
try { $webRequest.GetResponse() } catch {}
$cert = $webRequest.ServicePoint.Certificate
$bytes = $cert.Export([Security.Cryptography.X509Certificates.X509ContentType]::Cert)
set-content -value $bytes -encoding byte -path "$pwd\contrast.cer"
You can then double-click the certificate file to inspect the details.
You can also use the deep-connect option in the .NET agent diagnostics utility to view the certificate.
For Contrast SaaS customers, the issuer should be GlobalSign. For EOP customers, the issuer should match the CA who signed the server certificate.  If the issuer is another party then it is likely that a device or software (such as a proxy or VPN) is inspecting SSL traffic between the agent and server and modifying the certificate.

Option One - Obtain an exception

Contact the administrators of the proxy or VPN to see if a bypass can be added for this application server.

Option Two - Trust the certificate

If you have verified that the certificate is valid in your organization, you can trust the certificate permanently.

On Windows, double-click the certificate to open it and select "Install Certificate...".  Follow the wizard prompts to install the certificate to the Trusted Root Certification Authorities certificate store for the Local Machine.

On Linux, the certificate must be in PEM format with the extension .crt - you can acquire that using openssl as follows:

openssl s_client -showcerts -connect {Contrast UI hostname}:{port} </dev/null 2>/dev/null | openssl x509 -outform PEM > contrast.crt

And then import into the system's trust store by running the following commands as root (note that the ca-certificates package must be installed on the system for this to succeed):

cp contrast.crt /usr/local/share/ca-certificates/

Option Three - Ignore certificate exceptions

Certificate errors can be ignored by adding the following to the contrast_security.yaml file on the server:

ignore_cert_errors: true
This option is only recommended as a troubleshooting step to verify that the certificate is indeed the issue.  Using this option as a long-term workaround is at the user's own risk.

Configuration Issues

For other issues, open the .NET agent's configuration file, contrast_security.yaml, which is located in the agent's working directory (i.e., %ProgramData%\Contrast\dotnet\). Then:

  • Verify that the url value is correct. It should look similar to the following, although will vary if you have an on-premise Contrast UI install:
    url: https://app.contrastsecurity.com/Contrast
    Check the URL can be reached from a normal web browser on the server. If it can't be reached, you should review the network path and related settings between the server and the Contrast application.
  • Verify proxy settings. If a normal web browser can connect to Contrast but the agent can't, the agent might be missing the proxy settings required by your network environment. You can configure a proxy using the following settings:
    enable: true
    url: <proxy url with port and scheme>
    user: <proxy user if required>
    pass: <proxy password if required>
    auth_type: <proxy auth type if required>
  • Verify that the values of service_key and api_key are correct. If the above settings are correct, the API key used by your organization might have changed. Follow these directions to view your current API Key.

Error Transitioning app domains

Force TLS 1.2 and disable the app domain reporting behavior with the following configuration:
  tls_versions: tls12
    enable_http_client_app_domain_isolation: false


More detail on the .NET agent's configuration properties can be found here. All properties can also be set as environment variables - this is especially useful if it's not possible to store the proxy password in a configuration file.

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request