mrva

mrva is a terminal-first approach to CodeQL multi-repo variant analysis. You can download existing CodeQL databases from the GitHub API, run variant analyses, and view results all from your local machine. This tool was inspired by the VSCode CodeQL extension, but instead runs as a standalone CLI tool.

Table of contents:

• Installing
• Using
• Developing
  • Testing
  • Linting

Installing

Currently mrva must be installed from the git source. If/when it is open sourced we will upload it to PyPI.

To install:

$ git clone https://github.com/trailofbits/mrva.git
$ python -m pip install mrva/
$ mrva -h

Using

mrva has the following command tree:

• mrva
  • download
    • top
    • org
    • repo
    • query
    • from-file
  • analyze
  • pprint
  • print-ast (experimental)

Using mrva generally requires three steps:

1. Downloading existing CodeQL databases from the GitHub API
2. Running CodeQL variant analyses against these databases
3. Viewing the results

First, ensure you have a codeql binary in your $PATH (releases here).

Next, create a directory to store mrva data:

$ mkdir dbs/

This directory will eventually contain CodeQL databases, tool configuration, SARIF results, and other information mrva needs to operate.

Use the mrva download command to download CodeQL databases:

$ mrva download --token $GITHUB_TOKEN --language ruby dbs/ top --limit 100

[!NOTE] download will automatically use the $GITHUB_TOKEN environment variable if it's available.

This command will download CodeQL databases of the top 100 GitHub Ruby projects (by star count). You can download other databases by specifying a different --language, or using a different download strategy like download org or download repo.

Use the mrva analyze command to analyze the downloaded databases:

$ mrva analyze dbs/ /path/to/queries -- --rerun --threads=0

Any flags included after -- are passed directly to the CodeQL binary.

[!NOTE] mrva recommends using the --threads flag to process multiple queries within a single CodeQL analysis instead of parallelizing multiple CodeQL analyses. This prevents contention between mrva and CodeQL.

Use the mrva pprint command to view analysis results:

$ mrva pprint dbs/

You can also use the pprint command to print raw CodeQL SARIF results:

$ codeql database analyze \
    --format sarif-latest \
    --sarif-add-file-contents \
    --output output.sarif \
    -- db/ query.ql
$ mrva pprint output.sarif

Many of these commands take additional flags to modify their functionality. For example, analyze and pprint take --select and --ignore flags to filter repositories. Use the --help flag to explore all functionality provided by a given command.

Developing

mrva uses poetry for dependency and configuration management.

Before proceeding, install project dependencies with the following command:

$ poetry install --with dev

[!NOTE] When running mrva analyze in the Poetry environment you may need to pass -- to poetry run like poetry run -- mrva analyze. This prevents Poetry from getting confused about which arguments are its arguments, mrva's arguments, and codeql's arguments.

Linting

Lint all project files with the following command:

$ poetry run pre-commit run --all-files

Testing

Run Python tests with the following command:

$ poetry run pytest --cov