CodeQL Advanced

For an advanced understanding of CodeQL, you'll want to focus on three key areas: using its advanced features for custom analysis, deeply customizing the code scanning workflow, and mastering the techniques for writing your own powerful queries.

The table below summarizes the core areas of advanced CodeQL functionality.

| **Area of Focus** | **Key Advanced Capabilities** | **Primary Use Cases** |
| :--- | :--- | :--- |
| **Custom Query Development** | Writing custom QL queries, defining CodeQL classes, using recursion and transitive closures, creating query packs. | Finding organization-specific vulnerabilities, enforcing custom security rules, extending CodeQL's analysis. |
| **Workflow & Configuration** | Matrix builds for multiple languages, customizing build steps, specifying database locations, using `paths-ignore`. | Analyzing complex, multi-language projects; integrating with custom CI/CD pipelines; optimizing scan times. |
| **Advanced Analysis Techniques** | Taint tracking, data flow analysis, modeling custom sources and sinks. | Finding complex vulnerability patterns where data flows unsafely from a source to a sink. |

### 🔧 Advanced Setup and Customization

Moving beyond basic setup allows you to tailor CodeQL to complex project needs.

- **Custom Database Location**: While CodeQL manages databases automatically, you can specify a custom disk location using the `db-location` parameter with the `init` action. This is useful for custom workflow steps, like uploading the database as an artifact.
- **Multi-Language Analysis with Matrix Strategy**: For repositories containing multiple programming languages, using a **matrix strategy** in your GitHub Actions workflow is much more efficient than running separate jobs. This allows you to create a single job definition that automatically runs in parallel for each language you specify.
- **Optimizing Scans**: You can control when scans run to save resources. Use `on:pull_request:paths-ignore` and `on:pull_request:paths` to avoid triggering scans when only certain files (like documentation) are changed. Remember, this controls when the workflow *runs*, not which files are analyzed. To exclude files from the analysis itself, you must configure this separately within CodeQL.
- **Self-Hosted Runners & OS**: If you require a specific OS or use self-hosted runners, configure the `runs-on` field in your workflow. You can specify GitHub-hosted runners (e.g., `ubuntu-latest`) or self-hosted runners with appropriate labels.

### 🧠 Writing Custom CodeQL Queries

The true power of CodeQL is unlocked by writing custom queries, which use a declarative, object-oriented language called QL.

- **Creating Query Packs**: Custom queries are organized into "query packs." Initialize a new pack using `codeql pack init <scope>/<name>`. This creates a `qlpack.yml` file where you declare dependencies on standard CodeQL libraries (e.g., `codeql/java-all`).
- **QL Syntax and Logic**: A basic query follows this structure: `from Type x where P(x) select f(x)`. You can define your own **CodeQL classes** to model specific code patterns. For example, a class to represent all calls to `memcpy` would extend `FunctionCall` and define a characteristic predicate.
    ```ql
    class MemcpyCall extends FunctionCall {
      MemcpyCall() {
        this.getTarget().getName() = "memcpy"
      }
    }
    ```
- **Advanced Language Features**: CodeQL supports powerful logical operations.
    - **Quantification**: Use `exists` and `forall` for existential and universal quantification.
    - **Recursion & Transitive Closures**: Define recursive predicates to explore paths in code, like reachability in a control flow graph. CodeQL provides built-in support for transitive closures using the `*` (zero or more) and `+` (one or more) operators, which is more efficient than manual recursion.
- **Query Metadata**: Always include metadata in a comment block for your queries. This information is used in SARIF outputs and GitHub code scanning alerts.
    ```ql
    /**
     * @name Unsafe memcpy usage
     * @id cpp/unsafe-memcpy
     * @description Finds calls to memcpy that might be unsafe.
     * @kind path-problem
     * @problem.severity warning
     */
    ```

### 🔍 Mastering Taint Tracking and Data Flow

For finding complex vulnerabilities like command injection or SQL injection, **taint tracking** is CodeQL's most powerful feature. It identifies when user-controlled data ("tainted" data from a **source**) flows unsafely to a dangerous function (a **sink**).

The process involves extending CodeQL's data flow models. If you use a library that CodeQL doesn't model by default (like the Python library `sarge`), you must teach CodeQL about its sinks.

1.  **Model the Source**: Use the existing `ActiveThreatModelSource` to represent user-controllable data, such as HTTP request parameters.
2.  **Model the Sink**: Implement a predicate to tell CodeQL what constitutes a sink. For `sarge.run`, this would be a function call node where the function is `sarge.run`.
3.  **Create a Configuration Class**: Write a class that implements the `DataFlow::ConfigSig` interface, defining your `isSource` and `isSink` predicates. Then, instantiate this configuration with `DataFlow::Global<YourConfig>` to perform the analysis.

### 💡 Pro-Tips for Advanced Users

- **Leverage the Community**: The GitHub Security Lab runs a bounty program for CodeQL queries. The queries accepted into the standard set are valued for high precision, quality, and good documentation—excellent examples to learn from.
- **Understand the Ecosystem**: CodeQL is part of a broader landscape. Compared to tools like SonarQube, CodeQL's strength is its deep **semantic code analysis** and powerful, flexible query language for finding complex security vulnerabilities, though it may have a steeper learning curve.
- **Iterate and Refine**: Start queries simply and gradually add complexity. Use the VSCode CodeQL extension for a interactive environment to develop and test your queries against a code database.

I hope this advanced guide helps you leverage CodeQL's powerful capabilities for securing your codebase. If you have a specific vulnerability pattern or language you'd like to write a query for, I can offer more targeted guidance.