By the end of this guide, you will be able to run Pysa to find bugs on most Python web servers, and view those bugs on Static Analysis Post Processor (SAPP).
This guide was tested on Ubuntu 18.04.5 LTS, macOS 10.15.7, and Ubuntu 20.04 LTS on WSL1
If you run into any issues along the way, please refer to the common issues section to help you debug
Pysa runs on Pyre, so we require the same dependencies as Pyre. You will need Python 3.7 or later, and
wheel Python packages.
Since the Python version included in Ubuntu 18.04.5 is Python 3.6.9, we will need to update Python to a newer version.
Next we need to install
wheel python packages:
- Set up the virtual environment:
- Install dependencies for your project
You can check which packages are installed in your virtual environment by looking at the files in:
If you already have dependencies installed for your project in your virtual environment, you can skip this step. If not, usually Python projects will list their dependencies in a
requirements.txt file. If your project has a
requirements.txt file, you can install dependencies by:
Installing your project dependencies in your virtual environment will allow Pysa to provide you better results, because it allows Pysa to use models that correspond to those dependencies and detect sources and sinks that might be hidden in your dependencies' code
- Install Pyre and SAPP in the virtual environment:
- Create Pyre configuration file in the project directory you want to run Pysa on:
pyre init will set up a configuration file for Pyre (
.pyre_configuration) in your project's directory. The defaults for
pyre init should cover most projects.
- Optional, but recommended - Add type annotations automatically to your project:
If your project uses Python 3.5 or later and isn't type annotated, running Pyre's type inference might improve your Pysa results. Note: this command will modify your code, but don't worry the type annotations won't affect your code at runtime if your project is running Python 3.5 or later.
- Set up SAPP with some high signal filters
Run the following command to set up SAPP and import a list of filters to help you start looking into issues once Pysa has found them:
Now that Pysa is set up to run on your project, you won't need to repeat any of the earlier steps to run Pysa on subsequent runs. You can run Pysa with
This command will run Pysa and store the results of the Pysa run into a
pysa-runs folder in your project directory. The output of Pysa runs will be used later by SAPP to help you filter and refine the results Pysa provides you.
After you have the results from your Pysa run stored in
pysa-runs, we will ingest those runs into SAPP for analysis with the following command:
We imported some filters into SAPP earlier and now that SAPP has processed your latest Pysa run, you can run the following command to spawn the server for the SAPP Web UI at http://localhost:5000:
Through SAPP's Web UI, you can view and filter the issues Pysa found by clicking on the "Filter" button. A list of filters should appear under "Saved Filters" for you to choose from. Note that unfiltered Pysa issues can be noisy by default, so it is usually preferable to browse issues via these saved filters.
We've provided you with some filters in SAPP to help you find a small subset of the bugs Pysa is able to catch. If you want to use Pysa to its full potential and find more bugs than the ones in your current Pysa run, you can learn how to write your own filters and tailor Pysa for your codebase below:
Problem: Installing my project dependencies while in my virtual environment gives me errors, because some of my project dependencies are not compatible with Python 3+.
Solution: Fortunately, you can still run Pysa and SAPP on your project, so feel free to continue with the Quickstart instructions. However, Pysa may miss some taint flows.
pip install fb-sapp or
pip install pyre-check results in
ERROR: Could not install packages due to an OSError: [Error 13] Permission denied
Solution: Likely you are not installing
pyre-check in the virtual environment we created earlier. Try running
source ~/.venvs/pysa/bin/activate before running
pip install fb-sapp or
pip install pyre-check fails, because it has multiple compilation errors like
Solution: You are missing
setuptools python package or
Problem: Attempting to create a virtual environment with
python3.8 -m venv ~/.venvs/pysa results in
The virtual environment was not created successfully because ensurepip is not available.
Solution: You are either missing
python3.8-dev package. Make sure you delete the directory created by the failed virtual environment command earlier.
pip install fb-sapp or
pip install pyre-check fails to install, because of a series of
error: invalid command 'bdist_wheel' errors
Solution: You are missing either
pyre init shows
ƛ Source directory path/to/dir does not exist. Be sure the source path is relative to the import_root.
Solution: You will need to manually update
.pyre_configuration. Refer to Pyre Global configuration section to set up
pyre analyze --no-verify command results in
ƛ Error: Could not find a pyre client.
Solution: Some shells (e.g.
zsh) require a restart to pick up updated PATH variables.
which pyre points to a path not within the virtual environment (e.g.
which pyre now points to a path in the virtual environment (e.g.
Ideally, if you have a local installation of Pyre, it would be best to remove the installation and only install Pyre in a virtual environment.
pyre analyze results in a bunch of errors and Pysa stops running
pyre analyze --no-verify to skip model validation.
pyre analyze --no-verify will freeze when parsing stubs and sources or processing functions, but the seconds runtime timer is still increasing
Solution: Unfortunately, it is likely the case that your machine doesn't have enough memory to run Pysa on projects with similar size to yours.
pyre analyze --no-verify exits with error
ƛ Uncaught exception: (Invalid_argument "~/.venvs/pysa/lib/pyre_check/typeshed/stdlib/zlib.pyi is not a directory")
Solution: Delete your virtual environment and recreate your virtual environment by following the steps in the Initial configuration section
Problem: I'm seeing a bunch of errors like
~/.venvs/pysa/lib/pyre_check/taint/filename.pysa: module.path.function_name is not part of the environment!
If you don't use the
module.path.function_name mentioned in your project, you can ignore them. Pysa ships with many taint models for code that isn't present in all projects. The errors you are seeing is Pysa informing you that Pysa hasn't found the source code for that particular function in your project or your venv.
If you do use the
module.path.function_name mentioned in your project and the package wasn't installed with
pip, you will need to add the package's path to
search_path in your
.pyre_configuration. Eventually, your
.pyre_configuration should look something like this:
Problem: Running any
sapp command results in
SyntaxError: future feature annotations is not defined
Solution: SAPP requires Python 3.7. Ensure you are running a Python version later than Python 3.7
Problem: Running any
sapp command results in a bunch of
Solution: Please ignore the
SAWarnings. They don't affect the functionality of SAPP and everything should be working as intended.
Problem: I can't connect to the Web UI and it displays an error related to SSL. The SAPP server log displays a bunch of
400 Bad Request error codes
Solution: Make sure you are visiting
http://localhost:5000 and not
Problem: If your SAPP server shows
404 Not found and the webpage shows
The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.
Solution: The SAPP Web UI will show this error when there are no issues imported during
sapp analyze. Check if Pysa has found any issues with your project and if SAPP has imported any of those issues.
Checking if Pysa found any issues - you should expect the following command return at least one line:
Checking which issues SAPP imported - you should expect the following lines to appear after running
Problem: The issues on SAPP Web UI have boxes with
No file found for filename.py, so I cannot see the source code related to the trace for my issues
Solution: Try passing the path to your project source code with
Problem: Pysa still doesn't work despite trying everything above
Solution: Ensure you are not running a nightly version of Pyre
Some shells (e.g. zsh) will require extra steps:
If you are still unable to get Pysa to run, please file an issue on pyre-check GitHub repo with some information about what OS you are running on, what error you are running into, and how to reproduce the error.