Skip to content

Python tracer getting started guide↑

This guide explains how to use the SandboxAQ Python tracer to obtain a cryptography trace from a Python application.

Prerequisites↑

Before using the Python tracer, make sure you’ve followed the installation instructions.

Tracing the application↑

Follow these steps to trace your Python application.

Add the tracer import statement↑

  1. Navigate to a directory where you have write permissions.
  2. Edit the entry point of the application you want to trace by adding the following import statement:

    import sandboxaq.tracer #noqa #isort:skip

Important

This line must be the first import statement in the application. Otherwise, traces may not capture all cryptographic calls made through the application.

Supress linters and formatters↑

Some code analysis tools, such as linters and formatters, may identify the Python tracer as an unused import and stop the program from running. This behavior is expected and can be safely ignored by quality assurance tools.

To prevent warnings from most linters, including isort, and tools that enforce coding standards such as mypy, refurb, or pyre, use the #noqa comment as shown in the previous example import statement: import sandboxaq.tracer #noqa #isort:skip. This comment instructs the linter to disregard any warnings for that specific line of code.

Note

If your quality assurance tooling continues to flag this statement as an unused import, consult its documentation to learn how to disable the check for this line of code.

Trace the application↑

Execute the following command before running your application as usual. This command adds the necessary import statement to main.py and runs the application using Python.

Note

This example assumes the entry point of the application is main.py and any quality checks for unused imports have been suppressed, as described in Supress linters and formatters.

Bash
echo 'import sandboxaq.tracer' | cat - main.py > temp && mv temp main.py
python main.py

Retrieve the trace file↑

Once you call the application, a cs-tracer/ repository will be located at the root of your project. This repository contains a compressed trace file named cs_trace_<DATE-AND-TIME>.cst.gz.

Note

If the traced application is terminated abruptly, the resulting gzip file may be missing a trailer and appear to be corrupted. However, AQtive Guard should still be able to analyze the contents of the trace.

Upload the trace and generate a report↑

Upload the trace to AQtive Guard to run an analysis and generate a report. Refer to these instructions: