GitHub Custom Queries: How to Build and Configure Custom CodeQL Queries with Github advanced security

IM BACK ! this time with a technical article since i’ve recently learned about CodeQl custom queries. So the goal of this article is to present a Proof of Concept (PoC) around customizing CodeQL to analyze a C++ project. This approach can be applied to any other programming language supported by GHAS.

The idea is to show, step by step, how to configure an analysis workflow, write custom QL queries, and interpret results in order to adapt vulnerability detection to the project’s context. This customization also helps optimize CodeQL execution, reducing noise and sometimes even execution time thanks to more targeted rules and paths.

We will follow these steps:

1. Create a codeql.yml workflow => To automatically analyze the code with GitHub Actions and export the results in SARIF format.
2. Configure a codeql-config.yml file => To define which paths to include or ignore, choose rule packs, and add custom queries.
3. Write custom .ql queries with metadata => Using properties like @problem.severity, @precision, @tags, and @security-severity to adjust the severity and relevance of results.
4. Use query-filters => To reduce noise, exclude low-precision rules or recommendations, and focus on critical results.
5. Test and interpret the results => By checking alerts in GitHub Security and in the exported SARIF files, to validate that the configuration and queries meet the project’s needs.

Creating the codeql.yml workflow

Create a file at .github/workflows/codeql.yml This file describes the GitHub Actions workflow that runs CodeQL. Example for a C++ project:

codeql.yml for C++

• **uses: github/codeql-action/init@v3** Initializes and configures CodeQL with the target language. Loads codeql-config.yml to know which folders to include/exclude and which queries to run.
• **uses: github/codeql-action/autobuild@v3** GitHub tries to automatically compile your project. For compiled languages (C++, C#, Java), a build is required for CodeQL to understand the code. If autobuild fails, replace with a manual build (make, cmake, mvn, dotnet build, yarn build, etc.).
• **uses: github/codeql-action/analyze@v3** Runs the CodeQL analysis with the selected queries. Results are exported to a SARIF file (containing vulnerabilities, severity, and precision).
• **uses: actions/upload-artifact@v4** Saves the SARIF file as a downloadable artifact of the workflow. You can open it in GitHub Security or import it into a third-party tool (e.g., SonarQube).

SARIF File as ann artifact ready for download

The codeql-config.yml file

This file allows you to customize what is scanned and which rules are applied. Example:

• **security-extended**: official GitHub pack with more security rules (recommended).
• **security-and-quality**: adds quality and best-practice rules in addition to extended.
• **./github/codeql/queries/test-query.ql**: custom query, e.g., detecting the unsafe use of strcpy() in C/C++.

Query filters

Query filters allow you to fine-tune results without changing the queries themselves. You can exclude or include results based on criteria like:

• problem.severity: exclude warnings to only keep errors.
• precision: ignore low-precision rules to reduce false positives.
• tags: include only certain categories (security, correctness, etc.).

search for “warning” severity in SARIF file after excluding it

search for “low” precision in SARIF file after excluding it

Understanding a CodeQL query file (.ql)

A .ql file describes a pattern to detect in the code. It’s a declarative language (inspired by SQL and logic) that queries a CodeQL database built from your source code. You can get your .ql from: https://github.com/github/codeql/blob/main/cpp/ql/src/Likely%20Bugs/Likely%20Typos/UsingStrcpyAsBoolean.ql

Example: detecting strcpy() in C++

test-query.ql

/**
 * @name Dangerous use of strcpy
 * @description strcpy is unsafe and can cause buffer overflows.
 * @kind problem
 * @precision high
 * @problem.severity error
 * @tags security;buffer-overflow
 * @security-severity 7.5  #(add it if you need)
 */

Explanation

1- Metadata (top of file):

• @name: name shown in GitHub Security.
• @description: explains the issue.
• @kind: type of result (problem, path-problem).
• @precision: confidence level (low, medium, high, very-high).
• @problem.severity: severity (error, warning, recommendation).
• @tags: classification (security, CWE, best practice).
• @security-severity: score 0.0–10.0 → mapped in GitHub:

How CodeQl interpret security.severity

2- CodeQL logic:

• import cpp: load CodeQL libraries for C++: https://codeql.github.com/docs/codeql-language-guides/codeql-library-for-cpp/#codeql-library-for-cpp
• from FunctionCall call: define a variable for each function call in the code.
• where call.getTarget().getName() = "strcpy": filter only calls to strcpy.
• select call, "Avoid using strcpy...": return each match with a message.

.ql file structure

Best Practices for Pull Requests

Beyond creating custom queries and configuring workflows, it is essential to enforce branch protection rules to ensure that vulnerable code is never merged into the main branch — whether by mistake or through a bypass/force merge of a PR.

Recommended Rulesets to enable in GitHub:

• Require status checks to pass → enforce that the CodeQL workflow must succeed before allowing a merge. It becomes a Required check.
• Require branches to be up to date before merging → the PR must be updated with the latest version of the target branch to avoid introducing unscanned code.

Require code scanning results → enforce that CodeQL scanning results are present with:

• Security alerts threshold: High or higher
• Blocking alert types: Errors (or All)

This means that if a High or Critical severity alert is detected, the merge will be blocked until it is fixed.

With this ruleset, a PR cannot be merged until the CodeQL workflow has completed successfully and all High/Critical security alerts are resolved.

Conclusion

In summary, custom CodeQL queries provide strong flexibility:

• They allow going beyond GitHub’s default GHAS rules.
• They let you tailor vulnerability detection to your project context.
• They reduce noise and false positives using query-filters.
• They enable you to surface the most relevant results in GitHub Security and SARIF exports.

With this approach, teams can build precise, efficient, and business-relevant security analysis on top of GitHub Advanced Security.