{"id":34889552,"url":"https://github.com/trailofbits/mrva","last_synced_at":"2026-06-27T11:02:36.364Z","repository":{"id":331206959,"uuid":"1037996055","full_name":"trailofbits/mrva","owner":"trailofbits","description":"A terminal-first approach to CodeQL multi-repo variant analysis","archived":false,"fork":false,"pushed_at":"2026-05-19T19:23:22.000Z","size":190,"stargazers_count":14,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T08:34:48.383Z","etag":null,"topics":["codeql","variant-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trailofbits.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-14T13:01:18.000Z","updated_at":"2026-05-14T18:55:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/trailofbits/mrva","commit_stats":null,"previous_names":["trailofbits/mrva"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/trailofbits/mrva","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fmrva","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fmrva/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fmrva/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fmrva/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trailofbits","download_url":"https://codeload.github.com/trailofbits/mrva/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fmrva/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34850575,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codeql","variant-analysis"],"created_at":"2025-12-26T05:00:31.731Z","updated_at":"2026-06-27T11:02:36.353Z","avatar_url":"https://github.com/trailofbits.png","language":"Python","funding_links":[],"categories":["Tooling \u0026 Environment"],"sub_categories":["CodeQL CLI Tooling"],"readme":"# mrva\n\n`mrva` is a terminal-first approach to CodeQL [multi-repo variant analysis](https://docs.github.com/en/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-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](https://github.com/github/vscode-codeql), but instead runs as a standalone CLI tool.\n\nTable of contents:\n\n- [Installing](#installing)\n- [Using](#using)\n- [Developing](#developing)\n  - [Testing](#testing)\n  - [Linting](#linting)\n\n## Installing\n\nFirst, install `mrva` from [PyPI](https://pypi.org/project/mrva/):\n\n```bash\n$ python -m pip install mrva\n$ mrva -h\n```\n\n_Or, use your favorite Python package installer like `pipx` or `uv`._\n\n## Using\n\n`mrva` has the following command tree:\n\n- `mrva`\n  - `download`\n    - `top`\n    - `org`\n    - `repo`\n    - `query`\n    - `from-file`\n  - `analyze`\n  - `pprint`\n  - `print-ast` (experimental)\n\nUsing `mrva` generally requires three steps:\n\n1. Downloading existing CodeQL databases from the GitHub API\n1. Running CodeQL variant analyses against these databases\n1. Viewing the results\n\nFirst, ensure you have a `codeql` binary in your `$PATH` (releases [here](https://github.com/github/codeql-cli-binaries/releases)).\n\nNext, create a directory to store `mrva` data:\n\n```bash\n$ mkdir dbs/\n```\n\nThis directory will eventually contain CodeQL databases, tool configuration, SARIF results, and other information `mrva` needs to operate.\n\nUse the `mrva download` command to download CodeQL databases:\n\n```bash\n$ mrva download --token $GITHUB_TOKEN --language ruby dbs/ top --limit 100\n```\n\n\u003c!-- prettier-ignore --\u003e\n\u003e [!NOTE]\n\u003e `download` will automatically use the `$GITHUB_TOKEN` environment variable if it's available.\n\nThis 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`.\n\nUse the `mrva analyze` command to analyze the downloaded databases:\n\n```bash\n$ mrva analyze dbs/ /path/to/queries -- --rerun --threads=0\n```\n\nAny flags included after `--` are passed directly to the CodeQL binary.\n\n\u003c!-- prettier-ignore --\u003e\n\u003e [!NOTE]\n\u003e `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.\n\nUse the `mrva pprint` command to view analysis results:\n\n```bash\n$ mrva pprint dbs/\n```\n\nYou can also use the `pprint` command to print raw CodeQL SARIF results:\n\n```bash\n$ codeql database analyze \\\n    --format sarif-latest \\\n    --sarif-add-file-contents \\\n    --output output.sarif \\\n    -- db/ query.ql\n$ mrva pprint output.sarif\n```\n\nMany 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.\n\n## Developing\n\n`mrva` uses [`poetry`](https://python-poetry.org/) for dependency and configuration management.\n\nBefore proceeding, install project dependencies with the following command:\n\n```bash\n$ poetry install --with dev\n```\n\n\u003c!-- prettier-ignore --\u003e\n\u003e [!NOTE]\n\u003e 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.\n\n### Linting\n\nLint all project files with the following command:\n\n```bash\n$ poetry run pre-commit run --all-files\n```\n\n### Testing\n\nRun Python tests with the following command:\n\n```bash\n$ poetry run pytest --cov\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fmrva","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrailofbits%2Fmrva","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fmrva/lists"}