Question
What troubleshooting tools are built into the agent?
Answer
The Contrast Java agent includes built in utility programs to help with configuring and troubleshooting the agent. Run these utilities by executing the agent jar using java:
java -jar ~/Downloads/contrast-agent-3.6.10.12341.jar
*** Contrast Agent (version 3.6.10.12341)
Usage: java -jar contrast-agent-3.6.10.12341.jar <command action> [arguments]
The commands are as follows:
info - get basic info about this Contrast engine
diagnostic - diagnoses communication problems with the Contrast site
verify - verifies legality of bytecode weaved by Contrast (advanced)
properties - Displays Configuration Properties
Usage: java -jar contrast.jar properties [Options]
Options: --filter=<searchString> Filters configurations by searching paths, variables and properties
The utilities printed in the help screen are those which we are comfortable with exposing to users. In addition to these utilities, the agent includes hidden utilities for internal use only including
-
analyze-log: analyzes a given Contrast Java agent debug log and builds an Agent Metrics Format file to be visualized by the https://github.com/Contrast-Security-OSS/agent-metrics tool -
combine-logs: concatenates a directory of log files into a single file
Check TeamServer Connection Info
Use the agent's info utility to see the TeamServer connection configuration
java -jar ~/Downloads/contrast-agent-3.6.10.12341.jar info
*** Contrast Agent (version 3.6.10.12341)
Agent Configuration
===================
Reporting to: https://apptwo.contrastsecurity.com/Contrast
User ID: contrast.user@contrastsecurity.com
User Service Key: REDACTED
API-Key: wInpj9FQP43qcHg8zo5Z3df4aDu40S77
The output of info must include connection configuration. null values indicate a misconfiguration.
Use Diagnostic Utility to Check Network Connectivity
Use the agent's diagnostic utility to verify that the agent is able to route network requests to TeamServer. This is useful for checking if your TLS and proxy settings are correct. This diagnostics does not verify that the agent's authentication configuration is correct nor does it verify that the agent's TeamServer URL is actually pointing to a TeamServer service.
java -jar contrast.jar diagnostic
*** Contrast Agent (version 3.6.3.7840)
[!] Attempting to connect to the Contrast TeamServer at https://apptwo.contrastsecurity.com/Contrast (No proxy).
[!] Attempting to resolve domain: apptwo.contrastsecurity.com
Resolved domain apptwo.contrastsecurity.com to IP Address 52.200.215.12
[+] Client successfully resolved the DNS of the Contrast TeamServer. No proxy needed.
[!] Issuing HTTP request to Contrast...
Executing request...
Reading response [200]
Response size = 4209
Snippet: <!doctype html> <!--[if gt IE 8]><!--> <html class="no-js" i
[+] Client can connect directly to the Contrast TeamServer. No proxy needed.
View Configuration Properties
Use the agent's properties utility to list out all of the Configuration properties supported by this version of the agent.
java -jar ~/Downloads/contrast-agent-3.6.10.12341.jar properties
Debug Logs Analyzer
Use the agent's analyze-log utility to help make sense of all the information in a Contrast debug log. This utility works in tandem with other tools to visualize the data in the agent's debug logs. First, the analyze-log utility generates an Agent Metrics File from the debug log.
java -jar ~/Downloads/contrast-agent-3.6.10.12341.jar analyze-log ~/investigations/sup-878/multipart-spring-4-fn.log amf
*** Contrast Agent (version 3.6.10.12341)
Creating AMF, using temp dir: /var/folders/__/h22x914n5f3242pvhyg4h8880000gp/T//amfdata1578080090
Serialized 0 traces to /var/folders/__/h22x914n5f3242pvhyg4h8880000gp/T//amfdata1578080090
Top 25 Propagators
==========================
Count API
15 org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
-- REDACTED FOR BREVITY --
Top 25 Propagator Stacks
==========================
Count API
1 org.apache.catalina.connector.RequestFacade.getRequestURI(RequestFacade.java:856)
org.apache.catalina.connector.RequestFacade.getRequestURI(RequestFacade.java:856)
javax.servlet.http.HttpServlet.service(HttpServlet.java)
org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:846)
-- REDACTED FOR BREVITY --
Zipping all files from /var/folders/__/h22x914n5f3242pvhyg4h8880000gp/T//amfdata1578080090(34)
Agent metrics written to javaagent-0092476.amf
The Agent Metrics File is a zip file which contains a set of structured data in JSON format and partitioned log files. See Agent Metrics File (.amf) - Java/.NET for more details on how to use and visualize the data in this file.