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 tracer’s installation instructions.

Tip

Installing the integration help tool isn’t necessary but recommended.

Tracer integration↑

There are two ways to integrate the Python tracer:

  • Use the integration help tool.
  • Add a tracer import statement.

Use the integration help tool↑

Make sure you’ve installed the integration help tool.

The tracer should automatically work as soon as the AQG_ENABLE_PYTHON_TRACER environment variable is set to true in the environment where the application is executed.

Add a tracer import statement↑

To add a 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.

Tracing the application↑

The way you trace your application depends on the integration method you used.

Trace using the integration help tool↑

Set the AQG_ENABLE_PYTHON_TRACER environment variable to true in the environment where the application is executed. This command sets AQG_ENABLE_PYTHON_TRACER and runs the application using Python.

Note

This example assumes the entry point of the application is main.py.

Bash
export AQG_ENABLE_PYTHON_TRACER=true
python main.py

Trace using a tracer import statement↑

Execute the following command before running your application. 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’ve called 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: