This repository's purpose is to show how to model a Python library using CodeQL. In this repository, we model the sarge Python library. We chose sarge because:

1. Sarge is currently not in CodeQL's list of supported Python libraries.
2. Sarge wraps subprocess and as such it can create security threats, if used incorrectly.

We recommend installing the vscode CodeQL extension and to develop rules in the codeql-queries directory. If you have installed codeql by unpacking the codeql-bundle and made the codeql binary available in your PATH, you should have support for navigating the CodeQL standard library from an editor launched in this repository.

To test vulnerabilities found by codeql on this codebase, the workflow is the following:

1. Call ./create-codeql-db.sh. This creates a codeql-db-GIT_HASH directory and links the codeql-db directory to it.
2. Call ./run-codeql-analysis.sh. This call codeql on the database codeql-db and then calls sarif to present the results in text format. This is handy to locally test on the CLI (as opposed to launching queries within vscode, which can be flaky).

You need to create the database with ./create-codeql-db.sh as above, but then to test a single query you are currently developing (say codeql-queries/GetSargeRunSinks.ql), do as follows:

./run-codeql-analysis.sh ./codeql-queries/GetSargeRunSinks.ql

When you change your query, unless you've changed the Python code in app, you don't need to rebuild the database.

To observe the vulnerabiities, you need to setup this project's Python code, as detailed below.

This project uses poetry for provisioning dependencies and tooling.

We provide a .envrc file to enter the development shell automatically (leveraging direnv). If you don't use that, please refer to poetry's documentation.

Run the Flask app with:

flask --app src/sarge_security/app.py --debug run

The --debug flag enables hot reloading of changes.

Depending on the kind of vulnerability, you will observe it in the terminal executing flask or in the webpage's content.