https://github.com/advanced-security/codeql-development-template
Copilot-native repository template for CodeQL query development
https://github.com/advanced-security/codeql-development-template
Last synced: 21 days ago
JSON representation
Copilot-native repository template for CodeQL query development
- Host: GitHub
- URL: https://github.com/advanced-security/codeql-development-template
- Owner: advanced-security
- License: mit
- Created: 2025-11-18T04:19:16.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2025-12-15T14:35:28.000Z (about 1 month ago)
- Last Synced: 2025-12-16T00:40:25.782Z (about 1 month ago)
- Language: CodeQL
- Size: 217 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
- awesome-codeql - codeql-development-template - Copilot-native repository template for CodeQL query development. Lowering the barrier to entry for CodeQL development through natural language and GitHub Copilot. A GitHub repository template for building custom CodeQL queries with AI assistance. This template provides a structured environment with prompts, instructions, and workflows designed to guide GitHub Copilot Coding Agent through the complete CodeQL development lifecycle. (Tooling & Environment / CodeQL AI & LLM Tooling)
README
# codeql-development-template
> **Lowering the barrier to entry for CodeQL development through natural language and GitHub Copilot**
A GitHub repository template for building custom CodeQL queries with AI assistance. This template provides a structured environment with prompts, instructions, and workflows designed to guide GitHub Copilot Coding Agent through the complete CodeQL development lifecycle.
## Background
This repository template enables developers to create custom CodeQL security queries with minimal CodeQL expertise by leveraging:
- **GitHub Copilot Coding Agent** for automated query development
- **Hierarchical prompt system** that guides AI through CodeQL tasks
- **Test-driven development methodology** for reliable query creation
- **Pre-configured workflows** for setup, testing, and validation
## Requirements
Before using this repository template, ensure your GitHub organization/account has:
- **GitHub Actions** enabled for running CI/CD workflows
- **GitHub Copilot Coding Agent** access for AI-assisted development
- **GitHub Advanced Security** (optional, but recommended)
## Getting Started
### Step 1: Create a New Repository from Template
1. Click the **"Use this template"** button at the top of this repository
2. Choose **"Create a new repository"**
3. Select your GitHub organization or personal account
4. Enter a repository name (e.g., `my-codeql-queries`)
5. Set the repository visibility (internal, private, or public)
6. Click **"Create repository"**
**Note:** The ['copilot-setup-steps' actions workflow](./.github/workflows/copilot-setup-steps.yml) will automatically set up the environment for Copilot Coding Agent (CCA), so local installation is optional and primarily useful for manual development.
### Step 2: Create an Issue for the CodeQL query you want to develop
1. **Navigate to Issues** in your new repository
2. **Click "New Issue"**
3. **Select "Request new CodeQL Query"** template
4. **Fill in the details:**
- Choose target language (e.g., Java, Python, JavaScript)
- Describe what the query should detect
- Provide code examples (optional but recommended)
- Specify severity level
5. **Submit the issue**
### Step 3: Assign Issue to `@copilot`
1. **Assign the issue** to `@copilot` (GitHub's Copilot Coding Agent user)
2. **Wait for Copilot** to process the issue and create a Pull Request
3. **Monitor progress** via the `Sessions` and/or comments for the new Pull Request
### Step 4: Review Pull Request created by Copilot Coding Agent
1. **Navigate to the generated Pull Request**
2. **Review the changes:**
- Query implementation (`.ql` files)
- Test cases (in `test/` directories)
- Query documentation (`.md` and `.qhelp` files)
3. **Check CI/CD results:**
- All tests pass
- Query compiles successfully
- Linting and formatting checks pass
4. **Review and approve** the PR
5. **Merge** to incorporate the query into your repository
## 📋 Available Issue Templates
| Template | Purpose |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| [Request new CodeQL Query](.github/ISSUE_TEMPLATE/query-create.yml) | Create a new CodeQL query to detect specific code patterns or vulnerabilities |
| [Update existing CodeQL Query](.github/ISSUE_TEMPLATE/query-update.yml) | Modify an existing query to improve accuracy or add new detection capabilities |
| [Improve Prompts/Instructions](.github/ISSUE_TEMPLATE/prompt-update.yml) | Contribute improvements to the AI guidance system |
## Repository Structure
After creating your first query, your repository will contain:
```text
codeql-development-template/
├── .github/
│ ├── instructions/ # Level 2: Language-specific Copilot instructions
│ ├── prompts/ # Level 3: High-level prompt templates
│ ├── ISSUE_TEMPLATE/ # Level 1: Entry points for Copilot workflows
│ └── workflows/ # CI/CD automation for testing and setup
├── languages/
│ └── {language}/ # Per-language development environments
│ ├── custom/ # Your custom queries (generated by Copilot)
│ │ ├── src/ # Query source files (.ql)
│ │ └── test/ # Query test cases
│ ├── example/ # Example queries for reference
│ └── tools/ # Development resources and AST exploration
│ ├── dev/ # Language-specific development guides
│ ├── src/ # PrintAST queries for exploring code structure
│ └── test/ # PrintAST test suites
├── resources/cli/ # CLI command reference documentation
│ ├── codeql/ # CodeQL CLI subcommand guides
│ └── qlt/ # QLT CLI subcommand guides
└── scripts/ # Setup and automation scripts
```
## How It Works
This template implements a **hierarchical prompt system** that maximizes GitHub Copilot's effectiveness:
1. **Issue Templates** provide structured input for query requirements
2. **Language-Specific Instructions** guide Copilot with relevant context
3. **High-Level Prompts** break down complex CodeQL workflows
4. **Tool-Specific Resources** provide CLI usage examples and patterns
5. **Test-Driven Development** ensures query accuracy through automated testing
The Copilot Coding Agent uses this hierarchy to:
- Understand your query requirements
- Generate appropriate CodeQL logic
- Create comprehensive test cases
- Validate query correctness
- Document the query properly
See [PROMPTS.md](PROMPTS.md) for details on the prompt hierarchy system.
## Supported Languages
The template supports CodeQL query development for:
| Language | CodeQL Library |
| --------------------- | -------------- |
| GitHub Actions | `actions` |
| C/C++ | `cpp` |
| C# | `csharp` |
| Go | `go` |
| Java | `java` |
| JavaScript/TypeScript | `javascript` |
| Python | `python` |
| Ruby | `ruby` |
## License
This repository template is available under the [MIT License](LICENSE).
## Maintainers
This repository template is maintained by the [CODEOWNERS](CODEOWNERS).
## Support
This repository template comes with no expectation or guarantee of support, with more details in the [SUPPORT.md](SUPPORT.md) document.