CodeQL

Visit Website

Introduction

CodeQL is GitHub’s code analysis engine. It treats code as data: CodeQL extracts a relational database from your source code, then runs queries written in the QL language to find patterns such as untrusted data flowing into a SQL query. The github/codeql repository holds the standard CodeQL libraries and queries, licensed MIT, that power GitHub Advanced Security and GitHub’s other application security products.

You can use CodeQL in three main ways: GitHub code scanning (default or advanced setup in a repository), the CodeQL CLI in any CI system, and the CodeQL extension for Visual Studio Code for writing and running your own queries.

Licensing matters. The CodeQL CLI terms allow academic research, demonstrations and analysis of open-source codebases (released under an OSI-approved licence), including automated CI analysis when the open-source code is hosted on GitHub.com. Using CodeQL on private code requires a paid GitHub product licence.

In the quality loop, CodeQL is a release-gate SAST check: it runs on pull requests and on the default branch, and its alerts appear in the Security tab and as pull-request annotations. It complements dependency scanning (Dependabot, OSV-Scanner) and secret scanning.

Features

1. Semantic analysis: Data-flow and taint tracking across functions and files, not just pattern matching.
2. Standard query packs: Security and quality queries maintained by GitHub and the community in the open repository.
3. Custom queries: Write your own QL queries to encode project-specific rules or variant analysis.
4. Code scanning integration: Results show as alerts in GitHub with pull-request annotations.
5. CodeQL CLI: Create databases and run queries in other CI systems; upload SARIF results.
6. VS Code extension: Author, run and debug queries locally against databases.
7. SARIF output: Standard format that other tools and dashboards can read.
8. Multi-language: Supports major languages; see the documentation for the current list.

Pros

1. Deep analysis: Finds data-flow vulnerabilities that simple linters miss.
2. Free for open source: Public open-source repositories can use it at no cost.
3. Open queries: The query library is MIT-licensed and reviewable.
4. Native to GitHub: Low setup for GitHub-hosted projects.
5. Extensible: Variant analysis lets teams hunt for similar bugs across many repositories.

Cons

1. Private code needs a licence: Commercial use on private repositories requires a paid GitHub product.
2. Build required for some languages: Compiled languages may need a build step, which adds CI time.
3. Learning curve for QL: Writing custom queries takes practice.
4. Scan time: Large codebases can take a long time to analyse.
5. False positives: Like all SAST, results need triage.

Usage and Links (Example)

The simplest path on GitHub is code scanning default setup from the repository’s security settings. For advanced setup, a workflow uses the CodeQL action:

- uses: github/codeql-action/init@v3
  with:
    languages: javascript-typescript
- uses: github/codeql-action/analyze@v3

With the CLI in other CI systems:

codeql database create db --language=python --source-root .
codeql database analyze db --format=sarif-latest --output=results.sarif

Tips: start with the default query suite, add the extended security suite once the team is comfortable, and triage alerts weekly so they do not pile up.

Resources:

• CodeQL website
• CodeQL documentation
• GitHub repository

Pricing

CodeQL is free for academic research and for analysing open-source codebases, per the CodeQL CLI terms. Use on private code requires a paid GitHub product licence; see GitHub’s security plans for current prices.

Recommended for?

1. Open-source maintainers on GitHub wanting free, deep SAST.
2. GitHub Enterprise teams that want code scanning built into pull requests.
3. Security researchers doing variant analysis.
4. Not a fit for private code without a GitHub licence; consider Semgrep or Opengrep.

Conclusion

CodeQL is one of the most capable SAST engines available, with an open query library and tight GitHub integration.

It is free for open source and research; private repositories need a paid GitHub licence, so check terms before rolling it out.