Beyond the Default Queries: A Closer Look at CodeQL Community Packs

CodeQL’s strength as a semantic code analysis tool lies in its ability to treat codebases as queryable databases. The standard query set is carefully tuned for accuracy, aiming for low false positives so alerts can be acted upon directly by developers in CI/CD pipelines. However, when security engineers manually triage results, the calculus shifts: the priority becomes avoiding false negatives to ensure no potential vulnerability is missed, accepting that additional manual review will be needed to filter the noise.

To serve this latter use case, the GitHub Security Lab has been using and now formally releasing a larger set of resources. The CodeQL Community Packs are designed to supplement the standard queries, providing the tools security researchers need for deep-dive investigations and manual audits. The results from using these packs in the field are documented on the wall of fame.

Badge that says 381 vulnerabilities found with the help of CodeQL.

The packs have also proven invaluable in large, unfamiliar codebases during reviews such as those for Datahub and Home Assistant. In these scenarios, the focus is on exploration as much as detection.

Screenshot of the section 'Analyzing the code base' from a blog post about Home Assistant.

Structure and Contents of the Packs

The community packs are standard CodeQL packs that fall into three distinct categories:

  • Model packs contain extra taint-tracking sources, sinks, and summaries for libraries and frameworks not covered by the default suites.
  • Query packs house additional security and audit queries to identify potential weaknesses and improve code quality.
  • Library packs provide reusable libraries for other query packs, containing no queries themselves.

For languages like Java, C#, and Python, these packs shift the signal-to-noise ratio toward lower false negatives. Taking Java as a representative example, the available packs include:

  • Java query packs: Covering known CVEs like Log4Shell, dozens of new security queries from community researchers, and several audit-focused categories.
  • Java extension models: Defining additional remote flow sources, summaries, and sinks for hundreds of APIs.
  • Java libraries: A collection of classes and predicates used by the Java queries.
  • Library extension models: A special threat model pack that treats certain third-party library method parameters as sources of untrusted data.

Screenshot of what is included in the Java CodeQL Community Pack

A New Threat Model for Third-Party Code

The creation of library extension models stems from a fundamental gap in how SAST tools, including CodeQL, typically model untrusted data. The default assumption is that untrusted data originates from network input. This works well for analyzing a web application, but it fails when analyzing a library in isolation.

Consider Log4Shell. A SAST tool can easily spot the JNDI injection sink since it is already modeled. However, to flag the vulnerability in an application, the tool must see untrusted data flowing from a network source into a logger method. If analyzing only the Log4J library source code, the logger method arguments are not seen as untrusted by default.

To solve this, the Security Lab analyzed thousands of applications to catalog third-party APIs that receive untrusted data in real-world usage. This list, including methods like org.apache.logging.log4j.core.impl.ThrowableProxy and others such as Log4J’s AbstractLogger.error, was used to define new sources for library scans. Analyzing Log4J code with this new library source pack correctly identified that the logger method arguments were untrusted, and succeeded in detecting the JNDI injection within the library’s own source code.

Screenshot of an open issue titled 'JNDI-lookup with user-controlled name.' Beneath the title, there is a banner reading 'Speed up the remediation of this alert with Copilot Autofix for CodeQL.'

Mapping Unknown Codebases

Efficiently reviewing an unfamiliar codebase hinges on reducing the review surface to the most critical files. The GitHub Security Lab begins by mapping the codebase using exploration queries. Two types are essential to this process:

  • RemoteFlowSources.ql: Lists all points in the application where untrusted data enters from external sources.
  • HotSpots: Lists all hazardous operations—like file I/O, deserialization, or network calls—regardless of whether untrusted data demonstrably reaches them.

These queries are useful not only for producing a heat map of the code but also for identifying where the query models are lacking, indicating where additional library modeling may be needed.

For deeper manual reviews, audit queries that list all files introducing untrusted data or performing security-relevant actions have been a significant time-saver. Other audit tools include templates for building custom taint-tracking queries, exploring data paths, and library source queries for finding third-party APIs called with untrusted information.

Usage and Integration

These packs are regular CodeQL packs, so integrating them into daily work is straightforward. In GitHub code scanning, you can add the packs in your workflow by specifying a packs: option in the github/codeql-action/init@v3 step.

To include the library extension models in a standard scan:

- name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: java
          packs: githubsecuritylab/codeql-java-library-sources,githubsecuritylab/codeql-java-extensions

To run additional security queries alongside the standard settings:

- name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: java          
          queries: java
          packs: githubsecuritylab/codeql-java-queries

To leverage a combination that includes both the additional security queries and the extension models:

- name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: java          
          queries: java
          packs: githubsecuritylab/codeql-java-extensions,githubsecuritylab/codeql-java-queries

The same configuration is available when using the command-line interface.

Adding library extension models:

codeql database analyze --download <CodeQL DB> --model-packs githubsecuritylab/codeql-java-extensions --model-packs githubsecuritylab/codeql-java-library-sources codeql/java-queries --format=sarif-latest --output=scan.sarif --sarif-add-file-contents

Running the additional security query packs:

codeql database analyze --download <CodeQL DB> githubsecuritylab/codeql-java-queries --format=sarif-latest --output=scan.sarif --sarif-add-file-contents

Running both kinds of community contributions:

codeql database analyze --download db --model-packs githubsecuritylab/codeql-java-extensions githubsecuritylab/codeql-java-queries --format=sarif-latest --output=scan.sarif --sarif-add-file-contents

Fostering Community Contributions

The distinct value of these packs lies in community contributions. Sharing queries and models is vital to securing the open source ecosystem. Contributions can range from simple Model As Data (MaD) additions to existing extension files, up to entirely new queries detecting novel vulnerability classes. The project’s contribution guidelines welcome all levels of involvement.