https://github.com/tweag/codeql-wrapper
A simple solution to run codeql anywhere
https://github.com/tweag/codeql-wrapper
codeql python
Last synced: 23 days ago
JSON representation
A simple solution to run codeql anywhere
- Host: GitHub
- URL: https://github.com/tweag/codeql-wrapper
- Owner: tweag
- License: mit
- Created: 2025-07-04T18:00:45.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-11-18T10:40:01.000Z (3 months ago)
- Last Synced: 2026-01-27T00:05:04.236Z (30 days ago)
- Topics: codeql, python
- Language: Python
- Homepage:
- Size: 1.07 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-codeql - tweag/codeql-wrapper - Universal Python CLI wrapper for CodeQL analysis across monorepos and CI/CD platforms (Tooling & Environment / CodeQL CLI Tooling)
README
# CodeQL Wrapper
[](https://github.com/tweag/codeql-wrapper/actions/workflows/lint.yml)
[](https://github.com/tweag/codeql-wrapper/actions/workflows/build.yml)
[](https://badge.fury.io/py/codeql-wrapper)
[](https://pypi.org/project/codeql-wrapper/)
[](https://tweag.github.io/codeql-wrapper/)
[](https://opensource.org/licenses/MIT)
***
> **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
**Universal Support**\
Works with both monorepos and single repositories
**CI/CD Agnostic**\
Seamless integration across all major CI/CD platforms
**Smart Language Detection**\
Automatically detects and analyzes multiple programming languages
**SARIF Integration**\
Built-in support for SARIF upload to GitHub Advanced Security
**Performance Optimized**\
Parallel processing and intelligent resource management
**Auto-Installation**\
Automatically downloads and manages CodeQL CLI
**Flexible Configuration**\
JSON-based configuration for complex project structures
## Prerequisites
| Requirement | Version/Details |
|-------------|-----------------|
| **Python** | 3.9 or higher |
| **Git** | For repository analysis |
| **GitHub Token** | Required for SARIF upload functionality |
***
## Quick Start
### Installation
Install CodeQL Wrapper from PyPI:
```bash
pip install codeql-wrapper
```
### Basic Usage
#### Single Repository Analysis
Analyze a single repository with automatic language detection:
```bash
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:
```bash
codeql-wrapper analyze /path/to/monorepo --monorepo --upload-sarif
```
#### Targeted Analysis
Analyze only projects with changes (perfect for CI/CD):
```bash
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:
Click to view example configuration
```json
{
"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
| Option | Description | Values |
|--------|-------------|---------|
| `path` | Relative path to the project | Any valid path |
| `build-mode` | How to build the project (default=none) | `none`, `manual`, `autobuild` |
| `build-script` | Custom build script path | Path to executable script |
| `queries` | CodeQL query suites to run | Array of query suite names |
| `language` | Target language (default=auto-detect) | Any supported language |
***
## CI/CD Integration
| Platform | Status |
|----------|--------|
| **GitHub Actions** | ✅ Supported |
| **Harness** | ✅ Supported |
| **Circle CI** | ✅ Supported |
| **Azure Pipelines** | ✅ Supported |
| **Jenkins** | ✅ Supported |
**Examples and implementation guides available at:**\
***
## Documentation
**Complete documentation is available at:**\
***
## Contributing
We welcome contributions! Please see the [contributing guidelines](CONTRIBUTING.md) for more information.
***
## License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
***
**Made with ❤️ by the Modus Create team**