Question
What are some common troubleshooting steps for the Python agent?
Prerequisites
Before installing the Python agent, check the system requirements outlined in https://docs.contrastsecurity.com/en/python-system-requirements.html.
In particular, verify that that a C compiler and C standard library headers are available on the system where you are installing the agent. Package names may differ across platforms but installing your platform's version of build-essential should cover most of the prerequisites.
At this time, the Python agent only supports Unix-like operating systems and does not work on Windows.
In case of problems, ensure the system is running the latest version of the agent. For a list of available versions, run pip index versions contrast-agent or pip install contrast-agent==. To get the currently installed version, run pip show contrast-agent.
Python agents prior to v5.24.0 require the agent to be added manually as middleware in the project under test. For details, see https://docs.contrastsecurity.com/en/python-middleware.html. It is recommended that, when using a newer agent, users should use the contrast-python-run command (though the middleware method is currently still supported).
Possible Problems
[1] The app does not start with the agent or the agent fails to install/run:
When installing the agent, and an error like Building wheel for contrast-agent (pyproject.toml) did not run successfully is shown, this may indicate a missing dependency. The output should have details, such as ./autogen.sh: line 2: autoheader: command not found, indicating autoheader is not installed. The exact package would depend on the platform/environment, but for Linux, it may help to install automake, build-essentails or linux-headers. The agent needs these tools to build C extensions.
If importing middleware, ensure the the Contrast middleware is the first to be called. Middlewares are called in the reverse order they are added when using add_middleware.
Some servers require certain configuration options in order to work properly with Contrast. If an application fails to get to a ready state with the agent attached, there are some properties that can be set for servers such as Gunicorn, Uvicorn and uWSGI. For details, see https://docs.contrastsecurity.com/en/python-webserver.html.
If application startup fails with a TypeError, it may be possible to bypass the error by disabling the rewriter using the following configuration option:
agent:
python:
rewrite: false
If Assess or Protect are not enabled at startup, try enabling the feature via the agent configuration yaml file, for example:
assess:
enable: true
If possible, try increasing memory/CPU resources available to the application to see if that addressed any problems.
[2] The agent does not report the the Contrast UI:
Ensure the contrast_security.yaml (or the corresponding environment values) used with the agent does provide the correct API credentials for the agent, which can be obtained from User Menu->Organization Settings->Agent.
The Contrast UI may reject the application because an archived app with the same name exists. In this case, the log should read something like “Contrast received instructions to disable itself”. To address this, ensure there is no archied app with the same name or - if there is - delete or unarchive the archived application.
The Contrast UI may reject the application because required metadata has not been provided. In this case, the log should read something like “DISABLING Contrast agent due to metadata violation”. To address this, provide the required metadata or modify the metadata settings for the organization via User Menu->Organization Settings->Applications (requires Admin access to the organization).
If a proxy is required to communicate with the Contrast UI, settings for
api:
proxy:
url: scheme://host:port
may be required
In case of a certificate problem, the log may show an error like “certificate verify failed: self signed certificate in certificate chain”. To test this, you can disable certificate validation via
api:
certificate:
ignore_cert_errors: true
[3] Performance Issues:
As a rule of thumb, do not run Assess and Protect on the same system, and do not run Assess in production as it has a significantly higher overhead than Protect. If the application performance still shows a significant impact, it may be possible to disable specific rules to improve startup performance in the Contrast UI.
There are several configuration options to help reduce the impact of the agent when running in Assess mode - see this article for detail: Python Agent Effects on Application Performance (Assess)
While DEBUG logging is generally required for troubleshooting, excessive logging will affect performance. Using the default (INFO) is recommended for normal operation.
For uWSGI, you can try to disable automatic application reloading by setting py-autoreload=0 in uwsgi.ini.
Additional Troubleshooting
If issues persist after trying these steps, please submit a ticket to our online support portal and include any errors displayed, an agent DEBUG log (see How to get logs from the Python agent), the requirements.txt and the output of pip list.