CodeQL Wrapper

A universal Python CLI wrapper for running CodeQL analysis seamlessly across any project architecture and CI/CD platform.

CodeQL Wrapper simplifies security analysis by providing a unified interface for CodeQL across monorepos, single repositories, and diverse CI/CD environments including Jenkins, GitHub Actions, Harness, Azure DevOps, and more.

Features

Prerequisites

Quick Start

Installation

Install CodeQL Wrapper from PyPI:

pip install codeql-wrapper

Basic Usage

Single Repository Analysis

Analyze a single repository with automatic language detection:

codeql-wrapper analyze /path/to/repository

Monorepo Analysis

Analyze all projects in a monorepo "using build-mode none" and upload results to GitHub Advanced Security:

codeql-wrapper analyze /path/to/monorepo --monorepo --upload-sarif

Targeted Analysis

Analyze only projects with changes (perfect for CI/CD):

codeql-wrapper analyze /path/to/repo --monorepo --only-changed-files --upload-sarif

Note: Ensure your GITHUB_TOKEN environment variable is set for SARIF upload functionality.

Advanced Configuration

For complex monorepo setups, create a .codeql.json configuration file in your repository root:

{
  "projects": [
    {
      "path": "./monorepo/project-java-1",
      "build-mode": "manual",
      "build-script": "./build/project-java-1.sh",
      "queries": ["java-security-extended"],
      "language": "java"
    },
    {
      "path": "./monorepo/project-java-1", 
      "language": "javascript"
    },
    {
      "path": "./monorepo/project-python-1",
      "build-mode": "none"
    },
    {
      "path": "./monorepo/project-python-javascript-cpp",
      "build-mode": "none",
      "language": "javascript"
    }
  ]
}

Configuration Options

CI/CD Integration

Examples and implementation guides available at:
https://github.com/ModusCreate-fernandomatsuo-GHAS/poc-codeql-wrapper

Documentation

Complete documentation is available at:
https://moduscreate-perdigao-ghas-playground.github.io/codeql-wrapper

Contributing

We welcome contributions! Please see the contributing guidelines for more information.

License

This project is licensed under the MIT License - see the LICENSE file for details.