CodeQL Tracing Playground

A sample C++ project designed to test and explore CodeQL's build tracing behavior. This project includes multiple compilation units, generated code during build, conditional compilation, and various code patterns useful for analyzing how CodeQL traces build processes.

Project Structure

codeql-tracing-playground/
├── README.md
├── Makefile
├── src/
│   ├── main.cpp           # Main entry point, ties everything together
│   ├── utils.cpp          # String manipulation and logging utilities
│   ├── utils.h
│   ├── math_ops.cpp       # Math operations including recursive functions
│   ├── math_ops.h
│   └── generated/         # Directory for dynamically generated code
│       └── config.h       # Generated during build (not in git)
├── scripts/
│   └── generate_config.sh # Script that generates config.h during build
└── .gitignore

Features

This project is specifically designed to exercise different aspects of CodeQL tracing:

1. Multiple Compilation Units: 3 separate .cpp files compiled and linked together
2. Generated Code: config.h is generated during build with timestamp/version info
3. Conditional Compilation: DEBUG_MODE flag controls logging behavior
4. Cross-file Function Calls: Functions call across different compilation units
5. Recursive Functions: Factorial, Fibonacci, GCD, and Ackermann functions
6. Pointer Operations: Array operations and pointer arithmetic for security analysis
7. Intentionally Unsafe Code: unsafe_copy() uses strcpy for CodeQL to detect

Building the Project

Prerequisites

• C++ compiler with C++17 support (g++ or clang++)
• GNU Make
• Bash shell (for the config generation script)

Basic Build

# Build the release version
make

# Run the built program
make run

# Or build and run in one step
make run

Debug Build

# Build with debug flags (-g -DDEBUG_MODE)
make DEBUG=1

# Build and run debug version
make run DEBUG=1

Other Commands

# Show all available targets
make help

# Clean build artifacts
make clean

# Clean and rebuild
make rebuild

# Just generate the config.h file
make generate

Creating a CodeQL Database

CodeQL can trace this build to create a database for analysis. Here's how:

Prerequisites

1. Install the CodeQL CLI
2. Download the CodeQL standard libraries

Create Database

# Clean any previous build first
make clean

# Create CodeQL database (this traces the build)
codeql database create codeql-db --language=cpp --command="make"

# Or with debug flags
codeql database create codeql-db-debug --language=cpp --command="make DEBUG=1"

What to Observe in Tracing

When creating the database, CodeQL will trace:

1. Multiple compiler invocations: One for each .cpp file
2. Script execution: The generate_config.sh script runs before compilation
3. Preprocessor flags: -DDEBUG_MODE when building with DEBUG=1
4. Include paths: -I flags for header resolution
5. Linker invocation: Final linking of object files

Running Queries

# Run all C++ queries
codeql database analyze codeql-db codeql/cpp-queries --format=sarif-latest --output=results.sarif

# Run a specific query
codeql query run path/to/query.ql --database=codeql-db

# Look for security issues (e.g., buffer overflow from unsafe_copy)
codeql database analyze codeql-db codeql/cpp-queries:Security --format=sarif-latest --output=security-results.sarif

Code Patterns for Analysis

Security Patterns

• utils::unsafe_copy() - Uses strcpy, potential buffer overflow
• math_ops::offset_pointer() - Raw pointer arithmetic without bounds checking

Dataflow Patterns

• math_ops::factorial() - Simple recursive dataflow
• math_ops::fibonacci() - Multiple recursive calls
• math_ops::ackermann() - Deeply nested recursion
• demo_cross_file_calls() - Data flowing between compilation units

Control Flow Patterns

• math_ops::classify_number() - Multiple return paths
• Conditional compilation blocks with #ifdef DEBUG_MODE

Files Description

File	Description
src/main.cpp	Entry point, demonstrates all features
src/utils.cpp	String helpers, logging (with DEBUG_MODE behavior)
src/utils.h	Utils declarations
src/math_ops.cpp	Math operations, recursive functions, pointer ops
src/math_ops.h	Math operations declarations
scripts/generate_config.sh	Generates config.h with build info
Makefile	Build system with separate compile/link steps

License

MIT License - Feel free to use this for learning and testing CodeQL.