Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (89 loc) · 4.56 KB

CONTRIBUTING.md

File metadata and controls

134 lines (89 loc) · 4.56 KB

Contributing

Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.

Contributions to this project are released to the public under the project's open source license.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Reporting Bugs

The best way to report a bug is to open an issue on GitHub. Please include as much information as possible, including:

  • A clear description of the problem
  • Steps to reproduce the problem
  • The expected behavior
  • The actual behavior

This will help us understand the issue and fix it more quickly.

Suggesting Enhancements

If you have an idea for a new feature or enhancement, please open an issue on GitHub.

Submitting Changes

  1. Fork and clone the repository
  2. Create a new branch for your changes
  3. Make your changes
  4. Write tests for your changes (if applicable)
  5. Run the tests to make sure everything is working
  6. Submit a pull request with a clear description of your changes

Requirements

Cloning the Repository

To clone the repository, run the following command:

git clone https://github.com/GitHubSecurityLab/codeql-extractor-bicep
git submodule update --init --recursive

![NOTE] This repository uses submodules to manage the Tree-Sitter grammar from the language.

Building Extractor Pack

There is a script to build the extractor pack. You can run it from the root of the repository:

./scripts/create-extractor-pack.sh

Testing CodeQL Libraries and Queries

To test the CodeQL libraries and queries, you can run the following command:

./scripts/run-tests.sh

Coverage Reporting

The project includes a coverage script to track CodeQL query coverage and generate reports. The script analyzes all available queries and provides detailed coverage statistics.

Running the Coverage Script

To update coverage data and generate a report:

python scripts/coverage.py

This will:

  • Load the existing .coverage.json file
  • Run codeql resolve queries to discover all available queries
  • Update the coverage data with query metadata
  • Generate a markdown coverage report
  • Update the README.md file with the latest coverage statistics

Coverage Script Options

The coverage script supports several command-line options:

# Generate only markdown output (useful for CI/CD)
python scripts/coverage.py --markdown-only

# Update coverage data but skip README.md update
python scripts/coverage.py --no-readme-update

# Show help and available options
python scripts/coverage.py --help

Coverage Report Features

The generated coverage report includes:

  • Coverage Badge: Dynamically colored based on coverage percentage
  • Summary Statistics: Total queries, covered queries, coverage percentage
  • Category Breakdown: Coverage by query category (Security, Diagnostics)
  • CWE Analysis: Coverage by Common Weakness Enumeration categories
  • Timestamp: When the report was last generated

Understanding Coverage Data

The coverage script tracks:

  • Total Queries: All queries discovered in ql/src/
  • Covered Queries: Queries that have associated tests (initially 0, updated as tests are added)
  • Categories: Query categories like security and diagnostics
  • CWE Categories: Security queries mapped to Common Weakness Enumeration identifiers

To mark a query as "covered", you'll need to create corresponding test files in the ql/test/ directory structure.

Resources